# 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?