REST API

Base URL: https://api.attoscloud.com/api/v1. All endpoints return JSON. Binary blob delivery uses a dedicated sync endpoint consumed directly by SDK Synchronizers.

Authentication

Pass your API key in the X-API-Key header on every request. Keys are generated in the dashboard under Settings → API Keys.

curl https://api.attoscloud.com/api/v1/datasets \
  -H "X-API-Key: at_live_9f3a21b47c02"

GET /datasets/sync/:dataset_id

Streams the compiled .attos binary for the specified dataset. This is the endpoint polled by SDK Synchronizers on every sync cycle. The response body is the raw binary; a X-Attos-Config response header carries a JSON object controlling SDK-side settings such as telemetry opt-in state.

curl -o data.attos \
  -H "X-Attos-Node-ID: $(hostname)" \
  -H "X-API-Key: $ATTOS_KEY" \
  "https://api.attoscloud.com/api/v1/datasets/sync/ds_a1b2c3d4"

PUT /datasets/:id/data

Upload new CSV or NDJSON source data for an existing dataset. The control plane runs the Go builder (Builder.BuildFromCSV or Builder.BuildFromNDJSON), compiles a new .attos binary, stores it atomically in object storage (GCS), and the next SDK sync poll picks it up automatically. Rejected uploads (402/429) change nothing.

curl -X PUT \
  "https://api.attoscloud.com/api/v1/datasets/ds_a1b2c3d4/data" \
  -H "X-API-Key: $ATTOS_KEY" \
  -F "file=@users.csv"

Response

{
  "id":        "6f1c2a9e-4b7d-4a8e-9c1f-2d3e4f5a6b7c",
  "name":      "users",
  "row_count": 1000,
  "blob_size": 32768,
  "status":    "ready"
}

Rate limits

Only the sign-up, login, password-reset, lead and checkout endpoints are rate limited, per client IP (2 requests per second, bursts of 5). Over that they answer 429 with {"error": "Too many requests. Please try again later."} and no Retry-After header. The dataset and sync endpoints have no request-rate limit; they are bound by the plan limits below.

Plans, limits & error codes

Limits belong to the project. Monthly limits reset on the 1st of each month (UTC). Pro and Enterprise projects choose overage separately for dataset updates, active nodes and sync bandwidth (Billing settings; all on by default). A meter with overage on keeps working past its included amount and the extra usage is billed; with it off, that meter stops at the included amount like Free, with the code overage_disabled.

Active nodes are distinct X-Attos-Node-IDs that synced in the last 5 minutes. Extra nodes are billed once a month on the average of the month's hourly node counts. Bandwidth counts the bytes of sync responses; a 304 counts as zero.

Error body

Every plan-limit rejection has the same JSON shape. error is a human-readable message, code is stable, limit_kind names the limit (it differs from code only for overage_disabled). A 429 also carries Retry-After: the seconds until the monthly reset.

{
  "error":       "Free projects include 10 GB of sync bandwidth per month and it is used up. ...",
  "code":        "bandwidth_limit",
  "status":      402,
  "limit_kind":  "bandwidth_limit",
  "limit":       10000000000,
  "used":        10000482113,
  "upgrade_url": "/dashboard/billing"
}

POST /datasets/compile

Create a new dataset from source data in a single request. The attos_value column is mandatory; all other columns are treated as composite key dimensions and sorted alphabetically.

curl -X POST https://api.attoscloud.com/api/v1/datasets/compile \
  -H "X-API-Key: $ATTOS_KEY" \
  -F "file=@users.ndjson" \
  -F "name=edge-router"

{
  "id":        "0b7e5c3d-2f1a-4c6b-8d9e-1a2b3c4d5e6f",
  "name":      "edge-router",
  "row_count": 12400000,
  "blob_size": 32505856,
  "status":    "ready"
}