Skip to main content

​
Base URL

All API requests are made to the following base URL: 
https://api.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://api.avala.ai/api/v1/agents \
  -H "X-Avala-Api-Key: avk_..."
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://api.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.

​
Pagination Best Practices

  • Use limit to control page size. Default is 100. Use smaller pages (10-25) for interactive UIs, larger pages (100) for batch processing.
  • Follow next URLs directly. Don’t construct pagination URLs manually. The next URL includes the correct cursor and any filters you applied.
  • Handle empty pages. A page with an empty results array and next: null means you’ve reached the end.
  • Don’t assume page sizes. The last page may contain fewer items than limit.
  • Use the Python SDK for automatic pagination: client.datasets.list() returns a CursorPage with has_more and next_cursor attributes.
# Paginate through all datasets
import requests

headers = {"X-Avala-Api-Key": "YOUR_API_KEY"}
url = "https://api.avala.ai/api/v1/datasets/?limit=50"

all_datasets = []
while url:
    response = requests.get(url, headers=headers)
    data = response.json()
    all_datasets.extend(data["results"])
    url = data["next"]  # None when no more pages

print(f"Total datasets: {len(all_datasets)}")

​
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
Burst20 requests per second
Inference10 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.