REST API

Authentication

Server-to-server endpoints take a product-scoped service API key:

Authorization: Bearer yswld_<43 characters>

• A key belongs to one organization, one product and one environment, and carries up to five scopes. The tenant and product always come from the key, never from the request body.
• Keys expire (180 days by default, at most 365) and are shown once. Rotating a key keeps its scopes; to change scopes, issue a new key.
• Browser session cookies are never accepted on these endpoints, and the /api/v1/proof endpoints send no CORS headers. Call them from your server.
• Availability: service API keys are currently issued only to sponsored internal workspaces. Other workspaces receive 403 when creating one. MCP credentials, the SDK identity flow and the Web Components are available to every workspace.

Endpoints the SDK calls from the browser take the signed end-user identity instead (see SDK). Customer-facing collection and control endpoints take the secret from the customer's own link, sent in a header, never in the URL.

Proof scopes

A key acts as a non-human integration. Approving, rejecting, managing consent, revoking directly, publishing paid use and exporting raw originals stay with people: those calls answer HUMAN_APPROVAL_REQUIRED or FORBIDDEN, and revocation calls file a request that a teammate completes (HTTP 202).

Idempotency

Send an Idempotency-Key header on any write to /api/v1/proof/*:

• 8 to 200 characters of letters, digits, period, underscore, colon or hyphen.
• Kept for 24 hours per key and credential. A retry with the same key, method, path and body replays the stored response with the header idempotent-replayed: true.
• The same key with a different request answers 409 IDEMPOTENCY_KEY_REUSED. A retry while the first call is still running answers 409 IDEMPOTENCY_IN_PROGRESS.
• Only successful responses are stored; after an error the key is released and you can retry.
• POST /api/v1/proof/submissions requires the header. A conflicting reuse there answers 409 CONFLICT.

Other writes use their own idempotency fields: signals take idempotencyKey in the body and value events are stored once per eventId.

Errors

Service-key endpoints return a typed envelope. The requestId is also sent as x-request-id.

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The request did not match the schema.",
    "requestId": "req_...",
    "details": [{ "path": "placementId", "message": "Required" }]
  }
}

Customer collection and control endpoints (/api/proof/*) use a simpler shape, { "error": "message", "code": "INVALID_INPUT" }, because their messages are shown to customers.

Pagination

List endpoints take limit (default 50, 1 to 100) and cursor, and return:

{ "data": [ ... ], "nextCursor": "WyIyMDI2LTA5..." }

Pass nextCursor back unchanged until it is null. Cursors are opaque. Proof items and signals are newest first; ledger events are oldest first. Items filter by status (repeat it or separate with commas) and type; events filter by proofItemId, eventType and eventId.

Expansion

Some proof endpoints take expand to inline data you would otherwise fetch from a sub-resource. Repeat it or separate relations with commas:

GET /api/v1/proof/items?expand=versions,consent&limit=20

{ "data": [ { "id": "...", "status": "approved", ...,
    "expanded": {
      "versions": { "data": [ ... ], "hasMore": false },
      "consent": { "data": { "proofItemId": "...", "status": "approved", "grants": [ ... ] }, "hasMore": false }
    } } ],
  "nextCursor": null }

• Each relation's data has exactly the shape of its sub-resource and needs the same scope and permission. Unapproved versions appear only with yousaid:proof:read_private, as on /versions.
• At most 2 relations per request. An unknown, repeated or extra relation answers 400 VALIDATION_FAILED with the allowed values in details.
• Each relation is capped per parent; hasMore is true when the cap cut it. Read the sub-resource for the rest.
• On a list, each relation costs one query for the whole page, and the page size is capped at 50 while expanding.

Rate limits

Each service key has 120 requests per minute. Every response carries x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset (unix seconds). A 429 adds retry-after.

Endpoints

Paths use {id} for identifiers. The machine-readable contracts are /openapi-v1.yaml and /openapi-rooms-v1.5.yaml.