Annotation Platforms Overview

The OpenTrain Platform API lets annotation platforms plug OpenTrain’s AI trainer marketplace into their own product — whether you run a commercial data labeling platform or internal annotation tooling at an AI lab or enterprise. Your customers hire AI trainers on OpenTrain (with OpenTrain handling vetting, contracts, escrow, and payouts), and OpenTrain tells your platform exactly when each hired AI trainer should gain or lose access to your workspace.

Base URL:  https://app.opentrain.ai/api/partner/v1
Auth:      Authorization: Bearer ot_ptk_...

Warning

Platform apps never receive personal data. Pre-hire candidates are invisible to this API entirely. Post-hire participants expose only their OpenTrain user ID, display name, profile URL, and country. The optional workEmail field returns the AI trainer’s platform-issued @opentrain.work Work Email — and only when the employer explicitly consented at install time. Personal email addresses are never shared through any surface.

The Core Loop

View diagram source

sequenceDiagram
    participant Customer as Employer (your customer)
    participant OpenTrain
    participant Platform as Your platform

    Customer->>OpenTrain: Opens your consent deep link and approves scopes
    OpenTrain-->>Customer: Shows the ot_ptk_ token once
    Customer->>Platform: Pastes the token into your integration settings
    Platform->>OpenTrain: POST /project-links (map your project to their job)
    Platform->>OpenTrain: POST /webhook-endpoints (subscribe to events)
    Customer->>OpenTrain: Hires an AI trainer
    OpenTrain-->>Platform: contract.started (signed webhook)
    Platform->>Platform: Provision the AI trainer by Work Email
    Customer->>OpenTrain: Ends the contract (human co-signed)
    OpenTrain-->>Platform: contract.ended
    Platform->>Platform: Offboard the AI trainer

1. Connect. Your customer opens your consent deep link, reviews the scopes your app requests, and approves. OpenTrain mints an install-scoped ot_ptk_… token and shows it once — the customer pastes it into your platform.
2. Link. Your platform creates a project link mapping one of your projects to the customer’s OpenTrain job. All events are job-keyed, so this mapping is what routes them to you.
3. Subscribe. Register a webhook endpoint for the lifecycle events you care about.
4. Provision. When the customer hires, you receive contract.started with the AI trainer’s Work Email (consent permitting) — create or invite their account in your workspace.
5. Offboard. Ending a contract is a human co-signed action inside OpenTrain. When it completes you receive contract.ended — remove the AI trainer’s access.
6. Sync usage (optional). Report cumulative per-day work on linked contracts — OpenTrain computes budget consumption against funded milestones and webhooks warn both sides before funded hours or labels run out.

The reference integration implements this entire loop in one self-contained webhook consumer you can adapt to your own platform’s user API.

Provisioning Modes

Each project link declares how hired AI trainers get into your workspace:

Mode	Who provisions	When to use
PARTNER_WEBHOOK (default, recommended)	You — your platform consumes contract.started / contract.ended webhooks and manages accounts itself	You have a user or membership API and want full control
MANAGED_ADAPTER	OpenTrain — the managed-credential path operated by OpenTrain	Your platform has no integration surface yet; coordinate with the OpenTrain team

Everything in these docs focuses on PARTNER_WEBHOOK, the mode the reference integration uses.

Authentication

Every Platform API call carries an install-scoped bearer token:

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 on the OpenTrain consent screen — shown once, never included in the redirect back to your platform. Each token is bound to a single install (one customer’s grant to your app) and carries exactly the scopes that customer approved. See Consent and Installs for the full lifecycle, including reconnects and revocation.

Getting Access

Registration is self-serve: create your platform app directly in the OpenTrain app — name, redirect URIs, and requested scopes — and your client ID and consent deep link are issued immediately. See Register Your App.

Where to Go Next

Consent and Installs

The consent deep link, scopes, one-time tokens, reconnects, and revocation.

Project Links

Map your projects to OpenTrain jobs so events route correctly.

Lifecycle Events

The eight event types, their payloads, and what to do on each.

Usage Sync and Budgets

Report work back to OpenTrain and keep funded budgets ahead of consumption.

Platform Webhooks

Endpoint management, signatures, retries, auto-disable, and redelivery.

Reference Integration

A complete worked example: a webhook consumer that provisions and offboards AI trainers against a self-hosted annotation tool.

Platform API Reference

Every endpoint, hand-documented with examples and error tables.

Note

The machine-readable contract of record is the served spec at GET https://app.opentrain.ai/api/partner/v1/openapi.json (no authentication required). The Platform API shares its error envelope and webhook signature scheme with the Public API.