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

# API Overview

> Base URLs, authentication headers, pagination, and error response standards.

The Wirebox REST API provides programmatic access to manage agent identities, mailboxes, messages, and webhooks.

## Base URL

| Environment    | Base URL                                |
| :------------- | :-------------------------------------- |
| **Production** | `https://api.wirebox.sh/api/v1`         |
| **Staging**    | `https://staging-api.wirebox.sh/api/v1` |

***

## Authentication

Every API call must include an active API key in the `Authorization` header:

```http theme={null}
Authorization: Bearer wb_live_xxxxxxxxxxxxxxxxxxxxxxxx
```

***

## Response Format

All successful responses return HTTP status `200 OK` or `201 Created` with a JSON payload. Deletions return `204 No Content`.

***

## Error Handling

When an error occurs, Wirebox returns standard HTTP 4xx or 5xx status codes along with a structured JSON error object:

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "Detailed human-readable explanation of what went wrong."
  }
}
```

### Common Error Codes

| HTTP Status | Code              | Meaning                                                                |
| :---------- | :---------------- | :--------------------------------------------------------------------- |
| **400**     | `invalid_request` | The request body or query parameter failed validation.                 |
| **401**     | `unauthorized`    | Missing or invalid API key.                                            |
| **403**     | `forbidden`       | The API key does not have permission to access the requested resource. |
| **404**     | `not_found`       | The requested identity, thread, message, or webhook does not exist.    |
| **409**     | `conflict`        | The handle is already claimed or resource already exists.              |
| **429**     | `rate_limited`    | Rate limit exceeded. Back off and retry.                               |
| **500**     | `internal_error`  | Wirebox edge error. Check status or reach out to support.              |