# GitHub Repo Readme API (https://www.socialcrawl.dev/platforms/github/repo-readme)

> Returns the repository's README in raw form (the file contents, not base64-wrapped). The fetcher sets `Accept: application/vnd.github.raw+json` so the response body is the actual file. Useful for content discovery and AI-grounding workflows.

TL;DR: `GET /v1/github/repo/readme` costs 1 credit per call and returns SocialCrawl's unified JSON schema. Single x-api-key auth, 100 free credits on signup.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `url` | yes | GitHub repo URL — `https://github.com/{owner}/{repo}`. |

## Code example

```bash
curl "https://www.socialcrawl.dev/v1/github/repo/readme?url=https%3A%2F%2Fgithub.com%2Foctocat%2FHello-World" \
  -H "x-api-key: sc_YOUR_API_KEY"
```

## FAQ

### How do I get a repo's README with an API?

Send a GET request to /v1/github/repo/readme with the repository URL in the url parameter. SocialCrawl returns the README as decoded text (the raw markdown ready to render) along with its file path and byte size.

### Is the README returned as Base64 or plain text?

Plain decoded text. GitHub's own contents API returns README content Base64-encoded, which you then have to decode. SocialCrawl decodes it for you and returns the raw markdown directly, so you can render or parse it immediately.

### Which README file does it return?

The repository's canonical README, the same file GitHub renders on the repo home page, whether it is README.md, README.rst, or a docs-folder variant. The response includes the actual file path so you know which one was resolved.

### Can I use this to feed READMEs into an LLM?

Yes. Because the content comes back as clean decoded markdown, it drops straight into a prompt or embedding pipeline. Pair it with the repo endpoint for metadata when you are summarising or classifying projects at scale.

### How much does the GitHub README API cost?

Each request costs 1 credit on the standard tier. New accounts get 100 free credits with no credit card required, enough to pull around 100 READMEs before you pay. There is no extra charge for the decoding step.

See the full GitHub API: https://www.socialcrawl.dev/platforms/github

## Pricing

- Standard endpoints: 1 credit per call
- Advanced endpoints: 5 credits per call
- Premium endpoints: 10 credits per call
- 100 free credits on signup, no credit card required. Cached responses cost 0 credits. Credit packs never expire.
- Full pricing: https://www.socialcrawl.dev/pricing

## Explore with AI

Questions this API answers, phrased for an AI assistant:

- How to get a GitHub README as plain text with an API
- What does the SocialCrawl GitHub README API return?