API reference

Public API v1 for Primate Vision — video understanding for the agentic web. P1 (PRI-430) publishes resource schemas; endpoints ship from P3 onward.

Generated from the OpenAPI 3.1 contract (version 1.0.0-alpha). The machine-readable spec is the source of truth: https://api.primateintelligence.ai/v1/openapi.json.

• Base URL: https://api.primateintelligence.ai
• Auth: Authorization: Bearer $PRIMATE_API_KEY (see Security model)
• Errors: every non-2xx response carries the standard envelope — see the Error registry

Provisioning & keys

POST /v1/sandbox

Provision an instant sandbox (pv_test_) key — no auth, no card

Anonymous zero-touch provisioning (A1). Issues a fixture-only test-mode key: analyses return deterministic canned results, never touch the GPU, and burn no credits. IP-limited; 7-day expiry. Live keys require signup (billing gate, not an integration gate).

Responses

• 201 — Sandbox key issued. The raw key appears only in this response. → SandboxKey
• 429 — sandbox_limit_exceeded — IP daily cap reached. Retry-After set. → ErrorEnvelope
• 503 — db_unavailable — transient; retry with backoff. → ErrorEnvelope

POST /v1/keys/upgrade

Upgrade a test key to a live free-grant key (6,000s credit)

Stage 1 of the key lifecycle. Call with a pv_test_ key in Authorization; receive a pv_live_ key with tier: free_grant and a 6,000-second credit grant. No email or card required. GitHub-gated (PRI-479): calling without a github_token returns 403 github_verification_required whose details carry the OAuth client_id and device-flow URLs — complete GitHub's device flow and retry with {"github_token": "..."}. One free grant per GitHub account, ever (duplicate → 409 github_account_already_used). IP caps (3 / IP / 24h) remain as secondary defense.

Request body — UpgradeKeyRequest

Responses

• 201 — Live key issued. The raw api_key appears only in this response. → UpgradeKeyResponse
• 401 — github_token_invalid — the supplied github_token failed verification with GitHub. → ErrorEnvelope
• 403 — test_mode_only — must call with a pv_test_ key. github_verification_required — GitHub gate enabled and no github_token supplied; details carry the device-flow bootstrap (client_id, URLs). → ErrorEnvelope
• 409 — github_account_already_used — this GitHub account has already claimed its free grant. → ErrorEnvelope
• 429 — upgrade_limit_exceeded — per-IP or global daily cap reached. → ErrorEnvelope

POST /v1/keys/request

Start a device-code claim flow for a full billed key

Stage 2 of the key lifecycle. Optional auth (test or live key accepted, or none). Returns a device_code and claim_url. Direct the user to claim_url to sign in; poll GET /v1/keys/request/{code} until status changes from pending. Key is delivered once in the claim response; subsequent polls return 410.

Responses

• 202 — Device code issued. → DeviceCodeRequest
• 503 — db_unavailable → ErrorEnvelope

GET /v1/keys/request/{code}

Poll a device-code claim request

Returns {status: "pending"} until the user approves in the browser. After approval, returns status: "consumed" (key was delivered in the claim response). Expired or already-consumed codes return 410.

Parameters

• code (path, string) (required) — The device_code from POST /v1/keys/request.

Responses

• 200 — Current status of the device code. → DeviceCodeStatus
• 404 — resource_not_found — code not found. → ErrorEnvelope
• 410 — device_code_expired — code consumed or expired. Start a new request. → ErrorEnvelope

Videos

GET /v1/videos

List videos (cursor pagination, created_at desc)

Parameters

• limit (query, integer)
• starting_after (query, string) — Cursor — mutually exclusive with ending_before.
• ending_before (query, string)
• status (query, string)
• created_after (query, string (date-time))
• created_before (query, string (date-time))

Responses

• 200 — List envelope (§13.4). → VideoList
• 400 — validation_failed / url_forbidden / prompt errors (§15) → ErrorEnvelope
• 401 — invalid_api_key / key_revoked / key_expired → ErrorEnvelope
• 404 — resource_not_found (account-scoped; no existence oracle) → ErrorEnvelope
• 409 — resource_conflict / idempotency_key_reused / idempotency_unavailable → ErrorEnvelope
• 429 — rate_limit_exceeded / concurrency_limit_exceeded / quota_exceeded (always with Retry-After) → ErrorEnvelope

POST /v1/videos

Create a video (presigned upload or URL ingest)

Parameters

• Idempotency-Key (header, string) — §16.1: first request wins; 24h replay window; same key + different body → 409 idempotency_key_reused.

Request body — CreateVideoRequest

Responses

• 201 — Video created. Presigned mode → status awaiting_upload with upload instructions; URL mode → status processing (async fetch). → Video
• 400 — validation_failed / url_forbidden / prompt errors (§15) → ErrorEnvelope
• 401 — invalid_api_key / key_revoked / key_expired → ErrorEnvelope
• 404 — resource_not_found (account-scoped; no existence oracle) → ErrorEnvelope
• 409 — resource_conflict / idempotency_key_reused / idempotency_unavailable → ErrorEnvelope
• 429 — rate_limit_exceeded / concurrency_limit_exceeded / quota_exceeded (always with Retry-After) → ErrorEnvelope

POST /v1/videos/{id}/complete

Signal that the presigned S3 PUT finished

Parameters

• id (path, string) (required)

Responses

• 200 — Size verified (±5% of declaration); video is ready. → Video
• 400 — validation_failed / url_forbidden / prompt errors (§15) → ErrorEnvelope
• 401 — invalid_api_key / key_revoked / key_expired → ErrorEnvelope
• 404 — resource_not_found (account-scoped; no existence oracle) → ErrorEnvelope
• 409 — resource_conflict / idempotency_key_reused / idempotency_unavailable → ErrorEnvelope
• 429 — rate_limit_exceeded / concurrency_limit_exceeded / quota_exceeded (always with Retry-After) → ErrorEnvelope

GET /v1/videos/{id}

Fetch a video

Parameters

• id (path, string) (required)

Responses

• 200 — The video. → Video
• 400 — validation_failed / url_forbidden / prompt errors (§15) → ErrorEnvelope
• 401 — invalid_api_key / key_revoked / key_expired → ErrorEnvelope
• 404 — resource_not_found (account-scoped; no existence oracle) → ErrorEnvelope
• 409 — resource_conflict / idempotency_key_reused / idempotency_unavailable → ErrorEnvelope
• 429 — rate_limit_exceeded / concurrency_limit_exceeded / quota_exceeded (always with Retry-After) → ErrorEnvelope

DELETE /v1/videos/{id}

Delete a video (409 while analyses are non-terminal on it)

Parameters

• id (path, string) (required)

Responses

• 200 — Deleted. → DeletedVideo
• 400 — validation_failed / url_forbidden / prompt errors (§15) → ErrorEnvelope
• 401 — invalid_api_key / key_revoked / key_expired → ErrorEnvelope
• 404 — resource_not_found (account-scoped; no existence oracle) → ErrorEnvelope
• 409 — resource_conflict / idempotency_key_reused / idempotency_unavailable → ErrorEnvelope
• 429 — rate_limit_exceeded / concurrency_limit_exceeded / quota_exceeded (always with Retry-After) → ErrorEnvelope

GET /v1/videos/{id}/analyses

List analyses for a video (result history)

PRI-496: resource-nested spelling of GET /v1/analyses?video_id={id}. Same list envelope, same filters (status, limit, starting_after), ordered created_at desc. Use it to rebuild a video's full analysis/session history.

Parameters

• id (path, string) (required)
• limit (query, integer)
• starting_after (query, string) — Cursor — mutually exclusive with ending_before.
• ending_before (query, string)
• status (query, string)
• created_after (query, string (date-time))
• created_before (query, string (date-time))

Responses

• 200 — List envelope of analyses referencing this video (§13.4). → AnalysisList
• 400 — validation_failed / url_forbidden / prompt errors (§15) → ErrorEnvelope
• 401 — invalid_api_key / key_revoked / key_expired → ErrorEnvelope
• 404 — resource_not_found (account-scoped; no existence oracle) → ErrorEnvelope
• 409 — resource_conflict / idempotency_key_reused / idempotency_unavailable → ErrorEnvelope
• 429 — rate_limit_exceeded / concurrency_limit_exceeded / quota_exceeded (always with Retry-After) → ErrorEnvelope

GET /v1/demo-videos

Public sample videos with precomputed results (no auth)

PRI-496 GAP-8: onboarding samples — curated videos with precomputed answers for a set of example prompts. Unauthenticated. Use these to see real result shapes before uploading your own video. The documented subset above is the stable contract; extra fields may appear and change without notice.

Responses

• 200 — Sample videos. → DemoVideoList

Analyses

GET /v1/analyses

List analyses (filters: status, video_id, model, created_*)

Parameters

• limit (query, integer)
• starting_after (query, string) — Cursor — mutually exclusive with ending_before.
• ending_before (query, string)
• created_after (query, string (date-time))
• created_before (query, string (date-time))
• status (query, string) — Filter by public analysis status (§13.2 vocabulary): queued | preparing | analyzing | rendering | completed | failed | canceled. E.g. status=analyzing returns currently-running analyses. Unknown values → 400 validation_failed.
• video_id (query, string)
• model (query, string)

Responses

• 200 — List envelope (§13.4). → AnalysisList
• 400 — validation_failed / url_forbidden / prompt errors (§15) → ErrorEnvelope
• 401 — invalid_api_key / key_revoked / key_expired → ErrorEnvelope
• 404 — resource_not_found (account-scoped; no existence oracle) → ErrorEnvelope
• 409 — resource_conflict / idempotency_key_reused / idempotency_unavailable → ErrorEnvelope
• 429 — rate_limit_exceeded / concurrency_limit_exceeded / quota_exceeded (always with Retry-After) → ErrorEnvelope

POST /v1/analyses

Create an analysis (video × prompt × model)

Async by default: 202 + poll. Prefer: wait=<s> (≤120) blocks and returns the terminal resource when it finishes in time. Test-mode keys (pv_test_) return deterministic canned results with no GPU time and no credit burn. Set validate_only: true to dry-run a prompt — returns an AnalysisPreview with cost/assessability and creates nothing.

Parameters

• Idempotency-Key (header, string) — §16.1: first request wins; 24h replay window; same key + different body → 409 idempotency_key_reused.
• Prefer (header, string) — wait= (cap 120)

Request body — CreateAnalysisRequest

Responses

• 200 — Terminal resource (Prefer: wait satisfied, or test mode) — OR an AnalysisPreview when validate_only:true was sent. Discriminate on the object field. → Analysis | AnalysisPreview
• 202 — Queued. Response echoes the compiled query and honest queue_position. → Analysis
• 400 — validation_failed / url_forbidden / prompt errors (§15) → ErrorEnvelope
• 401 — invalid_api_key / key_revoked / key_expired → ErrorEnvelope
• 402 — insufficient_credits (details.meter = credit_seconds) → ErrorEnvelope
• 404 — resource_not_found (account-scoped; no existence oracle) → ErrorEnvelope
• 409 — resource_conflict / idempotency_key_reused / idempotency_unavailable → ErrorEnvelope
• 429 — rate_limit_exceeded / concurrency_limit_exceeded / quota_exceeded (always with Retry-After) → ErrorEnvelope
• 503 — inference_unavailable / capacity_exhausted (with Retry-After) → ErrorEnvelope

GET /v1/analyses/{id}

Fetch an analysis (live progress while running)

Parameters

• id (path, string) (required)

Responses

• 200 — The analysis. progress uses the canonical stage set queued→preparing→analyzing→rendering. → Analysis
• 400 — validation_failed / url_forbidden / prompt errors (§15) → ErrorEnvelope
• 401 — invalid_api_key / key_revoked / key_expired → ErrorEnvelope
• 404 — resource_not_found (account-scoped; no existence oracle) → ErrorEnvelope
• 409 — resource_conflict / idempotency_key_reused / idempotency_unavailable → ErrorEnvelope
• 429 — rate_limit_exceeded / concurrency_limit_exceeded / quota_exceeded (always with Retry-After) → ErrorEnvelope

POST /v1/analyses/{id}/rerun

Free re-run of a failed analysis (never billed)

PRI-493: when a failed analysis carries rerun_eligible: true (it failed during a platform incident, or was flagged by ops), POST here creates a FRESH analysis — same video, prompt/query, model, and options — at no charge (usage stays null on the re-run). One free re-run per failed analysis. 409 rerun_not_eligible otherwise. Normal capacity gates still apply.

Parameters

• id (path, string) (required)

Responses

• 202 — Fresh analysis queued (new id). Never billed. → Analysis
• 400 — validation_failed / url_forbidden / prompt errors (§15) → ErrorEnvelope
• 401 — invalid_api_key / key_revoked / key_expired → ErrorEnvelope
• 404 — resource_not_found (account-scoped; no existence oracle) → ErrorEnvelope
• 409 — resource_conflict / idempotency_key_reused / idempotency_unavailable → ErrorEnvelope
• 429 — rate_limit_exceeded / concurrency_limit_exceeded / quota_exceeded (always with Retry-After) → ErrorEnvelope
• 503 — inference_unavailable / capacity_exhausted (with Retry-After) — the free re-run is NOT consumed on platform failure. → ErrorEnvelope

POST /v1/analyses/{id}/cancel

Cancel an analysis (best-effort once analyzing)

Parameters

• id (path, string) (required)

Responses

• 200 — Canceled (or best-effort race documented in §14.2). → Analysis
• 400 — validation_failed / url_forbidden / prompt errors (§15) → ErrorEnvelope
• 401 — invalid_api_key / key_revoked / key_expired → ErrorEnvelope
• 404 — resource_not_found (account-scoped; no existence oracle) → ErrorEnvelope
• 409 — resource_conflict / idempotency_key_reused / idempotency_unavailable → ErrorEnvelope
• 429 — rate_limit_exceeded / concurrency_limit_exceeded / quota_exceeded (always with Retry-After) → ErrorEnvelope

POST /v1/analyses/batch

Submit 2–10 prompts against the same video (batch discount)

Pricing: first prompt billed at full price; each additional prompt billed at 50% (a 50% discount — config-driven; read the live value from GET /v1/credit-pricing batch_discount_pct). Credits are reserved per-prompt at the discounted rate so the ledger shows the discount directly. Returns an analysis_batch containing all analysis DTOs plus a pricing summary. Each analysis can be polled individually via GET /v1/analyses/{id}. Pass validate_only: true for a cost-estimate dry-run (HTTP 200, no credits reserved).

Request body — CreateAnalysisBatchRequest

Responses

• 200 — Dry-run preview (validate_only: true). Prompts parsed; cost estimated; no credits reserved, no jobs created. → AnalysisBatchPreview
• 202 — Batch queued. All analyses dispatched; poll each id individually. → AnalysisBatch
• 400 — validation_failed / url_forbidden / prompt errors (§15) → ErrorEnvelope
• 401 — invalid_api_key / key_revoked / key_expired → ErrorEnvelope
• 402 — insufficient_credits / grant_exhausted → ErrorEnvelope
• 404 — resource_not_found (account-scoped; no existence oracle) → ErrorEnvelope
• 409 — resource_conflict / idempotency_key_reused / idempotency_unavailable → ErrorEnvelope
• 429 — rate_limit_exceeded / concurrency_limit_exceeded / quota_exceeded (always with Retry-After) → ErrorEnvelope
• 503 — capacity_exhausted / inference_unavailable → ErrorEnvelope

Streams

GET /v1/streams

List streams (cursor pagination, created_at desc)

Parameters

• limit (query, integer)
• starting_after (query, string) — Cursor — mutually exclusive with ending_before.
• ending_before (query, string)
• status (query, string)
• created_after (query, string (date-time))
• created_before (query, string (date-time))
• status (query, "queued" · "ready" · "live" · "ended")

Responses

• 200 — List envelope (§13.4). → StreamList
• 400 — validation_failed / url_forbidden / prompt errors (§15) → ErrorEnvelope
• 401 — invalid_api_key / key_revoked / key_expired → ErrorEnvelope
• 404 — resource_not_found (account-scoped; no existence oracle) → ErrorEnvelope
• 409 — resource_conflict / idempotency_key_reused / idempotency_unavailable → ErrorEnvelope
• 429 — rate_limit_exceeded / concurrency_limit_exceeded / quota_exceeded (always with Retry-After) → ErrorEnvelope

POST /v1/streams

Create a real-time analysis stream

Returns the signaling WS URL, ephemeral ICE servers, and session limits. Signaling protocol v1: join → ready|queued(position) → offer/answer/ice → live; mid-stream update_prompt {prompt} (client→server; server confirms with prompt_updated), metering (5s ticks), warning, end {reason}. WS auth: ?token= accepts a client token (pvct_) or first-party session JWT — never a secret key. Billed per second of live clock time (join/negotiation free) from the same credit ledger as uploads. options.narrative: true adds (a) a narrative_update object ({t_s, text}) to result-frame detections whenever the engine emits a new sentence — event-driven, absent otherwise — and (b) an additive server→client status event {type: "status", status: "prompt_context"|"combined_prompt"|"recalculating", message?} for ordering/annotating narrative entries (closed vocabulary; non-opted-in streams never receive status events). No extra cost.

Parameters

• Idempotency-Key (header, string) — §16.1: first request wins; 24h replay window; same key + different body → 409 idempotency_key_reused.

Request body — CreateStreamRequest

Responses

• 201 — Stream created (queued or ready). Response carries signaling.url + ice_servers + limits. → Stream
• 400 — validation_failed / url_forbidden / prompt errors (§15) → ErrorEnvelope
• 401 — invalid_api_key / key_revoked / key_expired → ErrorEnvelope
• 402 — insufficient_credits — positive balance required. → ErrorEnvelope
• 404 — resource_not_found (account-scoped; no existence oracle) → ErrorEnvelope
• 409 — stream_already_active — one queued|ready|live stream per account (also the un-keyed-retry guard, §31-F2) / idempotency_key_reused. → ErrorEnvelope
• 429 — rate_limit_exceeded / concurrency_limit_exceeded / quota_exceeded (always with Retry-After) → ErrorEnvelope
• 503 — capacity_exhausted (with Retry-After) — slot queue beyond the hard cap. → ErrorEnvelope

GET /v1/streams/{id}

Fetch a stream (usage + results summary once ended)

Parameters

• id (path, string) (required)

Responses

• 200 — The stream. Terminal streams carry usage {billed_seconds, credit_balance_after} + duration_s + results_summary. → Stream
• 400 — validation_failed / url_forbidden / prompt errors (§15) → ErrorEnvelope
• 401 — invalid_api_key / key_revoked / key_expired → ErrorEnvelope
• 404 — resource_not_found (account-scoped; no existence oracle) → ErrorEnvelope
• 409 — resource_conflict / idempotency_key_reused / idempotency_unavailable → ErrorEnvelope
• 429 — rate_limit_exceeded / concurrency_limit_exceeded / quota_exceeded (always with Retry-After) → ErrorEnvelope

GET /v1/streams/{id}/recording

Fetch the session recording (signed URL, sign-on-read)

PRI-496: returns a signed playback URL for the server-side session recording. Requires the stream to have been created with recording: true and to have ended with a stored recording. 404 resource_not_found when recording was not enabled; 409 resource_conflict while the stream is still active, when capture failed, or when no recording was stored. URL TTL 1h — re-fetch for a fresh one.

Parameters

• id (path, string) (required)

Responses

• 200 — Signed recording URL. → StreamRecording
• 400 — validation_failed / url_forbidden / prompt errors (§15) → ErrorEnvelope
• 401 — invalid_api_key / key_revoked / key_expired → ErrorEnvelope
• 404 — resource_not_found (account-scoped; no existence oracle) → ErrorEnvelope
• 409 — resource_conflict / idempotency_key_reused / idempotency_unavailable → ErrorEnvelope
• 429 — rate_limit_exceeded / concurrency_limit_exceeded / quota_exceeded (always with Retry-After) → ErrorEnvelope

POST /v1/streams/{id}/end

End a stream (idempotent)

Graceful end: settles the credit reservation for the billed live-clock seconds (releases it entirely when the stream never went live). Ending an already-ended stream returns the terminal resource unchanged.

Parameters

• id (path, string) (required)

Responses

• 200 — The ended stream with final usage. → Stream
• 400 — validation_failed / url_forbidden / prompt errors (§15) → ErrorEnvelope
• 401 — invalid_api_key / key_revoked / key_expired → ErrorEnvelope
• 404 — resource_not_found (account-scoped; no existence oracle) → ErrorEnvelope
• 409 — resource_conflict / idempotency_key_reused / idempotency_unavailable → ErrorEnvelope
• 429 — rate_limit_exceeded / concurrency_limit_exceeded / quota_exceeded (always with Retry-After) → ErrorEnvelope

Webhook endpoints

GET /v1/webhook_endpoints

List webhook endpoints (secrets never included)

Responses

• 200 — List envelope. → WebhookEndpointList
• 400 — validation_failed / url_forbidden / prompt errors (§15) → ErrorEnvelope
• 401 — invalid_api_key / key_revoked / key_expired → ErrorEnvelope
• 404 — resource_not_found (account-scoped; no existence oracle) → ErrorEnvelope
• 409 — resource_conflict / idempotency_key_reused / idempotency_unavailable → ErrorEnvelope
• 429 — rate_limit_exceeded / concurrency_limit_exceeded / quota_exceeded (always with Retry-After) → ErrorEnvelope

POST /v1/webhook_endpoints

Create a webhook endpoint (returns the one-time whsec_ secret)

Standard Webhooks signing (webhook-id / webhook-timestamp / webhook-signature). The secret appears ONLY in this response. Delivery contract: 10s timeout, retries 1m/5m/30m/2h/8h/24h with jitter, at-least-once, no ordering — dedupe on the evt_ id. Endpoints failing 100% for 72h are auto-disabled with an email notice. At most 10 endpoints per account.

Parameters

• Idempotency-Key (header, string) — §16.1: first request wins; 24h replay window; same key + different body → 409 idempotency_key_reused.

Request body — CreateWebhookEndpointRequest

Responses

• 201 — Endpoint created. secret is returned exactly once. → WebhookEndpoint
• 400 — validation_failed / webhook_endpoint_limit (10 per account). → ErrorEnvelope
• 401 — invalid_api_key / key_revoked / key_expired → ErrorEnvelope
• 404 — resource_not_found (account-scoped; no existence oracle) → ErrorEnvelope
• 409 — resource_conflict / idempotency_key_reused / idempotency_unavailable → ErrorEnvelope
• 429 — rate_limit_exceeded / concurrency_limit_exceeded / quota_exceeded (always with Retry-After) → ErrorEnvelope

GET /v1/webhook_endpoints/{id}

Fetch a webhook endpoint (secret never included)

Parameters

• id (path, string) (required) — Webhook endpoint id (we_…).

Responses

• 200 — The endpoint. → WebhookEndpoint
• 400 — validation_failed / url_forbidden / prompt errors (§15) → ErrorEnvelope
• 401 — invalid_api_key / key_revoked / key_expired → ErrorEnvelope
• 404 — resource_not_found (account-scoped; no existence oracle) → ErrorEnvelope
• 409 — resource_conflict / idempotency_key_reused / idempotency_unavailable → ErrorEnvelope
• 429 — rate_limit_exceeded / concurrency_limit_exceeded / quota_exceeded (always with Retry-After) → ErrorEnvelope

DELETE /v1/webhook_endpoints/{id}

Delete a webhook endpoint (effective immediately, §17)

Parameters

• id (path, string) (required) — Webhook endpoint id (we_…).

Responses

• 200 — {id, object, deleted: true}.
• 400 — validation_failed / url_forbidden / prompt errors (§15) → ErrorEnvelope
• 401 — invalid_api_key / key_revoked / key_expired → ErrorEnvelope
• 404 — resource_not_found (account-scoped; no existence oracle) → ErrorEnvelope
• 409 — resource_conflict / idempotency_key_reused / idempotency_unavailable → ErrorEnvelope
• 429 — rate_limit_exceeded / concurrency_limit_exceeded / quota_exceeded (always with Retry-After) → ErrorEnvelope

POST /v1/webhook_endpoints/{id}/rotate_secret

Rotate the signing secret (24h dual-secret overlap)

Returns the NEW secret exactly once. The previous secret keeps signing deliveries for 24h so receivers can migrate without dropped verifications — the signature header carries one signature per active secret.

Parameters

• id (path, string) (required) — Webhook endpoint id (we_…).

Responses

• 200 — Endpoint with the new one-time secret. → WebhookEndpoint
• 400 — validation_failed / url_forbidden / prompt errors (§15) → ErrorEnvelope
• 401 — invalid_api_key / key_revoked / key_expired → ErrorEnvelope
• 404 — resource_not_found (account-scoped; no existence oracle) → ErrorEnvelope
• 409 — resource_conflict / idempotency_key_reused / idempotency_unavailable → ErrorEnvelope
• 429 — rate_limit_exceeded / concurrency_limit_exceeded / quota_exceeded (always with Retry-After) → ErrorEnvelope

POST /v1/webhook_endpoints/{id}/enable

Re-enable a disabled endpoint (clears auto-disable state)

Parameters

• id (path, string) (required) — Webhook endpoint id (we_…).

Responses

• 200 — The re-enabled endpoint. → WebhookEndpoint
• 400 — validation_failed / url_forbidden / prompt errors (§15) → ErrorEnvelope
• 401 — invalid_api_key / key_revoked / key_expired → ErrorEnvelope
• 404 — resource_not_found (account-scoped; no existence oracle) → ErrorEnvelope
• 409 — resource_conflict / idempotency_key_reused / idempotency_unavailable → ErrorEnvelope
• 429 — rate_limit_exceeded / concurrency_limit_exceeded / quota_exceeded (always with Retry-After) → ErrorEnvelope

GET /v1/webhook_endpoints/{id}/deliveries

List recent deliveries (last 100, with response codes)

Dead-lettered deliveries stay visible for 30 days. Deliveries carry the evt_ id (stable across retries), attempt count, last response status/error, and next retry time.

Parameters

• id (path, string) (required) — Webhook endpoint id (we_…).

Responses

• 200 — List envelope (newest first). → WebhookDeliveryList
• 400 — validation_failed / url_forbidden / prompt errors (§15) → ErrorEnvelope
• 401 — invalid_api_key / key_revoked / key_expired → ErrorEnvelope
• 404 — resource_not_found (account-scoped; no existence oracle) → ErrorEnvelope
• 409 — resource_conflict / idempotency_key_reused / idempotency_unavailable → ErrorEnvelope
• 429 — rate_limit_exceeded / concurrency_limit_exceeded / quota_exceeded (always with Retry-After) → ErrorEnvelope

POST /v1/webhook_endpoints/{id}/deliveries/{delivery_id}/redeliver

Redeliver a delivery now (works on failed/dead rows)

Parameters

• id (path, string) (required) — Webhook endpoint id (we_…).
• delivery_id (path, string) (required) — Delivery id (whd_…).

Responses

• 202 — Requeued for immediate delivery. → WebhookDelivery
• 400 — validation_failed / url_forbidden / prompt errors (§15) → ErrorEnvelope
• 401 — invalid_api_key / key_revoked / key_expired → ErrorEnvelope
• 404 — resource_not_found (account-scoped; no existence oracle) → ErrorEnvelope
• 409 — resource_conflict / idempotency_key_reused / idempotency_unavailable → ErrorEnvelope
• 429 — rate_limit_exceeded / concurrency_limit_exceeded / quota_exceeded (always with Retry-After) → ErrorEnvelope

Client tokens

POST /v1/client_tokens

Mint an ephemeral browser-safe client token (pvct_)

Server-side token exchange (§4.9): authenticate with a secret key (or first-party session), receive a short-lived scoped pvct_ bearer for the browser. The browser then calls Primate directly — your secret key never leaves your server. Tokens are revoked implicitly when the minting key is revoked (≤5s). Rate class: 120/min per key. Client tokens can never mint tokens.

Request body — CreateClientTokenRequest

Responses

• 201 — Token minted. The raw token appears only in this response. → ClientToken
• 400 — validation_failed — scopes/ttl_s/binding violations, all listed at once. → ErrorEnvelope
• 403 — insufficient_scope — requested scopes exceed the minting key’s, or the caller is itself a client token. → ErrorEnvelope
• 404 — resource_not_found — video_id binding does not resolve to an owned video. → ErrorEnvelope
• 429 — rate_limit_exceeded — client_tokens.create is 120/min per key. → ErrorEnvelope

Billing

GET /v1/credits

Credit balance and transaction history

Agent-facing billing truth (PRI-480 A-5): remaining balance in billable seconds plus a paginated ledger. Check this before submitting work to avoid a 402. Requires the billing:read scope.

Parameters

• limit (query, integer)
• before (query, string)

Responses

• 200 — Balance plus one page of ledger entries. → CreditsResponse
• 400 — validation_failed / url_forbidden / prompt errors (§15) → ErrorEnvelope
• 401 — invalid_api_key / key_revoked / key_expired → ErrorEnvelope
• 404 — resource_not_found (account-scoped; no existence oracle) → ErrorEnvelope
• 409 — resource_conflict / idempotency_key_reused / idempotency_unavailable → ErrorEnvelope
• 429 — rate_limit_exceeded / concurrency_limit_exceeded / quota_exceeded (always with Retry-After) → ErrorEnvelope

Usage

GET /v1/usage

Usage meters (credit balance, period consumption)

Responses

• 200 — Meters + legacy fields. Same numbers as the dashboard (shared service, reconciles with the credit ledger to the second). → UsageResponse
• 400 — validation_failed / url_forbidden / prompt errors (§15) → ErrorEnvelope
• 401 — invalid_api_key / key_revoked / key_expired → ErrorEnvelope
• 404 — resource_not_found (account-scoped; no existence oracle) → ErrorEnvelope
• 409 — resource_conflict / idempotency_key_reused / idempotency_unavailable → ErrorEnvelope
• 429 — rate_limit_exceeded / concurrency_limit_exceeded / quota_exceeded (always with Retry-After) → ErrorEnvelope

Meta & platform

GET /v1/models

List available models

Responses

• 200 — Model catalog. Requests may say model:"latest"; responses always name the concrete version. → object

GET /v1/credit-pricing

Current credit pricing (public, no auth)

Responses

• 200 — Pricing config. Billing unit is source-clock video-seconds; analysis cost = usage.billed_seconds × price_per_second_cents. → CreditPricing

POST /v1/parse

Compile a free-text prompt into a CompiledQuery (no analysis created)

Stateless prompt compiler. Auth optional (anonymous allowed); rate-limited to 30 req/min per IP. Never touches the GPU and never burns credits — use POST /v1/analyses with validate_only:true when you also want cost/assessability estimates.

Request body — ParseRequest

Responses

• 200 — The compiled query and which parser produced it. → ParseResponse
• 400 — empty_prompt — prompt missing, not a string, or blank. → ErrorEnvelope
• 422 — parse_failed — prompt could not be compiled into a query. → ErrorEnvelope
• 429 — rate_limit_exceeded (30 req/min per IP). → ErrorEnvelope
• 503 — parse_unavailable — parse service temporarily unavailable. → ErrorEnvelope

GET /v1/errors

Machine-readable error-code registry (§15)

Responses

• 200 — Closed registry — codes are append-only; SDK retry policy generates from retryable/idem flags. → object

Object schemas

Every named object in the contract. Field types link to their schema.

VideoStatus

Video lifecycle state (§14.1).

Enum: "awaiting_upload" · "processing" · "ready" · "failed"

VideoUpload

Presigned upload instructions. Present only while awaiting_upload. URL TTL 1h.

• method — "PUT" (required)
• url — string (uri) (required)
• headers — object (required)
• expires_at — string (date-time) (required)

VideoMedia

Signed 1h playback URL for the source video (sign-on-read — re-fetch for a fresh URL). Null while not ready or when no stored source object exists.

• url — string (uri) (required)
• expires_at — string (date-time) (required)

ErrorObject

- code — string (required)

• message — string (required)

Video

A source video (§13.1).

• id — string (required) — Video resource id (prefixed ULID). Immutable.
• object — "video" (required)
• livemode — boolean (required) — true when the request used a live key; false for test keys and sandbox. Stripe-style.
• status — VideoStatus (required) — Video lifecycle state (§14.1).
• filename — string,null (required)
• size_bytes — integer,null (required)
• duration_s — number,null (required)
• width — integer,null (required)
• height — integer,null (required)
• fps — number,null (required)
• content_type — "video/mp4" · "video/quicktime" (required)
• source — "upload" · "url" (required)
• upload — VideoUpload (required) — Presigned upload instructions. Present only while awaiting_upload. URL TTL 1h.
• media — VideoMedia — Signed 1h playback URL for the source video (sign-on-read — re-fetch for a fresh URL). Null while not ready or when no stored source object exists.
• error — ErrorObject (required)
• metadata — object — Free-form key/value metadata. ≤16 keys, key ≤40 chars [a-zA-Z0-9_.-], value ≤500 chars.
• expires_at — string,null (date-time) (required)
• created_at — string (date-time) (required)

AnalysisStatus

Analysis lifecycle state (§14.2). Clients MUST tolerate unknown future non-terminal values.

Enum: "queued" · "preparing" · "analyzing" · "rendering" · "completed" · "failed" · "canceled"

Progress

Non-terminal only. percent is monotonic non-decreasing per analysis.

• stage — string (required)
• percent — number (required)

Clip

- start_s — number (required)

• end_s — number (required)
• confidence — number (required)
• terms — object (required)

Result

Analysis result — the product (§13.3). Reserved (always absent in v1): masks, bounding_boxes, events.

• answer — "yes" · "no" · "indeterminate" (required)
• confidence — number (required)
• clips — array<Clip> (required)
• term_confidences — object (required)
• query_type — "object" · "action" · "compound" · "attribute" · "open_ended" (required)
• video_duration_s — number,null (required)
• detected_count — integer,null
• indeterminate_reason — "low_confidence" · "nothing_detected" · "unsupported_query_form" · "duration_mismatch"

Narrative

- status — "generating" · "ready" · "failed" (required)

• entries — array