Platform API Reference Overview

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

Scope	Endpoints it unlocks
(any valid token)	GET /installs/current
project-links:read	List and get project links
project-links:write (implies read)	Create and delete project links
contracts:read	List contracts and read contract budgets
participants:read	List contract participants
participants:email	The workEmail field on participants and webhook payloads — also requires install PII consent
usage:write	Report per-day work usage on linked contracts
webhooks:manage	All six webhook-endpoint operations

Endpoint Map

Family	Endpoints	What it covers
Installs	1	The install (consent grant) this token belongs to
Project links	4	Links between your projects and OpenTrain jobs
Contracts	4	Hired contracts on linked jobs, participants, budget, and usage reporting
Webhook endpoints	6	Endpoint CRUD, re-enable, and redelivery

Related

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.