Skip to main content

​
Base URL

All API requests are made to the following base URL: 
https://server.avala.ai/api/v1
All requests must be made over HTTPS. Requests over plain HTTP will be rejected.

​
Authentication

Authenticate every request by including your API key in the X-Avala-Api-Key header: 
curl https://server.avala.ai/api/v1/agents \
  -H "X-Avala-Api-Key: avala_sk_..."
API keys are created in Mission Control. See the Authentication page for full details on creating and managing keys.

​
Request Format

The API accepts JSON-encoded request bodies. Set the Content-Type header for requests with a body:
HeaderValue
X-Avala-Api-KeyYour API key
Content-Typeapplication/json

​
Response Format

All responses return JSON. Successful responses use standard HTTP status codes (200, 201, 204). Single resource: 
{
  "id": "agt_abc123",
  "name": "Research Agent",
  "status": "active",
  "created_at": "2025-09-15T08:30:00Z"
}
Paginated list: 
{
  "next": "https://server.avala.ai/api/v1/agents?cursor=abc123",
  "previous": null,
  "results": [
    {
      "id": "agt_abc123",
      "name": "Research Agent"
    }
  ]
}

​
Pagination

List endpoints return paginated results using cursor-based pagination. The response includes:
FieldTypeDescription
nextstring | nullURL for the next page of results, or null if this is the last page
previousstring | nullURL for the previous page of results, or null if this is the first page
resultsarrayArray of resource objects
To paginate through results, follow the next URL until it returns null.

​
Error Codes

When a request fails, the API returns an appropriate HTTP status code with a JSON error body: 
{
  "detail": "A human-readable description of the error."
}
Status CodeDescription
400Bad Request — The request body is invalid or missing required fields.
401Unauthorized — API key is missing, invalid, or expired.
403Forbidden — The API key does not have permission for this action.
404Not Found — The requested resource does not exist.
429Too Many Requests — You have exceeded the rate limit.
500Internal Server Error — Something went wrong on our end.
See the Error Codes page for detailed descriptions and remediation steps.

​
Rate Limits

The API enforces the following rate limits:
LimitValue
Standard requests100 requests per minute
Concurrent uploads10 simultaneous uploads
Concurrent exports5 simultaneous exports
When you exceed a rate limit, the API returns a 429 status code. Use the rate limit headers to manage your request volume:
HeaderDescription
X-RateLimit-LimitMaximum number of requests allowed in the current window
X-RateLimit-RemainingNumber of requests remaining in the current window
X-RateLimit-ResetUnix timestamp (seconds) when the current window resets

​
Interactive API Docs

Explore and test every endpoint directly in your browser with the interactive API documentation:

Interactive API Reference

Try endpoints, inspect request and response schemas, and generate code samples.