Skip to main content
Watch a DemoStart Free
Home›Docs›API Reference›API reference
API Reference

API reference

Conventions, rate limits, and error handling for the Perceive8 API, with a map of every endpoint group.

API reference

The Perceive8 API is a REST API with WebSocket and Server-Sent Events (SSE) endpoints for real-time work. It turns audio, video, live streams, and text into transcripts, speaker labels, scored signals, alerts, and reports — and lets you manage agents, boards, and workspaces programmatically.

Each endpoint group has its own reference page; the endpoint map below links to all of them. If you are new, start with the API quickstart.

Base URL

https://api.perceive8.com

All traffic requires TLS. WebSocket endpoints use wss://api.perceive8.com.

Authentication

Every endpoint requires credentials unless noted otherwise:

  • API key (server-side): X-API-Key: pk_live_xxxxxxxxxxxx
  • Bearer token (user-scoped): Authorization: Bearer <supabase-jwt>
  • Query parameter (WebSocket / SSE only): ?token=pk_live_xxxxxxxxxxxx

Production keys start with pk_live_, development keys with pk_test_. See Authentication for details and key management.

Versioning

The API is versioned by URL prefix. The current version is /v1. Breaking changes are not introduced within a version; when they are unavoidable, a new prefix is introduced and the old one is kept working.

Endpoints under /aria (assistant chat) and /ws (analysis event WebSockets) are public but follow the assistant's own versioning and are documented on their own pages.

Endpoint map

Topic Page Main paths
Analyses & speakers Analyses /v1/analyses, /v1/speakers
Live streaming & uploads Streaming API /v1/stream (WS), /v1/analysis/stream-upload, /v1/analysis/{id}/stream (SSE)
Use cases & skills Use cases and skills /v1/use-cases, /v1/skills
Reports Reports /v1/reports
Query (RAG) Query (RAG) /v1/query
Agents & runs Agents and runs /v1/agents, /v1/runs, /v1/approvals
Boards & workspaces Boards and workspaces /v1/boards, /v1/workspaces
Aria assistant Aria conversations /aria/conversations, /aria/results/chat
Text analysis Text analysis /v1/text
Privacy & consent Privacy and consent /v1/privacy, /v1/consent, /v1/tos, /v1/privacy-policy
API keys & OAuth API keys and OAuth /v1/keys, /v1/oauth
Billing & usage Billing /v1/billing
Agent monitoring Agent monitoring /v1/agent-monitoring
Webhook management Webhooks API /v1/webhooks

A machine-readable OpenAPI spec is available at /openapi.yaml with an interactive viewer at /swagger.html. Its coverage is partial and being expanded — the pages above are the authoritative reference.

Rate limits

API requests are rate-limited per workspace. Every response includes rate limit headers:

Header Description
X-RateLimit-Limit Requests allowed in the current minute window
X-RateLimit-Remaining Requests remaining in the current window
X-RateLimit-Reset UTC epoch seconds when the current window resets
X-RateLimit-Daily-Limit Requests allowed per day
X-RateLimit-Daily-Remaining Requests remaining today

Plan limits

Plan Requests/minute Requests/day
Free 30 500
Starter 60 2,500
Pro 150 10,000
Business 300 50,000

Endpoint categories

Heavy endpoint categories are limited to a fraction of your plan's per-minute limit:

Category Multiplier Paths
Upload 0.5× paths containing /upload or /stream-upload
Streaming 0.5× paths under /ws or containing /stream
Query 0.5× paths containing /query or /reports
All other endpoints 1.0× —

For example, on a Pro plan (150 RPM) you get 75 RPM on report endpoints.

Individual API keys can carry a lower custom limit (rate_limit_rpm, see API keys and OAuth). The effective limit is the minimum of the key limit and the plan limit.

Exceeding the limit

Over-limit requests return 429 with a Retry-After header (seconds to wait):

{
  "detail": "Rate limit exceeded",
  "error": "rate_limit_exceeded",
  "limit": 150,
  "window": "1 minute",
  "retry_after": 60
}

The daily variant returns "error": "daily_limit_exceeded" with "window": "1 day".

Errors

Errors use the standard FastAPI shape — a detail field with a human-readable message:

{
  "detail": "Analysis not found"
}

Validation failures (422) return a detail array describing each invalid field.

Status Meaning
400 Invalid request body or parameters
401 Missing or expired credentials
403 Valid credentials, insufficient permission (or frozen account)
404 Resource not found
409 Conflict with the current state of the resource
422 Request body failed schema validation
429 Rate limit exceeded — see Retry-After
500 Server error — safe to retry with backoff

Health

  • GET /v1/health — backend service health.
  • GET /health and GET /healthz — answered directly by the edge gateway; they report gateway health, not backend health.

SDKs

Official clients handle authentication, retries, and streaming for you:

← Back to docs