{% extends "docs/base.html" %} {% block docs_content %}

API documentation

HTTP API usage, authentication, and paging.

API docs OpenAPI JSON File uploads docs Attachments API Timers API Locks API Skills API CLI docs Skills docs Work docs
New to the concepts behind these endpoints? Start with repository scope, threads and pulls, hosted skills, or events and activity. For deferred or exclusive work, continue with timers and lease locks.

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. 

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:

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:

{% endblock %}