API Reference

The ALaaS API is plain JSON over HTTPS. Everything below works with curl - no SDK required.

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, embed 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. embed images (repeat 'files' + 'external_ids' per image)
curl -s -X POST https://api.alaas2.com/v1/pools/$POOL/embed-batch \
  -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"

POST/v1/pools/{pool_id}/embed-batch

Multipart upload. Send N files parts and N matching external_ids (any stable per-image ID, e.g. the relative path). Images become embeddings; the originals are not stored.

curl -s -X POST https://api.alaas2.com/v1/pools/$POOL/embed-batch \
  -H "Authorization: Bearer $ALAAS_API_KEY" \
  -F "files=@a.jpg" -F "external_ids=a.jpg" \
  -F "files=@b.jpg" -F "external_ids=b.jpg"
# -> {"embedded":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":[...]}

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_has_no_embeddings, 409 pool_exhausted.

Pricing

1 credit = $0.0001. Embed = 5 credits/image. Select = 10 + 1% of pool size. New accounts start with 10,000 free credits.

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.