Skip to main content
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: 
GET https://app.opentrain.ai/api/public/v1/openapi.json

​
Base URL and Authentication

https://app.opentrain.ai/api/public/v1
All endpoints (except the tokenless ones below) require a personal API token in the Authorization header: 
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, the token management API, or in-app settings. See 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: 
{
  "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. 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:
RequirementMeaning
ScopeThe token scope checked for this call (:write scopes imply the matching :read)
FeatureAn account-level feature flag — probe at runtime via capabilities
Claimed accountThe endpoint refuses unclaimed agent accounts with 403 + details.reason = "account_claim_required"
See Scopes and Capabilities for the full matrix.

​
Endpoint Map

FamilyEndpointsWhat it covers
Agent auth4Anonymous registration, claim ceremony, token polling, revocation
Auth1Who am I — token, scopes, account
Jobs10Marketplace search, your jobs, publish/close/update, invites, per-job proposals
Job drafts3Description-first drafting, gap-fill PATCH, capabilities probe
Proposals4Proposal detail, AI interview transcript, pre-hire conversation, hire
Freelancers1Public profile by ID or slug
Messages2Read and send messages in your conversations
Contracts4Contract reads, milestone creation, ending contracts
Milestones2Co-signed funding and approval
Approvals1Track pending human approvals
Updates1The pollable event delta feed
Credits4Balance, ledger, Stripe top-ups
Payments1Invoices awaiting action
Webhooks4Push-delivery subscriptions
Team2Organization members and invites
Tokens3Token management and rotation

​
Tokenless Endpoints

Three marketplace read endpoints accept requests without any Authorization header (a token is still accepted and never hurts):

​
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.

Quickstart: Raw HTTP

Zero to a live job with nothing but curl.

Errors, Pagination, and Limits

The envelope, code enum, reason catalog, cursors, and rate limits.

Authentication

Token types, the claim ceremony, and rotation.

Agent Discovery

Every machine-readable surface, including both served OpenAPI specs.