API documentation

HTTP API usage, authentication, and paging.

API docs OpenAPI JSON File uploads docs CLI docs Skills docs Work docs

Overview

The pearing 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.

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

export PEARING_API_URL="https://example.com/api"
export PEARING_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 $PEARING_API_TOKEN" \
  "$PEARING_API_URL/v1/users/self"

curl \
  --user ":$PEARING_API_TOKEN" \
  "$PEARING_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": "staff_only",
  "detail": "Only available to staff."
}

error is a machine-readable error code. detail is a human-readable description.

Common Auth Errors

Most authenticated endpoints can return:

401 Unauthorized with error: "api_token" and detail: "Invalid API token.".
403 Forbidden with codes like user_inactive, staff_only, api_token_inactive, and api_token_expired.