# GitHub (/docs/github)

GitHub profiles, repositories, READMEs, releases, issues and pull requests, plus two composites for project and developer intelligence

Read GitHub without holding a personal access token, minding a rate limit, or writing the pagination yourself: user profiles, repository metadata, README text, releases, the issue and pull-request stream, and cross-repository issue search. On top of the raw reads sit two composites, a one-call project dossier and a contribution-velocity report.

Base URL: `/v1/github/...`

  Two identifier shapes, never mixed. `profile`, `profile/repos` and
  `user/profile-velocity` take a `handle`. Every other endpoint takes a `url`:
  the repo endpoints want `https://github.com/{owner}/{repo}`, and the issue
  endpoints want the issue or PR's own HTML URL.

## Quickstart

### 1. Read a person

Users are identified by `handle`.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/github/profile?handle=octocat" \
  -H "x-api-key: YOUR_API_KEY"
```

### 2. Read a repository

Everything repository-shaped is identified by a full URL.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/github/repo?url=https://github.com/facebook/react" \
  -H "x-api-key: YOUR_API_KEY"
```

## People and their work

| Endpoint                               | Credits | What it returns                                                                                                                        | Key parameters                                            |
| -------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `GET /v1/github/profile`               | 1       | Login, name, avatar, bio, follower and following counts, public repository count, account creation date                                | `handle`                                                  |
| `GET /v1/github/profile/repos`         | 1       | What a person has published                                                                                                            | `handle`, `type`, `sort`, `direction`, `per_page`, `page` |
| `GET /v1/github/user/profile-velocity` | 10      | Pull requests opened and merged, the outside repositories a person contributes to, and their own repositories, in one activity picture | `handle`, `depth`                                         |

`type` is `all`, `owner` or `member`, and `sort` is `created`, `updated`, `pushed` or `full_name`. On `profile-velocity`, `depth` accepts `quick`, `default` or `deep` and trades upstream calls against how much per-repository detail comes back. It costs 10 credits, which is the price of not reconstructing a contribution graph yourself.

## Repositories

| Endpoint                       | Credits | What it returns                                                                                                      | Key parameters            |
| ------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| `GET /v1/github/repo`          | 1       | Full name, description, stars, forks, open issues, watchers, main language, creation date                            | `url`                     |
| `GET /v1/github/repo/readme`   | 1       | The README as plain file content, ready to read or feed to a model                                                   | `url`                     |
| `GET /v1/github/repo/releases` | 1       | Recent releases newest first, each with its tag, name, notes, publish date, prerelease flag, and downloadable assets | `url`, `per_page`, `page` |

## Issues and pull requests

GitHub treats pull requests as issues, and so does this API. Every item carries `post.ext.type` of `issue` or `pull_request`.

| Endpoint                        | Credits | What it returns                                                                    | Key parameters                                                                     |
| ------------------------------- | ------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `GET /v1/github/repo/issues`    | 1       | A repository's issues and pull requests together                                   | `url`, `type`, `state`, `labels`, `sort`, `direction`, `since`, `per_page`, `page` |
| `GET /v1/github/issue`          | 1       | One item by its HTML URL, whether that URL points at `/issues/{n}` or `/pull/{n}`  | `url`                                                                              |
| `GET /v1/github/issue/comments` | 1       | The discussion under one issue or PR, oldest first                                 | `url`, `since`, `per_page`, `page`                                                 |
| `GET /v1/github/search`         | 1       | Issues and pull requests across all of GitHub, using GitHub's own qualifier syntax | `query`, `sort`, `order`, `per_page`, `page`                                       |

The `type` filter on `repo/issues` narrows to issues or pull requests. `state` is `open`, `closed` or `all`, `labels` is comma-separated, and `since` sets an ISO-8601 lower bound.

On `search`, `repo:`, `label:`, `is:` and the rest all work as you would type them into the site.

```bash title="cURL"
# Open bug reports across a whole org, newest first
curl "https://www.socialcrawl.dev/v1/github/search?query=org%3Avercel+is%3Aissue+is%3Aopen+label%3Abug&sort=created&order=desc" \
  -H "x-api-key: YOUR_API_KEY"
```

## Composites

Two endpoints bundle several reads into one answer.

| Endpoint                         | Credits | What it returns                                                                                                                       | Key parameters |
| -------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| `GET /v1/github/repo/top-issues` | 5       | Exactly two issues: the top feature request, chosen by reactions, and the top complaint, chosen by how much it is being discussed     | `url`          |
| `GET /v1/github/repo/dossier`    | 5       | Repository details, a README excerpt, the latest three releases, and the same top feature request and top complaint, in a single call | `url`          |

`top-issues` is the fast read on what users most want and most dislike without paging the whole issue list. `dossier` is four separate endpoints' worth of context for one call, and it is the right shape when you are summarising a project rather than monitoring it.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/github/repo/dossier?url=https://github.com/facebook/react" \
  -H "x-api-key: YOUR_API_KEY"
```

## All endpoints

## Platform notes

- **Two identifier shapes, and they are not mixed.** `profile`, `profile/repos` and `user/profile-velocity` take a `handle`. Everything else takes a `url`. Handles are 1 to 39 characters, alphanumeric with non-consecutive hyphens.
- **Pagination is page-based, starting at 1.** Every list endpoint here takes `per_page` (1-100, default 30) and `page`. There are no cursors on this platform.
- **Public data only.** These endpoints read what an anonymous visitor sees, so private repositories, private forks and organisation-internal issues are not reachable through any of them.
- **`since` filters on updated time, not created time**, on both `repo/issues` and `issue/comments`.
- **Pull requests appear in `repo/issues` and in `search` results** unless you filter them out.
- All endpoints use `GET` with query parameters, and responses follow the unified SocialCrawl schema.

## Next steps

- [Prism](/docs/prism.md): org-radar, devtool-pulse, and launch-echo build on these reads.
- [Hacker News](/docs/hackernews.md): The other half of a developer-ecosystem read.
- [Pagination](/docs/pagination.md): Page, cursor, and offset styles across the API.