Ravi publishes first-party SDKs for TypeScript and Python. Use an SDK when you want typed resource clients, consistent error handling, retry behavior, and webhook signature helpers without hand-writing HTTP requests.

## Packages

| Language | Install package | Import package | Repo version |
| --- | --- | --- | --- |
| TypeScript | `@ravi-hq/sdk` | `@ravi-hq/sdk` | `0.2.0` |
| Python | `ravi-sdk` | `ravi` | `0.2.0` |

Install:

```bash
npm install @ravi-hq/sdk
pip install ravi-sdk
```

## Authentication

Both SDKs send the API key as a bearer token on every request. The key is an
**auth fence only** — it defines what you're allowed to touch, but it never
selects the identity. The *caller* picks an identity and calls channels on it,
and every per-identity request carries `?identity=<uuid>` automatically.

| Key family | Use for |
| --- | --- |
| `ravi_id_...` | Identity-scoped agent runtime work |
| `ravi_mgmt_...` | Account-level management work |

Read the key from `RAVI_API_KEY` in server-side code. Create keys from the [dashboard](https://dashboard.ravi.app/dashboard/api-keys/), `ravi auth login`, or the key-management API.

## Resource Map

Account-level resources hang off the client. Everything per-identity is reached
through an `Identity` object returned by `ravi.identities`, where `identity.email`
and `identity.phone` are channel objects (with `.address` / `.number`), not
strings.

### Account-level (`ravi.*`)

| Area | TypeScript | Python |
| --- | --- | --- |
| Identities | `ravi.identities` | `ravi.identities` |
| Fenced identity | `ravi.me()` | `ravi.me` |
| Events | `ravi.events` | `ravi.events` |
| Domains | `ravi.domains` | `ravi.domains` |
| Webhooks | `ravi.webhooks` | `ravi.webhooks` |
| API keys | `ravi.apiKeys` | `ravi.api_keys` |

### Per-identity (`identity.*`)

| Area | TypeScript | Python |
| --- | --- | --- |
| Email channel | `identity.email` | `identity.email` |
| Phone channel | `identity.phone` | `identity.phone` |
| Contacts | `identity.contacts` | `identity.contacts` |
| Passwords | `identity.vault.passwords` | `identity.vault.passwords` |
| Secrets | `identity.vault.secrets` | `identity.vault.secrets` |
| Events | `identity.events` | `identity.events` |

The `email` channel exposes `.address`, `inbox`/`threads`/`get`/`send`/`waitFor`
and returns `EmailMessage` objects (`.reply`/`.replyAll`/`.forward`/`.markRead`).
The `phone` channel exposes `.number`, `inbox`/`conversations`/`send`/`call`/
`calls`/`waitFor` and returns `SmsMessage` objects (`.reply`/`.markRead`).

## Next Steps

- [TypeScript SDK](/sdk/typescript/)
- [Python SDK](/sdk/python/)
- [API Reference](/api/reference/)