REST API

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://api.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 > Security.

Making Requests

Below are examples of listing datasets across several languages.

curl -X GET "https://api.avala.ai/api/v1/datasets/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY" \
  -H "Content-Type: application/json"

import requests
import os

response = requests.get(
    "https://api.avala.ai/api/v1/datasets/",
    headers={
        "X-Avala-Api-Key": os.environ["AVALA_API_KEY"],
        "Content-Type": "application/json",
    },
)

data = response.json()
for dataset in data["results"]:
    print(dataset["name"], dataset["uid"])

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.avala.ai/api/v1/datasets/", nil)
	req.Header.Set("X-Avala-Api-Key", os.Getenv("AVALA_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var result map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&result)
	fmt.Println(result)
}

require "net/http"
require "json"

uri = URI("https://api.avala.ai/api/v1/datasets/")

request = Net::HTTP::Get.new(uri)
request["X-Avala-Api-Key"] = ENV["AVALA_API_KEY"]
request["Content-Type"] = "application/json"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)
data["results"].each do |dataset|
  puts "#{dataset["name"]} (#{dataset["uid"]})"
end

<?php

$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL => "https://api.avala.ai/api/v1/datasets/",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "X-Avala-Api-Key: " . getenv("AVALA_API_KEY"),
        "Content-Type: application/json",
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
foreach ($data["results"] as $dataset) {
    echo $dataset["name"] . " (" . $dataset["uid"] . ")\n";
}

Handling Pagination

List endpoints return paginated results using cursor-based pagination with next, previous, and results fields. Response structure:

{
  "next": "https://api.avala.ai/api/v1/datasets/?cursor=cD0yMDI0...",
  "previous": null,
  "results": [...]
}

Field	Type	Description
`next`	string \| null	URL for the next page, or `null` if this is the last page
`previous`	string \| null	URL for the previous page, or `null` if this is the first page
`results`	array	Array of resource objects for the current page

Paginating through all results:

# First page
curl -s "https://api.avala.ai/api/v1/datasets/?limit=50" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY" | jq .

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

import requests
import os

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

all_datasets = []
url = f"{base_url}/datasets/?limit=50"

while url:
    response = requests.get(url, headers=headers)
    data = response.json()

    all_datasets.extend(data["results"])
    url = data.get("next")

print(f"Fetched {len(all_datasets)} datasets")

Error Handling

The API returns standard HTTP status codes. Error responses include a JSON body with details. Error response format:

{
  "detail": "Not found."
}

For validation errors, DRF returns field-level errors:

{
  "field_name": ["This field is required."]
}

Status Code	Meaning
`200`	Success
`201`	Created
`400`	Bad request — check the `detail` field or field-level errors in the response body.
`401`	Unauthorized — invalid or missing API key.
`404`	Not found — the resource does not exist.
`429`	Rate limited — too many requests. Respect the `Retry-After` header.
`500`	Internal server error — try again later.

Handling Errors in Code

import requests
import os
import time

headers = {"X-Avala-Api-Key": os.environ["AVALA_API_KEY"]}

response = requests.get(
    "https://api.avala.ai/api/v1/datasets/nonexistent/",
    headers=headers,
)

if response.status_code == 200:
    data = response.json()
elif response.status_code == 401:
    print("Invalid API key. Check your AVALA_API_KEY.")
elif response.status_code == 404:
    print("Resource not found.")
elif response.status_code == 429:
    retry_after = int(response.headers.get("Retry-After", 60))
    print(f"Rate limited. Retrying in {retry_after}s...")
    time.sleep(retry_after)
else:
    print(f"Error {response.status_code}: {response.json().get('detail', 'Unknown error')}")

# Check the HTTP status code
STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  "https://api.avala.ai/api/v1/datasets/nonexistent/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY")

if [ "$STATUS" = "429" ]; then
  echo "Rate limited. Check Retry-After header."
elif [ "$STATUS" != "200" ]; then
  echo "Error: HTTP $STATUS"
fi

When you receive a 429 response, always check the Retry-After header for the number of seconds to wait before retrying. The X-RateLimit-Remaining header on every response tells you how many requests you have left.

File Uploads

File uploads use presigned URLs rather than direct multipart uploads to the API. The general flow is:

Request a presigned upload URL from the API
Upload the file directly to cloud storage using the presigned URL
Confirm the upload with the API

# Step 1: Request presigned URL
UPLOAD_INFO=$(curl -s -X POST "https://api.avala.ai/api/v1/datasets/manual-upload/file-upload-url/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_path_in_dataset": "image001.jpg", "dataset_name": "my-dataset"}')

PRESIGNED_URL=$(echo $UPLOAD_INFO | jq -r '.url')

# Step 2: Upload to cloud storage using the presigned POST fields
# All fields from the response must be included as form data
curl -X POST "$PRESIGNED_URL" \
  $(echo $UPLOAD_INFO | jq -r '.fields | to_entries[] | "-F \(.key)=\(.value)"') \
  -F "file=@./image001.jpg"

import requests
import os

headers = {"X-Avala-Api-Key": os.environ["AVALA_API_KEY"]}

# Step 1: Request presigned URL
response = requests.post(
    "https://api.avala.ai/api/v1/datasets/manual-upload/file-upload-url/",
    headers=headers,
    json={"file_path_in_dataset": "image001.jpg", "dataset_name": "my-dataset"},
)
upload_info = response.json()

# Step 2: Upload to cloud storage using the presigned POST fields
with open("image001.jpg", "rb") as f:
    requests.post(
        upload_info["url"],
        data=upload_info["fields"],
        files={"file": ("image001.jpg", f)},
    )

Common Patterns

List All Items with Pagination

This pattern fetches every item in a dataset by following pagination URLs until all pages have been retrieved.

import requests
import os

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

def get_all_items(owner, slug):
    items = []
    url = f"{base_url}/datasets/{owner}/{slug}/items/?limit=100"

    while url:
        response = requests.get(url, headers=headers)
        response.raise_for_status()
        data = response.json()

        items.extend(data["results"])
        url = data.get("next")

    return items

all_items = get_all_items("acme-ai", "training-v2")
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://api.avala.ai/api/v1/exports/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id": "project_abc123"}')

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

# Poll until completed
while true; do
  STATUS=$(curl -s "https://api.avala.ai/api/v1/exports/$EXPORT_UID/" \
    -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://api.avala.ai/api/v1/exports/$EXPORT_UID/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY" | jq -r '.download_url')

echo "Download: $DOWNLOAD_URL"

SDKs

SDK Reference

Base URL

Authentication

Making Requests

Error Handling

Handling Errors in Code

File Uploads

Common Patterns

Create and Wait for an Export

​Base URL

​Authentication

​Making Requests

​Handling Pagination

​Error Handling

​Handling Errors in Code

​File Uploads

​Common Patterns

​List All Items with Pagination

​Create and Wait for an Export

Base URL

Authentication

Making Requests

Handling Pagination

Error Handling

Handling Errors in Code

File Uploads

Common Patterns

List All Items with Pagination

Create and Wait for an Export