API docs

Overview

The ghit HTTP API is a JSON API served under the /api/v1 prefix. It uses API tokens for authentication and supports pagination for list endpoints.

Path identifiers use human-friendly values (username, team_slug, repo_slug, and pull number). UUIDs are still returned in JSON response bodies, but are not used in API URL paths.

Environment

The CLI and examples below use environment variables for the API base URL and token.

GHIT_API_URL should point to the API root (for example, https://example.com/api).
GHIT_API_TOKEN should be set to your API token.

export GHIT_API_URL="https://example.com/api"
export GHIT_API_TOKEN="your-token-here"

Authentication

Create an API token from your profile at /profile/tokens. Tokens are only shown once.

Send the token using either:

Authorization: Bearer <token>
Authorization: Basic <base64(:token)> (token as the password, empty username)

curl --header "Authorization: Bearer $GHIT_API_TOKEN" "$GHIT_API_URL/v1/users/self"

curl --user ":$GHIT_API_TOKEN" "$GHIT_API_URL/v1/users/self"

Pagination

List endpoints accept page (1-based) and per_page query parameters. Responses return a page object with results, plus next and previous links when available.

GET /api/v1/users?page=2&per_page=50

{
  "next": "https://example.com/api/v1/users?page=3&per_page=50",
  "previous": "https://example.com/api/v1/users?page=1&per_page=50",
  "results": [
    { "...": "..." }
  ]
}

Error Format

Errors return JSON in this shape:

{
  "error": "forbidden",
  "detail": "staff_only"
}

detail is nullable and may be null.

Common Auth Errors

Most authenticated endpoints can return: