ALaaS

API Reference

The ALaaS API is plain JSON over HTTPS. Everything below works with curl - no SDK required. Prefer a CLI? pip install alaas-cli.

Base URL

https://api.alaas2.com

Authentication

Create a key under API Keys and send it as a Bearer token on every request.

export ALAAS_API_KEY=alaas_live_xxxxxxxxxxxx

Quickstart

Create a pool, upload images, then ask for the most useful ones to label.

# 1. create a pool
POOL=$(curl -s https://api.alaas2.com/v1/pools \
  -H "Authorization: Bearer $ALAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-dataset"}' | jq -r .id)

# 2. upload images (repeat 'files' + 'external_ids' per image)
curl -s -X POST https://api.alaas2.com/v1/pools/$POOL/images \
  -H "Authorization: Bearer $ALAAS_API_KEY" \
  -F "files=@cat.jpg"  -F "external_ids=cat.jpg" \
  -F "files=@dog.jpg"  -F "external_ids=dog.jpg"

# 3. select what to label next
curl -s -X POST https://api.alaas2.com/v1/pools/$POOL/select \
  -H "Authorization: Bearer $ALAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"n_clusters":50,"strategy":"coverage"}'

Endpoints

POST/v1/pools
Create a pool.
curl -s https://api.alaas2.com/v1/pools \
  -H "Authorization: Bearer $ALAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-dataset"}'
# -> {"id":"<pool_id>","name":"my-dataset","status":"active"}
GET/v1/pools
List your pools.
curl -s https://api.alaas2.com/v1/pools -H "Authorization: Bearer $ALAAS_API_KEY"
GET/v1/pools/{pool_id}
Pool details with progress counters. remaining_images tells you how many images a future select can still draw from; 0 means the next select returns pool_exhausted.
curl -s https://api.alaas2.com/v1/pools/$POOL -H "Authorization: Bearer $ALAAS_API_KEY"
# -> {"id":"...","name":"my-dataset","status":"active",
#     "total_images":60,"selected_images":20,"remaining_images":40}
POST/v1/pools/{pool_id}/images
Multipart upload. Send N files parts and N matching external_ids (any stable per-image ID, e.g. the relative path). Images are processed right away; the originals are never stored. The first request after idle can take about a minute while compute spins up.
curl -s -X POST https://api.alaas2.com/v1/pools/$POOL/images \
  -H "Authorization: Bearer $ALAAS_API_KEY" \
  -F "files=@a.jpg" -F "external_ids=a.jpg" \
  -F "files=@b.jpg" -F "external_ids=b.jpg"
# -> {"uploaded":2,"pool_id":"<pool_id>"}
POST/v1/pools/{pool_id}/select
Return the most useful images to label next. strategy: coverage (default, best for training) or explore (also surfaces edge cases). Selected images are never returned again, so repeated calls progressively cover the rest of the dataset.
curl -s -X POST https://api.alaas2.com/v1/pools/$POOL/select \
  -H "Authorization: Bearer $ALAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"n_clusters":50,"strategy":"coverage"}'
# -> {"selection_id":"...","pool_id":"...","representatives":[...],"outliers":[...]}
DELETE/v1/pools/{pool_id}
Permanently deletes the pool and all data derived from its images, including past selection results. Cannot be undone; spent credits are not refunded. Returns 204.
curl -s -X DELETE https://api.alaas2.com/v1/pools/$POOL -H "Authorization: Bearer $ALAAS_API_KEY"
GET/v1/selections/{selection_id}
Fetch a previous selection result.
curl -s https://api.alaas2.com/v1/selections/$SELECTION_ID \
  -H "Authorization: Bearer $ALAAS_API_KEY"
GET/v1/usage
Current credits balance.
curl -s https://api.alaas2.com/v1/usage -H "Authorization: Bearer $ALAAS_API_KEY"
# -> {"credits_balance":100000}

Errors

Every error uses the same shape:

{"error":{"code":"insufficient_credits","message":"...","details":null}}

Common codes: 401 invalid_api_key, 402 insufficient_credits, 404 pool_not_found / pool_empty, 409 pool_exhausted.

Pricing

1 credit = $0.0001. Upload = 5 credits per image. Select = 10 credits per run + 25 credits per returned candidate. You only pay for candidates actually delivered. New accounts start with 10,000 free credits.

Example: upload 10,000 images (50,000 credits = $5) and run 3 selection rounds of 300 candidates each (~22,500 credits = $2.25). Total $7.25 for a workflow that typically replaces hundreds of dollars of labelling budget.

Machine-readable spec

Built for agents: the full OpenAPI spec is public at https://api.alaas2.com/openapi.json, with an interactive explorer at https://api.alaas2.com/docs.