Agent Therapy API Reference: Overview and Conventions

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:

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.

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:

{
  "data": {
    "id": "agt_01j9z3kx2m4n8p7q",
    "name": "Support Bot",
    "status": "active"
  }
}

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

{
  "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:

{
  "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:

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.

Overview

Endpoints

Webhooks

Agent Therapy API Reference: Overview and Conventions

Base URL

Request Format

Response Format

Rate Limits

Error Codes

SDKs

​Base URL

​Request Format

​Response Format

​Rate Limits

​Pagination

​Error Codes

​SDKs

Base URL

Request Format

Response Format

Rate Limits

Pagination

Error Codes

SDKs