> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wave.sa/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Base URL, authentication, versioning, and response format for the Wave API.

The Wave API is a JSON REST API. All endpoints are served under the `/v1` prefix.

<Info>
  **Scope:** these docs cover **Web Callback (sandbox)** — the one shipped developer feature today. WebRTC, WhatsApp, recordings, and production-tier keys are not yet documented.
</Info>

## Base URL

```
https://api.wave.sa
```

## Authentication

Every developer request authenticates with a **sandbox API key** as a Bearer token:

```
Authorization: Bearer sk_sandbox_xxxxxxxxxxxx
```

Get your key from the [Wave dashboard](https://wave.sa). See [Authentication](/authentication).

## Versioning

All endpoints are under `/v1`. Breaking changes ship under a new version prefix.

## Response format

Success responses return the resource directly (no envelope). Errors return a standard bilingual envelope:

```json theme={null}
{
  "error_code": "VALIDATION_ERROR",
  "message": "…",
  "message_ar": "…",
  "request_id": "req_…",
  "docs_url": "https://wave.sa/docs/errors"
}
```

See [Errors](/errors) for the full code list.

## Endpoints

The **Endpoints** section is generated from the OpenAPI spec and includes an interactive playground. Today it covers the live `POST /v1/callback`, plus `GET /v1/calls` and `GET /v1/health`. Callback lifecycle endpoints (`GET`/`DELETE /v1/callbacks/:id`, `GET /v1/callbacks`) are marked **coming soon** until they ship.