# GitHub (/docs/github)



GitHub [#github]

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 — that answer the
questions developer-tooling and recruiting teams actually ask.

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

<Callout>
  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.
</Callout>

Most of the surface is 1 credit. `/v1/github/repo/top-issues` and `repo/dossier` are 5, and
`/v1/github/user/profile-velocity` is 10.

Getting started [#getting-started]

Every endpoint is a `GET` with query parameters and an `x-api-key` header. Users are identified
by `handle`; everything repository-shaped is identified by a full URL.

```bash
# A person
curl "https://www.socialcrawl.dev/v1/github/profile?handle=octocat" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

# A repository
curl "https://www.socialcrawl.dev/v1/github/repo?url=https://github.com/facebook/react" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"
```

People and their work [#people-and-their-work]

`profile` returns a user's login, name, avatar, bio, follower and following counts, public
repository count, and when the account was created. `/v1/github/profile/repos` lists what they
have published, with `type` (`all`, `owner`, `member`), `sort` (`created`, `updated`, `pushed`,
`full_name`) and `direction` to shape the list, page-paginated with `per_page` up to 100.

`user/profile-velocity` is the deeper read: pull requests opened and merged, the outside
repositories a person contributes to, and their own repositories, assembled into one activity
picture. `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 [#repositories]

`repo` is the overview — full name, description, stars, forks, open issues, watchers, main
language, creation date. Two endpoints go past what that summary carries:
`/v1/github/repo/readme` returns the README as plain file content, ready to read or feed to a
model, and `/v1/github/repo/releases` returns the most recent releases newest first, each with
its tag, name, release notes, publish date, prerelease flag and downloadable assets.

Issues and pull requests [#issues-and-pull-requests]

GitHub treats pull requests as issues, and so does this API. `/v1/github/repo/issues` returns
both, each item carrying `post.ext.type` of `issue` or `pull_request`, and the `type` filter
narrows to one or the other. Combine it with `state` (`open`, `closed`, `all`), a
comma-separated `labels` list, `sort` (`created`, `updated`, `comments`) and `since` for an
ISO-8601 lower bound. `/v1/github/issue` returns one item by its HTML URL, whether that URL
points at `/issues/{n}` or `/pull/{n}`, and `/v1/github/issue/comments` returns the discussion
under it, oldest first.

`GET /v1/github/search?query=…` searches issues and pull requests across all of GitHub using
GitHub's own qualifier syntax, so `repo:`, `label:`, `is:` and the rest all work as you would
type them into the site.

```bash
# 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: $SOCIALCRAWL_API_KEY"
```

Composites [#composites]

Two endpoints bundle several reads into one answer.

`repo/top-issues` (5 credits) returns exactly two issues for a repository: the top feature
request, chosen by reactions, and the top complaint, chosen by how much it is being discussed.
It is the fast read on what users most want and most dislike without paging the whole issue
list.

`repo/dossier` (5 credits) returns the repository details, a README excerpt, the latest three
releases, and the same top feature request and top complaint, in a single call. That 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
curl "https://www.socialcrawl.dev/v1/github/repo/dossier?url=https://github.com/facebook/react" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"
```

Endpoints [#endpoints]

<PlatformEndpoints platform="github" />

Read this before you build [#read-this-before-you-build]

**Two identifier shapes, and they are not mixed.** `profile`, `profile/repos` and
`user/profile-velocity` take a `handle`. Everything else 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. Handles are 1-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.

Notes [#notes]

* All endpoints use `GET` with query parameters
* Authentication via the `x-api-key` header
* Responses follow the unified SocialCrawl schema
* `since` on `repo/issues` and `issue/comments` filters on *updated* time, not created time
* Pull requests appear in `repo/issues` and in `search` results unless you filter them out