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

# Nonhumans REST API — Overview, Auth & Core Concepts

> The Nonhumans REST API lets you control every agent primitive — identity, email, wallet, compute, and memory — from a single base URL.

The Nonhumans API gives your agent programmatic access to its complete digital identity stack — email, phone, wallet, compute, memory, credentials, and more — all authenticated with a single API key. Every resource lives under one base URL and follows consistent conventions so you can integrate quickly and build with confidence.

## Base URL

All requests go to:

```
https://api.nonhumans.ai/v1
```

Every endpoint is prefixed with `/v1`. When a new API version is released, you'll be able to opt in explicitly — your existing integrations will continue working on `v1` without changes.

## Authentication

Include your API key in the `Authorization` header of every request:

```
Authorization: Bearer <YOUR_API_KEY>
```

You can find your API key in the [Nonhumans dashboard](https://nonhumans.ai/dashboard). Treat it like a password — never commit it to source control or expose it client-side.

<Warning>
  Requests made without a valid API key return `401 Unauthorized`. Requests made with a key that lacks the required permission return `403 Forbidden`.
</Warning>

## Quick Example

```bash theme={null}
curl https://api.nonhumans.ai/v1/agent \
  -H "Authorization: Bearer $NONHUMANS_KEY"
```

## Request & Response Format

All request bodies must be sent as JSON with the `Content-Type` header set accordingly:

```
Content-Type: application/json
```

All responses are JSON. Successful responses return the resource object directly or a wrapper object containing a data array for list endpoints. Errors follow a consistent shape — see the [Errors reference](/api/errors) for details.

## Versioning

The current API version is **v1**. The version is part of the URL path, not a header. Nonhumans will not make breaking changes within a version; additive changes (new fields, new endpoints) may be introduced at any time and will not be considered breaking.

## Rate Limits

Rate limits are applied per API key. When you exceed your limit the API returns `429 Too Many Requests` with a `Retry-After` header indicating how many seconds to wait before retrying. Default limits vary by plan. [Contact us](https://nonhumans.ai/contact) if you need higher throughput for your agent workloads.

## Pagination

List endpoints use **cursor-based pagination**. Pass `limit` and `cursor` as query parameters; the response includes a `next_cursor` field. When `next_cursor` is `null`, you have reached the end of the list.

| Parameter | Type    | Description                                               |
| --------- | ------- | --------------------------------------------------------- |
| `limit`   | integer | Number of items to return. Default `20`, max `100`.       |
| `cursor`  | string  | Opaque cursor from the previous response's `next_cursor`. |

**Example paginated response shape:**

```json theme={null}
{
  "data": [...],
  "next_cursor": "cur_01HXYZ..."
}
```

## API Resource Groups

Every capability your agent has is exposed as a named resource group under `/v1`:

| Resource    | Base Path     | Description                                                       |
| ----------- | ------------- | ----------------------------------------------------------------- |
| **Agent**   | `/v1/agent`   | Agent profile, public identity, and verifiable credentials        |
| **Email**   | `/v1/email`   | Send and receive email from the agent's inbox                     |
| **Phone**   | `/v1/phone`   | Send SMS, initiate voice calls, list inbound messages             |
| **Wallet**  | `/v1/wallet`  | Fiat and crypto balances, payments, invoices, and virtual cards   |
| **Compute** | `/v1/compute` | Sandboxed code execution, headless browser, persistent filesystem |
| **Memory**  | `/v1/memory`  | Vector memory store, semantic search, and file drive              |
| **Vault**   | `/v1/vault`   | Encrypted credential and secret storage                           |
| **Models**  | `/v1/models`  | LLM inference with automatic billing through the agent's wallet   |

## SDK Alternatives

If you prefer a typed client over raw HTTP, Nonhumans provides first-party SDKs:

* [TypeScript SDK](/sdk/typescript) — full type safety, auto-pagination helpers, and error classes
* [Python SDK](/sdk/python) — sync and async clients, Pydantic response models

<Tip>
  The SDKs mirror the REST API one-to-one, so this reference doubles as SDK documentation. Method names follow the resource path — for example, `POST /v1/email/send` becomes `client.email.send(...)`.
</Tip>