Skip to main content
You can call the Avala API directly over HTTP from any programming language, shell script, or automation tool. No SDK required.

​
Base URL

All API requests are made to: 
https://server.avala.ai/api/v1

​
Authentication

Every request must include your API key in the X-Avala-Api-Key header. 
X-Avala-Api-Key: your-api-key
You can find your API key in the Avala dashboard under Settings > API Keys.

​
Making Requests

Below are examples of listing datasets across several languages. 
curl -X GET "https://server.avala.ai/api/v1/datasets" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY" \
  -H "Content-Type: application/json"

​
Handling Pagination

List endpoints return paginated results. The response includes a cursor field that you use to fetch the next page of results. When there are no more results, has_more is false. Response structure: 
{
  "items": [...],
  "total": 142,
  "has_more": true,
  "cursor": "eyJpZCI6IjEyMyJ9"
}
Paginating through all results: 
# First page
curl -s "https://server.avala.ai/api/v1/datasets?limit=50" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY" | jq .

# Next page (use cursor from previous response)
curl -s "https://server.avala.ai/api/v1/datasets?limit=50&cursor=eyJpZCI6IjEyMyJ9" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY" | jq .

​
Error Handling

The API returns standard HTTP status codes. Error responses include a JSON body with details. Error response format: 
{
  "error": {
    "code": "not_found",
    "message": "Dataset not found",
    "details": []
  }
}
Status CodeMeaning
200Success
201Created
400Bad request — check the request body or parameters.
401Unauthorized — invalid or missing API key.
404Not found — the resource does not exist.
422Validation error — the request body failed validation. Check error.details.
429Rate limited — too many requests. Respect the Retry-After header.
500Internal server error — try again later.
When you receive a 429 response, always check the Retry-After header for the number of seconds to wait before retrying.

​
File Uploads

Some endpoints accept file uploads via multipart/form-data. Do not set the Content-Type header manually when uploading files — let your HTTP client set the boundary automatically. 
curl -X POST "https://server.avala.ai/api/v1/datasets/dataset_abc123/items" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY" \
  -F "file=@./data.jsonl"

​
Common Patterns

​
List All Items with Pagination

This pattern fetches every item in a dataset by following pagination cursors until all pages have been retrieved. 
import requests
import os

base_url = "https://server.avala.ai/api/v1"
headers = {"X-Avala-Api-Key": os.environ["AVALA_API_KEY"]}

def get_all_items(dataset_id):
    items = []
    cursor = None

    while True:
        params = {"limit": 100}
        if cursor:
            params["cursor"] = cursor

        response = requests.get(
            f"{base_url}/datasets/{dataset_id}/items",
            headers=headers,
            params=params,
        )
        response.raise_for_status()
        data = response.json()

        items.extend(data["items"])

        if not data["has_more"]:
            break
        cursor = data["cursor"]

    return items

all_items = get_all_items("dataset_abc123")
print(f"Total items: {len(all_items)}")

​
Create and Wait for an Export

This pattern starts an export job and polls until it finishes, then retrieves the download URL. 
# Start the export
EXPORT=$(curl -s -X POST "https://server.avala.ai/api/v1/exports" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id": "project_abc123", "format": "json"}')

EXPORT_ID=$(echo $EXPORT | jq -r '.id')
echo "Export started: $EXPORT_ID"

# Poll until completed
while true; do
  STATUS=$(curl -s "https://server.avala.ai/api/v1/exports/$EXPORT_ID" \
    -H "X-Avala-Api-Key: $AVALA_API_KEY" | jq -r '.status')

  echo "Status: $STATUS"

  if [ "$STATUS" = "completed" ]; then
    break
  fi

  sleep 2
done

# Get the download URL
DOWNLOAD_URL=$(curl -s "https://server.avala.ai/api/v1/exports/$EXPORT_ID" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY" | jq -r '.download_url')

echo "Download: $DOWNLOAD_URL"