API Overview

Base URL

https://api.ravi.app

Production backend endpoints are mounted under /api/. Use API Endpoints for the current route families and API Reference for the generated OpenAPI document.

Authentication

Ravi supports bearer authentication.

Authorization: Bearer <token-or-api-key>

The backend has two API-key families:

Prefix	Scope
`ravi_mgmt_...`	Management/account-level operations
`ravi_id_...`	Identity-scoped operations

JWT login and refresh routes are still available through the Django auth endpoints.

Identity Scoping

Some resources are naturally scoped to an identity: email, phone, calls, passwords, secrets, contacts, and events. The API key is an auth fence only — it never selects the identity. The caller chooses one and passes it explicitly.

Every per-identity request carries ?identity=<uuid>:

curl "https://api.ravi.app/api/messages/?identity=<uuid>" \
  -H "Authorization: Bearer $RAVI_API_KEY"

Key family	Behaviour of `?identity=<uuid>`
`ravi_id_...`	The param must match the key’s fenced identity; a mismatch returns an empty result.
`ravi_mgmt_...`	The param targets one identity. Omit it for account-wide behaviour.

The param is additive — the SDKs send it automatically from the identity object, so you never assemble it by hand.

Response Format

Most API responses are JSON and use normal HTTP status codes.

Status	Meaning
`200`	Success
`201`	Created
`204`	Deleted or empty success
`400`	Validation error
`401`	Missing or invalid authentication
`403`	Authenticated but not allowed
`404`	Resource or route not found
`429`	Rate limited
`500`	Server error

OpenAPI

The public documentation publishes a generated OpenAPI document at:

https://docs.ravi.app/openapi.json

That file is assembled from the backend schema fragments checked into the backend repo. It is the machine-readable contract to use for API linting, endpoint review, and agent context.

Current Public Health Check

curl https://api.ravi.app/api/health/ping/