API overview

shithub exposes a small REST API at /api/v1/. The user-facing API is PAT-authenticated, JSON-bodied, and CSRF-exempt. The Actions runner API under the same prefix uses runner registration tokens plus per-job JWTs instead of PATs.

Status. The API is intentionally narrow today. Endpoints currently shipped: GET /api/v1/user, the /api/v1/repos/{owner}/{repo}/check-runs family, and the /api/v1/user/starred* stars endpoints, plus the Actions lifecycle routes in Actions workflow API. Other sections of this reference (Issues, Pull requests, Webhooks, etc.) describe the planned shape and will land in subsequent sprints. Pages that document planned-only endpoints carry a banner.

Authentication

Every API request requires a personal access token. See Personal access tokens for how to create one. Runner endpoints documented in Actions runner API are the exception; they reject PATs and require runner credentials.

Authorization: Bearer shp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Authorization: token shp_… is also accepted as a synonym.

A request with no Authorization header — or with an invalid / expired / revoked PAT — returns 401 Unauthorized with the canonical JSON error envelope. The response also carries a WWW-Authenticate: Bearer realm="shithub", error="invalid_token" challenge so HTTP-aware clients can reauthenticate cleanly.

{"error": "invalid token"}

A request whose PAT lacks the scope a route requires returns 403 Forbidden with the required scope surfaced in the X-Accepted-OAuth-Scopes response header. The token's actual scopes are echoed on every PAT-authenticated response (including errors) via X-OAuth-Scopes, so clients can build precise "missing scope X, present scopes Y, Z" error messages without parsing the body:

HTTP/1.1 403 Forbidden
X-OAuth-Scopes: user:read
X-Accepted-OAuth-Scopes: repo:write
Content-Type: application/json; charset=utf-8

{"error":"token lacks required scope: repo:write"}

Scopes

Every route declares the scope(s) a token must hold. See scopes table.

Scopes are grants only — a token cannot do something the underlying user cannot. Holding repo does not let a token push to a repo the user has no access to.

Conventions

• Base URL: https://<your-instance>/api/v1/
• Content type: application/json; charset=utf-8 for request bodies and responses.
• Error responses: {"error": "<short message>"} with a conventional HTTP status.
• Cache-Control: every API response sets no-store.
• Pagination: list endpoints accept ?per_page= (default 30, max 100) and return an RFC 8288 Link: header with next, prev, first, last URLs. URLs are absolute and use the instance's configured public base URL. Forward-only feeds emit only next / prev (no first / last) when totals are expensive to compute. Cursor pagination on hot lists uses ?cursor=… and returns the next cursor in the same Link: header.
• Body cap: request bodies are capped at 256 KiB. Larger payloads return 413.
• Rate limits: every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers (Unix timestamp). Exceeding the limit returns 429 with the canonical error envelope, a Retry-After header (seconds), and X-RateLimit-Remaining: 0. Defaults: 5000 / hour for PAT callers (keyed by token id) and 60 / hour for anonymous callers (keyed by remote IP). Operators tune via SHITHUB_RATELIMIT__API__AUTHED_PER_HOUR and SHITHUB_RATELIMIT__API__ANON_PER_HOUR.
• Request id: every response echoes X-Request-Id. If the caller sends one (matching [a-z0-9/:_-]{1,128}) it's reused; otherwise the server generates a fresh 16-byte hex id. Quote this id in support reports — it correlates against the server logs.

Capability discovery

GET /api/v1/meta is unauthenticated and returns the server's version stamp plus a list of feature capability strings. Clients use it to gate optional features without trial-and-error:

{
  "version": "v0.2.0",
  "commit": "abc1234",
  "built_at": "2026-05-12T03:00:00Z",
  "capabilities": ["pat-auth", "check-runs", "stars", "actions-lifecycle"]
}

New capability identifiers are appended as feature batches land; existing entries are stable.

Versioning

The path prefix /api/v1/ is the version. Backwards-incompatible changes will land under /api/v2/. Additions (new endpoints, new fields on responses) are not breaking and land under v1.

Date format

All timestamps are RFC 3339 UTC: 2026-05-09T16:30:00Z.

ID stability

Numeric IDs are stable for the life of the row; reusing a name slot doesn't reuse the ID. URLs that take a {owner} and {repo} will redirect after a rename — but external callers should prefer numeric IDs where the API exposes them.