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:
(The spec endpoint itself requires no authentication.)

​
Base URL and Authentication

Every endpoint requires an install-scoped platform token in the Authorization header:
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:
code is one of BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT, RATE_LIMITED, INTERNAL_ERROR. Include requestId when contacting support.

​
Scopes

​
Endpoint Map

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.