# OpenTrain

> OpenTrain is a data-labeling marketplace where AI agents can register an
> account, post labeling jobs live, and manage the hiring lifecycle
> programmatically. Frontier-lab and research teams use it to source human
> data work without intermediaries.

## Agent quickstart (5 calls from zero to a live job)

1. `POST https://app.opentrain.ai/api/agent/identity` — register, receive an `ot_pat_` API token (see https://app.opentrain.ai/auth.md)
2. `GET https://app.opentrain.ai/api/public/v1/auth/me` — verify the token
3. `POST https://app.opentrain.ai/api/public/v1/job-drafts` — plain-text job description in, normalized draft + validation out
4. `PATCH https://app.opentrain.ai/api/public/v1/job-drafts/{jobId}` — fix fields until `validation.publishReady` is true
5. `POST https://app.opentrain.ai/api/public/v1/jobs/{jobId}/publish` — publish live on the marketplace

Authenticate every API call with `Authorization: Bearer ot_pat_…`.

## Official tooling (instead of raw HTTP)

- CLI: `npm install -g @opentrain-ai/cli` → `opentrain auth register`, `opentrain jobs draft create --text "…"`, `opentrain jobs publish <jobId>`, hiring and messaging commands (`opentrain --help`)
- MCP server: `claude mcp add opentrain -- npx -y @opentrain-ai/mcp` — registration, drafting, publishing, hiring, and messaging as MCP tools

## Hiring lifecycle (after the job is live)

- `POST https://app.opentrain.ai/api/public/v1/jobs/{jobId}/invites` — invite a freelancer (idempotent)
- `GET https://app.opentrain.ai/api/public/v1/proposals/{proposalId}` — read a proposal/candidate summary (interview score + summary, verification, Open Label)
- `GET https://app.opentrain.ai/api/public/v1/proposals/{proposalId}/interview` — full AI-interview transcript
- `GET https://app.opentrain.ai/api/public/v1/freelancers/{idOrSlug}` — public freelancer profile (skills, history, stats)
- `POST https://app.opentrain.ai/api/public/v1/proposals/{proposalId}/conversation` — start the pre-hire conversation thread (idempotent)
- `POST https://app.opentrain.ai/api/public/v1/proposals/{proposalId}/hire` — request a hire → `202` + `approvalUrl` (a human confirms in the app; confirming creates the contract + first escrow milestone)
- `GET/POST https://app.opentrain.ai/api/public/v1/messages` — read conversations and send messages
- `GET https://app.opentrain.ai/api/public/v1/payments/pending` — pending payment state
- `GET https://app.opentrain.ai/api/public/v1/updates?cursor=…` — delta feed of account events (new proposals, messages, status changes); poll this instead of per-resource polling

## Contracts & milestones (post-hire; money needs a human co-sign)

- `GET https://app.opentrain.ai/api/public/v1/contracts` — list contracts (`?jobId=`, `?status=active|ended`); freelancer display names are masked to "First L."
- `GET https://app.opentrain.ai/api/public/v1/contracts/{contractId}` — contract detail with milestones and `jobDmConversationId` for messaging the hired freelancer
- `POST https://app.opentrain.ai/api/public/v1/contracts/{contractId}/milestones` — create an unfunded milestone (no money moves)
- `POST https://app.opentrain.ai/api/public/v1/milestones/{milestoneId}/fund` — request escrow funding → `202` + `approvalUrl`
- `POST https://app.opentrain.ai/api/public/v1/milestones/{milestoneId}/approve` — request payment release → `202` + `approvalUrl`
- `GET https://app.opentrain.ai/api/public/v1/approvals/{approvalId}` — check whether a human confirmed, declined, or let an approval expire
- `POST https://app.opentrain.ai/api/public/v1/contracts/{contractId}/end` — end a contract (direct when nothing is funded; otherwise `202` + `approvalUrl`)
- `POST https://app.opentrain.ai/api/public/v1/jobs/{jobId}/close` — close/archive a published job (idempotent)
- `PATCH https://app.opentrain.ai/api/public/v1/jobs/{jobId}` — update a published job (re-runs moderation; a blocked result unpublishes back to draft)

## Credits (prepaid balance for hires and milestone escrow)

- `GET https://app.opentrain.ai/api/public/v1/credits` — available + reserved (escrow) balance with recent ledger entries
- `GET https://app.opentrain.ai/api/public/v1/credits/ledger?cursor=…` — full append-only ledger of credit movements
- `POST https://app.opentrain.ai/api/public/v1/credits/top-ups` — create a top-up (`{"amountUsd": 100}`, $10–$10,000): returns a Stripe Checkout `checkoutUrl` a signed-in human must pay; no money moves from the API call
- `GET https://app.opentrain.ai/api/public/v1/credits/top-ups/{topUpId}` — poll until `status` is `COMPLETED`

## Webhooks (push instead of polling)

- `POST https://app.opentrain.ai/api/public/v1/webhooks` — subscribe a URL to platform events (`{"url": "https://…", "eventTypes": ["proposal.received", …]}`); the signing `secret` is returned once
- `GET https://app.opentrain.ai/api/public/v1/webhooks` — list subscriptions
- `GET/DELETE https://app.opentrain.ai/api/public/v1/webhooks/{webhookId}` — inspect or remove one
- Deliveries push the same event records as `/updates` (IDs only), signed via `X-OpenTrain-Signature: t=…,v1=HMAC-SHA256(secret, "{t}.{rawBody}")`; retries with backoff, auto-disable after sustained failure

## Docs

- [Developer documentation](https://www.opentrain.ai/docs/developers/overview): full guides, concepts, and hand-written API reference — append `.md` to any page URL for raw markdown
- [Docs index for agents](https://www.opentrain.ai/docs/llms.txt): llms.txt index of every docs page (llms-full.txt for the whole site inline)
- [OpenAPI specification](https://app.opentrain.ai/api/public/v1/openapi.json): machine-readable description of every public v1 endpoint
- [Agent authentication and registration (auth.md)](https://app.opentrain.ai/auth.md): how to register, claim, rotate, and revoke credentials
- [OAuth protected resource metadata](https://app.opentrain.ai/.well-known/oauth-protected-resource): RFC 9728 discovery
- [OAuth authorization server metadata](https://app.opentrain.ai/.well-known/oauth-authorization-server): RFC 8414 discovery
- [Capability discovery](https://app.opentrain.ai/api/public/v1/job-drafts/capabilities): which API features are enabled for your token

## Notes

- Publishing requires the `jobs:write` scope plus the `public_api_job_publishing` feature; check `capabilities.publish`.
- Publishes run the same validation + moderation pipeline as the in-app flow and have per-account daily limits.
- Inviting and hiring require `proposals:write` plus the `public_api_hiring` feature; sending messages requires `messages:write` plus `public_api_messaging_writes`.
- Identity-bearing actions (messaging, inviting, hiring) require a human to claim the account first — unclaimed accounts get `403` with a `claimUrl`; the claim ceremony is described in auth.md.
- Hiring is co-signed: the hire call returns `202` + `approvalUrl`; a signed-in human confirms in the app and picks the payment source (card or credit balance). Only then is the contract created and the first milestone funded into escrow. With no card on file and insufficient credits, the request returns `409 payment_method_required` with a `billingUrl` a human must visit.
- Money never moves from an API call alone. Hiring, funding, releasing, and ending contracts with funded milestones return `202` with an `approvalUrl` that a signed-in human must open and confirm (approvals expire after ~72 hours). Watch `/updates` for `approval.confirmed` or re-check `GET /approvals/{approvalId}`.
- Contract/milestone reads require `payments:read`; milestone creation and approval requests require `payments:write`, a claimed account, and the `public_api_payments_write` feature.
- Credits are an alternative funding source: with a positive balance, hires and milestone funding draw from credits (held in escrow) instead of requiring a card charge. Credit reads require `payments:read` + the `public_api_credits` feature; creating top-ups requires `payments:write` and a claimed account. Co-sign approvals still apply to every money move.
- Webhooks require `webhooks:manage` plus the `public_api_webhooks` feature; each subscribed event type additionally requires its read scope. A subscription only receives events created after it — use `/updates` for history.