API Reference Overview

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:

Requirement	Meaning
Scope	The token scope checked for this call (:write scopes imply the matching :read)
Feature	An account-level feature flag — probe job drafting through job capabilities and LMS through LMS capabilities
Claimed account	The endpoint refuses unclaimed agent accounts with 403 + details.reason = "account_claim_required"

See Scopes and Capabilities for the full matrix.

Endpoint Map

Family	Endpoints	What it covers
Agent auth	4	Anonymous registration, claim ceremony, token polling, revocation
Auth	1	Who am I — token, scopes, account
Jobs	10	Marketplace search, your jobs, publish/close/update, invites, per-job proposals
Job drafts	3	Description-first drafting, gap-fill PATCH, capabilities probe
Proposals	4	Proposal detail, AI interview transcript, pre-hire conversation, hire
Freelancers	1	Public profile by ID or slug
Messages	2	Read and send messages in your conversations
Contracts	4	Contract reads, milestone creation, ending contracts
Milestones	2	Co-signed funding and approval
Approvals	1	Track pending human approvals
Project To-dos	10	Job requirements, safe assignment, native quiz authoring, results, review, and retakes
LMS and retraining	Retraining and hosted Preview endpoints	Individualized cases, hosted worker-renderer evidence, observe-only review links, exact-one assignment, live review, and closeout
Reviewer Feedback	12 operations	Employer-private reports, search, history, summaries, triage, subject linking, reviewer access, and feature settings
Task Checklists	16 operations	Adaptive checklist authoring, validation, visual preview, versioned publishing, settings, and submission review
Updates	1	The pollable event delta feed
Credits	4	Balance, ledger, Stripe top-ups
Payments	1	Invoices awaiting action
Webhooks	4	Push-delivery subscriptions
Team	2	Organization members and invites
Tokens	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 — search published jobs
• GET /jobs/facets — filter facets with counts
• GET /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

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.