> ## 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.

# Platform API Reference Overview

> Base URL, ot_ptk_ bearer authentication, the error envelope, scopes, and a map of every OpenTrain Platform API endpoint.

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:

```text theme={null}
GET https://app.opentrain.ai/api/partner/v1/openapi.json
```

(The spec endpoint itself requires no authentication.)

## Base URL and Authentication

```text theme={null}
https://app.opentrain.ai/api/partner/v1
```

Every endpoint requires an install-scoped platform token in the `Authorization` header:

```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 when a customer installs your app via the [consent flow](/docs/developers/annotation-platforms/consent-and-installs) — 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](/docs/developers/concepts/errors-pagination-limits):

```json theme={null}
{
  "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`](/docs/developers/annotation-platforms/api-reference/installs/current)                                                                                    |
| `project-links:read`                   | [List](/docs/developers/annotation-platforms/api-reference/project-links/list) and [get](/docs/developers/annotation-platforms/api-reference/project-links/get) project links           |
| `project-links:write` (implies `read`) | [Create](/docs/developers/annotation-platforms/api-reference/project-links/create) and [delete](/docs/developers/annotation-platforms/api-reference/project-links/delete) project links |
| `contracts:read`                       | [List contracts](/docs/developers/annotation-platforms/api-reference/contracts/list) and [read contract budgets](/docs/developers/annotation-platforms/api-reference/contracts/budget)  |
| `participants:read`                    | [List contract participants](/docs/developers/annotation-platforms/api-reference/contracts/participants)                                                                           |
| `participants:email`                   | The `workEmail` field on participants and webhook payloads — also requires install [PII consent](/docs/developers/annotation-platforms/consent-and-installs#scopes)                |
| `usage:write`                          | [Report per-day work usage](/docs/developers/annotation-platforms/api-reference/contracts/usage) on linked contracts                                                               |
| `webhooks:manage`                      | All six [webhook-endpoint](/docs/developers/annotation-platforms/api-reference/webhook-endpoints/list) operations                                                                  |

## Endpoint Map

| Family                                                                                     | Endpoints | What it covers                                                                                                                                                                                                 |
| ------------------------------------------------------------------------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Installs](/docs/developers/annotation-platforms/api-reference/installs/current)                | 1         | The install (consent grant) this token belongs to                                                                                                                                                              |
| [Project links](/docs/developers/annotation-platforms/api-reference/project-links/list)         | 4         | Links between your projects and OpenTrain jobs                                                                                                                                                                 |
| [Contracts](/docs/developers/annotation-platforms/api-reference/contracts/list)                 | 4         | Hired contracts on linked jobs, participants, [budget](/docs/developers/annotation-platforms/api-reference/contracts/budget), and [usage reporting](/docs/developers/annotation-platforms/api-reference/contracts/usage) |
| [Webhook endpoints](/docs/developers/annotation-platforms/api-reference/webhook-endpoints/list) | 6         | Endpoint CRUD, re-enable, and redelivery                                                                                                                                                                       |

## Related

<CardGroup cols={2}>
  <Card title="Annotation Platforms Overview" href="/docs/developers/annotation-platforms/overview" icon="map">
    The core loop, provisioning modes, and how to get access.
  </Card>

  <Card title="Lifecycle Events" href="/docs/developers/annotation-platforms/lifecycle-events" icon="zap">
    The eight event types and their payload shapes.
  </Card>

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

  <Card title="Verify Webhook Signatures" href="/docs/developers/guides/verify-webhook-signatures" icon="shield-check">
    Tested HMAC verification code, shared with the Public API.
  </Card>
</CardGroup>