> ## Documentation Index
> Fetch the complete documentation index at: https://opentrain.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Annotation Platforms Overview

> Integrate OpenTrain talent into your annotation platform: customers hire AI trainers on OpenTrain, and contract lifecycle webhooks tell you exactly when to provision and offboard them in your workspace.

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.

```text theme={null}
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](/docs/developers/concepts/privacy-and-work-email) — and only when the employer explicitly consented at install time. Personal email addresses are never shared through any surface.
</Warning>

## The Core Loop

```mermaid theme={null}
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](/docs/developers/annotation-platforms/consent-and-installs), 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](/docs/developers/annotation-platforms/project-links) 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](/docs/developers/annotation-platforms/webhooks) for the [lifecycle events](/docs/developers/annotation-platforms/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](/docs/developers/annotation-platforms/usage-sync) 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](/docs/developers/annotation-platforms/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:

```bash theme={null}
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](/docs/developers/annotation-platforms/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](/docs/developers/annotation-platforms/register-your-app).

## Where to Go Next

<CardGroup cols={2}>
  <Card title="Consent and Installs" href="/docs/developers/annotation-platforms/consent-and-installs" icon="handshake">
    The consent deep link, scopes, one-time tokens, reconnects, and revocation.
  </Card>

  <Card title="Project Links" href="/docs/developers/annotation-platforms/project-links" icon="link">
    Map your projects to OpenTrain jobs so events route correctly.
  </Card>

  <Card title="Lifecycle Events" href="/docs/developers/annotation-platforms/lifecycle-events" icon="zap">
    The eight event types, their payloads, and what to do on each.
  </Card>

  <Card title="Usage Sync and Budgets" href="/docs/developers/annotation-platforms/usage-sync" icon="gauge">
    Report work back to OpenTrain and keep funded budgets ahead of consumption.
  </Card>

  <Card title="Platform Webhooks" href="/docs/developers/annotation-platforms/webhooks" icon="webhook">
    Endpoint management, signatures, retries, auto-disable, and redelivery.
  </Card>

  <Card title="Reference Integration" href="/docs/developers/annotation-platforms/reference-integration" icon="flask-conical">
    A complete worked example: a webhook consumer that provisions and offboards
    AI trainers against a self-hosted annotation tool.
  </Card>

  <Card title="Platform API Reference" href="/docs/developers/annotation-platforms/api-reference/overview" icon="book-open">
    Every endpoint, hand-documented with examples and error tables.
  </Card>
</CardGroup>

<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](/docs/developers/concepts/errors-pagination-limits) and [webhook signature scheme](/docs/developers/guides/verify-webhook-signatures) with the Public API.
</Note>