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

# API Overview

> The Wardin REST API — versioned, cursor-paginated, structured errors.

The Wardin REST API lets you manage keys, budgets, policies, and pull analytics data programmatically. It's the same API the Wardin dashboard uses internally.

## Base URL

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

## Authentication

All API requests require a `wardin_sk_` key in the `Authorization` header:

```bash theme={null}
Authorization: Bearer wardin_sk_YOUR_KEY
```

The key must belong to a user with manager-level access to perform write operations. Read operations (analytics, key listing) work with any valid key.

See [Authentication](/api-reference/authentication) for details.

## Versioning

The API is versioned in the URL path (`/api/v1/`). Breaking changes (field removal, type change) require a new version with a 6-month deprecation window on the previous version. Adding optional fields is non-breaking and does not require a new version.

## Response format

All responses are JSON. Success responses return the resource directly (no wrapper envelope):

```json theme={null}
{
  "id": "key_01j...",
  "name": "alice-dev",
  "monthlyBudgetUsd": 100,
  "currentSpendUsd": 42.17,
  "createdAt": "2025-01-15T10:00:00Z"
}
```

List responses use cursor pagination:

```json theme={null}
{
  "data": [...],
  "nextCursor": "cursor_01j...",
  "hasMore": true
}
```

Pass `?cursor=cursor_01j...` to fetch the next page. Default page size is 50.

## Error format

All errors use the same structured shape:

```json theme={null}
{
  "error": {
    "type": "budget_exceeded",
    "message": "Monthly budget of $50.00 has been reached.",
    "code": 429
  }
}
```

| HTTP status | `type`                | Meaning                                 |
| ----------- | --------------------- | --------------------------------------- |
| 400         | `validation_error`    | Invalid request body                    |
| 401         | `unauthorized`        | Missing or invalid API key              |
| 403         | `forbidden`           | Key lacks permission for this operation |
| 403         | `policy_violation`    | Request blocked by a policy             |
| 404         | `not_found`           | Resource does not exist                 |
| 429         | `budget_exceeded`     | Monthly budget reached                  |
| 429         | `rate_limit_exceeded` | RPM or TPM limit reached                |
| 500         | `internal_error`      | Unexpected server error                 |

## Interactive docs

The full interactive API reference (powered by Swagger UI) is available at:

```
https://api.wardin.ai/docs
```

Machine-readable OpenAPI JSON:

```
https://api.wardin.ai/docs-json
```

## Rate limits on the API itself

Management API calls (not gateway proxy calls) are limited to 120 requests per minute per key. This limit is separate from the gateway proxy rate limits configured on keys.