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

# Agent Therapy API Reference: Overview and Conventions

> The Agent Therapy REST API lets you register agents, run diagnostic sessions, retrieve findings, and apply interventions programmatically.

The Agent Therapy REST API gives you full programmatic control over every aspect of the platform — registering agents, submitting behavior logs for analysis, retrieving diagnostic findings, and applying corrective interventions. All requests are made over HTTPS to the versioned base URL, and all request and response bodies use JSON. The API is versioned at `/v1`; breaking changes will only be introduced in new major versions.

## Base URL

Every API request you make must be directed to the following base URL:

```bash theme={null}
https://api.agenttherapy.ai/v1
```

Append the endpoint path directly to this base URL — for example, `https://api.agenttherapy.ai/v1/agents`.

## Request Format

All requests that include a body (POST, PATCH) must set the `Content-Type` header to `application/json`. Every request — regardless of method — must include a valid `Authorization` header.

```bash theme={null}
curl https://api.agenttherapy.ai/v1/agents \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer at_your_key_here"
```

| Header | Value |
| - | - |
| `Content-Type` | `application/json` |
| `Authorization` | `Bearer <your_api_key>` |

## Response Format

All responses are JSON. Successful responses wrap the returned resource or list in a `data` envelope:

```json theme={null}
{
  "data": {
    "id": "agt_01j9z3kx2m4n8p7q",
    "name": "Support Bot",
    "status": "active"
  }
}
```

Error responses follow a consistent structure with an `error` object that contains three fields:

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "The 'name' field is required.",
    "details": {
      "field": "name",
      "issue": "missing_required_field"
    }
  }
}
```

| Field | Type | Description |
| - | - | - |
| `error.code` | string | A machine-readable error code slug |
| `error.message` | string | A human-readable description of the error |
| `error.details` | object | Additional context about the error, such as the offending field |

## Rate Limits

Rate limits are enforced per API key on a rolling one-minute window. The limits by plan are:

| Plan | Requests per Minute |
| - | - |
| Free | 60 |
| Pro | 300 |
| Enterprise | Custom — contact your account manager |

Every API response includes the following headers so you can track your current usage:

| Header | Description |
| - | - |
| `X-RateLimit-Limit` | The maximum number of requests allowed in the current window |
| `X-RateLimit-Remaining` | The number of requests you have left in the current window |
| `X-RateLimit-Reset` | Unix timestamp (UTC) indicating when the current window resets |

When you exceed your rate limit, the API returns a `429 Too Many Requests` response. Wait until the time indicated in `X-RateLimit-Reset` before retrying.

## Pagination

List endpoints use **cursor-based pagination**, which is more stable than offset-based pagination for datasets that change frequently. Use the `limit` and `cursor` query parameters to page through results.

| Parameter | Type | Description |
| - | - | - |
| `limit` | integer | Number of records to return per page. Defaults to `20`, maximum `100`. |
| `cursor` | string | An opaque cursor string from the previous page's `next_cursor` value. Omit for the first request. |

Every list response includes pagination metadata alongside the `data` array:

```json theme={null}
{
  "data": [...],
  "next_cursor": "cur_01j9z3kx2m4n8p7q",
  "has_more": true
}
```

When `has_more` is `false`, you have reached the last page. When it is `true`, pass the value of `next_cursor` as the `cursor` parameter in your next request.

## Error Codes

| HTTP Status | Meaning |
| - | - |
| `400 Bad Request` | The request was malformed or missing required fields |
| `401 Unauthorized` | No valid API key was provided |
| `403 Forbidden` | Your API key does not have permission to perform this action |
| `404 Not Found` | The requested resource does not exist |
| `422 Unprocessable Entity` | The request was well-formed but failed semantic validation |
| `429 Too Many Requests` | You have exceeded your rate limit |
| `500 Internal Server Error` | Something went wrong on Agent Therapy's side — please retry with exponential backoff |

## SDKs

Agent Therapy provides an official **Python SDK** that wraps the REST API with idiomatic, typed interfaces. Install it from PyPI:

```bash theme={null}
pip install agent-therapy-sdk
```

The SDK handles authentication, retries, and pagination automatically so you can focus on building. For full setup instructions, framework-specific patterns, and code examples, see the [integration guides](https://vizmaxxing.com/integrations/openai.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.