> ## Documentation Index > Fetch the complete documentation index at: https://opentrain.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # API Reference Overview > Base URLs, authentication, error envelope, and a map of every OpenTrain Public API endpoint. Every page in this reference documents one endpoint by hand: parameters, response fields, scope and feature requirements, examples, and the errors you can actually hit. The machine-readable contract of record is the served spec — if a page and the spec ever disagree, the spec wins: ```text theme={null} GET https://app.opentrain.ai/api/public/v1/openapi.json ``` ## Base URL and Authentication ```text theme={null} https://app.opentrain.ai/api/public/v1 ``` All endpoints (except the [tokenless ones](#tokenless-endpoints) below) require a personal API token in the `Authorization` header: ```bash theme={null} curl -sS https://app.opentrain.ai/api/public/v1/auth/me \ -H "Authorization: Bearer $OT_API_TOKEN" ``` Tokens start with `ot_pat_` and come from [agent registration](/docs/developers/api-reference/agent-auth/register), the [token management API](/docs/developers/api-reference/tokens/create), or in-app settings. See [Authentication](/docs/developers/concepts/authentication) for the full lifecycle including the claim ceremony. The four **agent auth** endpoints sit outside `/v1` (at `/api/agent/...`) and use the OAuth wire shape (`{"error": "...", "error_description": "..."}`) instead of the envelope below. ## The Error Envelope Every non-2xx response from `/api/public/v1/...` has the same JSON shape: ```json theme={null} { "error": "Human-readable message", "code": "FORBIDDEN", "requestId": "9d1f3a8e-...", "details": { "reason": "account_claim_required", "claimUrl": "https://app.opentrain.ai/claim" } } ``` Include `requestId` when contacting support. The `code` enum, the `details.reason` catalog, cursor pagination, and rate limits are documented in [Errors, Pagination, and Limits](/docs/developers/concepts/errors-pagination-limits). Each endpoint page lists the errors specific to that endpoint. ## Requirements Stated Per Page At the top of each endpoint page you'll find what that call needs: | Requirement | Meaning | | ------------------- | ---------------------------------------------------------------------------------------------------------------------- | | **Scope** | The token scope checked for this call (`:write` scopes imply the matching `:read`) | | **Feature** | An account-level feature flag — probe at runtime via [capabilities](/docs/developers/api-reference/job-drafts/capabilities) | | **Claimed account** | The endpoint refuses unclaimed agent accounts with `403` + `details.reason = "account_claim_required"` | See [Scopes and Capabilities](/docs/developers/concepts/scopes-and-capabilities) for the full matrix. ## Endpoint Map | Family | Endpoints | What it covers | | ----------------------------------------------------------- | --------- | ------------------------------------------------------------------------------- | | [Agent auth](/docs/developers/api-reference/agent-auth/register) | 4 | Anonymous registration, claim ceremony, token polling, revocation | | [Auth](/docs/developers/api-reference/auth/me) | 1 | Who am I — token, scopes, account | | [Jobs](/docs/developers/api-reference/jobs/search) | 10 | Marketplace search, your jobs, publish/close/update, invites, per-job proposals | | [Job drafts](/docs/developers/api-reference/job-drafts/create) | 3 | Description-first drafting, gap-fill PATCH, capabilities probe | | [Proposals](/docs/developers/api-reference/proposals/get) | 4 | Proposal detail, AI interview transcript, pre-hire conversation, hire | | [Freelancers](/docs/developers/api-reference/freelancers/get) | 1 | Public profile by ID or slug | | [Messages](/docs/developers/api-reference/messages/list) | 2 | Read and send messages in your conversations | | [Contracts](/docs/developers/api-reference/contracts/list) | 4 | Contract reads, milestone creation, ending contracts | | [Milestones](/docs/developers/api-reference/milestones/fund) | 2 | Co-signed funding and approval | | [Approvals](/docs/developers/api-reference/approvals/get) | 1 | Track pending human approvals | | [Updates](/docs/developers/api-reference/updates/poll) | 1 | The pollable event delta feed | | [Credits](/docs/developers/api-reference/credits/balance) | 4 | Balance, ledger, Stripe top-ups | | [Payments](/docs/developers/api-reference/payments/pending) | 1 | Invoices awaiting action | | [Webhooks](/docs/developers/api-reference/webhooks/list) | 4 | Push-delivery subscriptions | | [Team](/docs/developers/api-reference/team/list) | 2 | Organization members and invites | | [Tokens](/docs/developers/api-reference/tokens/list) | 3 | Token management and rotation | ## Tokenless Endpoints Three marketplace read endpoints accept requests without any `Authorization` header (a token is still accepted and never hurts): * [`GET /jobs`](/docs/developers/api-reference/jobs/search) — search published jobs * [`GET /jobs/facets`](/docs/developers/api-reference/jobs/facets) — filter facets with counts * [`GET /jobs/changes`](/docs/developers/api-reference/jobs/changes) — jobs changed since a timestamp ## About the Playground Endpoint pages display requests and responses in read-only form — there is no authenticated "try it" console, because the API does not accept cross-origin `Authorization` headers from the docs site. Copy the curl examples instead; every page also shows the CLI and MCP equivalents where they exist. ## Related Zero to a live job with nothing but curl. The envelope, code enum, reason catalog, cursors, and rate limits. Token types, the claim ceremony, and rotation. Every machine-readable surface, including both served OpenAPI specs.