Skip to main content
Every page in this reference documents one Platform API endpoint by hand: parameters, response fields, scope 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/partner/v1/openapi.json
(The spec endpoint itself requires no authentication.)

​
Base URL and Authentication

https://app.opentrain.ai/api/partner/v1
Every endpoint requires an install-scoped platform token in the Authorization header: 
curl -sS https://app.opentrain.ai/api/partner/v1/installs/current \
  -H "Authorization: Bearer $OT_PARTNER_TOKEN"
Tokens start with ot_ptk_ and are minted when a customer installs your app via the consent flow — shown once, on the consent screen only. Beyond the per-endpoint scope, every request additionally requires a live (non-revoked) token, an ACTIVE install, an ACTIVE platform app, and the annotation-platform feature enabled on the granting employer’s account. Any of those failing yields 401 or 403.

​
The Error Envelope

Non-2xx responses share the same JSON shape as the Public API: 
{
  "error": "Human-readable message",
  "code": "FORBIDDEN",
  "requestId": "9d1f3a8e-...",
  "details": { "...": "endpoint-specific context" }
}
code is one of BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT, RATE_LIMITED, INTERNAL_ERROR. Include requestId when contacting support.

​
Scopes

ScopeEndpoints it unlocks
(any valid token)GET /installs/current
project-links:readList and get project links
project-links:write (implies read)Create and delete project links
contracts:readList contracts and read contract budgets
participants:readList contract participants
participants:emailThe workEmail field on participants and webhook payloads — also requires install PII consent
usage:writeReport per-day work usage on linked contracts
webhooks:manageAll six webhook-endpoint operations

​
Endpoint Map

FamilyEndpointsWhat it covers
Installs1The install (consent grant) this token belongs to
Project links4Links between your projects and OpenTrain jobs
Contracts4Hired contracts on linked jobs, participants, budget, and usage reporting
Webhook endpoints6Endpoint CRUD, re-enable, and redelivery

Annotation Platforms Overview

The core loop, provisioning modes, and how to get access.

Lifecycle Events

The eight event types and their payload shapes.

Platform Webhooks

Delivery mechanics: signatures, retries, auto-disable, redelivery.

Verify Webhook Signatures

Tested HMAC verification code, shared with the Public API.