## Base URL

```text
https://api.ravi.app
```

Production backend endpoints are mounted under `/api/`. Use [API Endpoints](/api/endpoints/) for the current route families and [API Reference](/api/reference/) for the generated OpenAPI document.

## Authentication

Ravi supports bearer authentication.

```http
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>`:

```bash
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:

```text
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

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

This is the quickest public check that you are talking to the production backend.

## Next Steps

- [API Endpoints](/api/endpoints/)
- [API Reference](/api/reference/)
- [Authentication](/getting-started/authentication/)
- [Error Reference](/api/error-reference/)