Authenticate with your key

#!/usr/bin/env bash
# First authenticated read. Either key works on shared routes such as /sandbox and /missions.
# Head Office routes need lab_off_, Factory routes need lab_fac_ (wrong key = 403 wrong_system).
set -euo pipefail
BASE="${ATLAS_BASE:-https://automationatlas.io/labs/api/v1}"
: "${ATLAS_OFFICE_KEY:?run: source atlas-keys.env}"

# Status: cash, inventory, expires_in_s, extensions_left
curl -sS "$BASE/sandbox" -H "Authorization: Bearer $ATLAS_OFFICE_KEY" \
  | jq '{cash_minor: .data.cash_minor, expires_in_s: .data.expires_in_s, inventory: .data.inventory}'

# Head Office read: sales orders, newest first
curl -sS "$BASE/office/sales-orders?limit=5" -H "Authorization: Bearer $ATLAS_OFFICE_KEY" \
  | jq '.data.items[] | {id, quantity, status}'

# Missions: what to try next, detected from what you actually did
curl -sS "$BASE/missions" -H "Authorization: Bearer $ATLAS_OFFICE_KEY" \
  | jq '.data.items[] | select(.status == "active") | {id, objective, hint}'

// First authenticated read (Node 20+).  Run after: source atlas-keys.env
const BASE = process.env.ATLAS_BASE ?? "https://automationatlas.io/labs/api/v1";
const KEY = process.env.ATLAS_OFFICE_KEY; // lab_off_...; Factory routes need ATLAS_FACTORY_KEY
if (!KEY) throw new Error("run: source atlas-keys.env");

async function get(path) {
  const res = await fetch(`${BASE}${path}`, { headers: { Authorization: `Bearer ${KEY}` } });
  const json = await res.json();
  if (!res.ok) throw new Error(`${res.status} ${json.error.code}: ${json.error.hint ?? json.error.message}`);
  return json.data;
}

const status = await get("/sandbox");
console.log("cash_minor", status.cash_minor, "expires_in_s", status.expires_in_s);

const { items: orders } = await get("/office/sales-orders?limit=5");
for (const o of orders) console.log(o.id, o.quantity, o.status);

const { items: missions } = await get("/missions");
console.log(missions.filter((m) => m.status === "active").map((m) => m.objective));

"""First authenticated read.  pip install requests; then: source atlas-keys.env"""
import os

import requests

BASE = os.environ.get("ATLAS_BASE", "https://automationatlas.io/labs/api/v1")
KEY = os.environ["ATLAS_OFFICE_KEY"]  # lab_off_...; Factory routes need ATLAS_FACTORY_KEY
HEADERS = {"Authorization": f"Bearer {KEY}"}


def get(path):
    res = requests.get(f"{BASE}{path}", headers=HEADERS, timeout=30)
    body = res.json()
    if not res.ok:
        err = body["error"]
        raise SystemExit(f"{res.status_code} {err['code']}: {err.get('hint') or err['message']}")
    return body["data"]


status = get("/sandbox")
print("cash_minor", status["cash_minor"], "expires_in_s", status["expires_in_s"])

for order in get("/office/sales-orders?limit=5")["items"]:
    print(order["id"], order["quantity"], order["status"])

print([m["objective"] for m in get("/missions")["items"] if m["status"] == "active"])

#!/usr/bin/env bash
# First write with an Idempotency-Key: accept a received sales order.
# Same key + same request = the original response again (header Idempotency-Replayed: true).
# Same key + a different path or body = 422 idempotency_key_reused.
set -euo pipefail
BASE="${ATLAS_BASE:-https://automationatlas.io/labs/api/v1}"
: "${ATLAS_OFFICE_KEY:?run: source atlas-keys.env}"

ORDER=$(curl -sS "$BASE/office/sales-orders?limit=20" -H "Authorization: Bearer $ATLAS_OFFICE_KEY" \
  | jq -r '[.data.items[] | select(.status == "received")][0].id')
[ "$ORDER" != "null" ] || { echo "no received sales order left to accept" >&2; exit 1; }
echo "accepting $ORDER"

# Derive the key from the action, so a retry after a crash reuses it (max 64 characters).
KEY="accept-$ORDER"
for attempt in 1 2; do
  curl -sS -D - -o body.tmp -X POST "$BASE/office/sales-orders/$ORDER/accept" \
    -H "Authorization: Bearer $ATLAS_OFFICE_KEY" \
    -H "Idempotency-Key: $KEY" | grep -iE '^(HTTP/|idempotency-replayed)' || true
  jq -c '.data | {id, status}' body.tmp
done
rm -f body.tmp

// First write with an Idempotency-Key (Node 20+).  Run after: source atlas-keys.env
// Same key + same request = the original response again (Idempotency-Replayed: true).
// Same key + a different path or body = 422 idempotency_key_reused.
const BASE = process.env.ATLAS_BASE ?? "https://automationatlas.io/labs/api/v1";
const KEY = process.env.ATLAS_OFFICE_KEY;
if (!KEY) throw new Error("run: source atlas-keys.env");
const headers = { Authorization: `Bearer ${KEY}` };

const list = await (await fetch(`${BASE}/office/sales-orders?limit=20`, { headers })).json();
const order = list.data.items.find((o) => o.status === "received");
if (!order) throw new Error("no received sales order left to accept");

// Derive the key from the action so a retry after a crash reuses it (max 64 characters).
const idempotencyKey = `accept-${order.id}`;

for (const attempt of [1, 2]) {
  const res = await fetch(`${BASE}/office/sales-orders/${order.id}/accept`, {
    method: "POST",
    headers: { ...headers, "Idempotency-Key": idempotencyKey },
  });
  const json = await res.json();
  console.log(attempt, res.status, "replayed:", res.headers.get("idempotency-replayed") === "true", json.data?.status ?? json.error);
}

"""First write with an Idempotency-Key.  pip install requests; then: source atlas-keys.env

Same key + same request = the original response again (Idempotency-Replayed: true).
Same key + a different path or body = 422 idempotency_key_reused.
"""
import os

import requests

BASE = os.environ.get("ATLAS_BASE", "https://automationatlas.io/labs/api/v1")
HEADERS = {"Authorization": f"Bearer {os.environ['ATLAS_OFFICE_KEY']}"}

orders = requests.get(f"{BASE}/office/sales-orders?limit=20", headers=HEADERS, timeout=30).json()
order = next((o for o in orders["data"]["items"] if o["status"] == "received"), None)
if order is None:
    raise SystemExit("no received sales order left to accept")

# Derive the key from the action so a retry after a crash reuses it (max 64 characters).
idempotency_key = f"accept-{order['id']}"

for attempt in (1, 2):
    res = requests.post(
        f"{BASE}/office/sales-orders/{order['id']}/accept",
        headers={**HEADERS, "Idempotency-Key": idempotency_key},
        timeout=30,
    )
    body = res.json()
    print(attempt, res.status_code, "replayed:", res.headers.get("Idempotency-Replayed") == "true",
          body.get("data", {}).get("status") or body.get("error"))

#!/usr/bin/env bash
# Page through a list. Lists are newest first; limit is 1..100 (default 50).
# Pass data.next_cursor back unchanged; null means the last page.
set -euo pipefail
BASE="${ATLAS_BASE:-https://automationatlas.io/labs/api/v1}"
: "${ATLAS_OFFICE_KEY:?run: source atlas-keys.env}"

cursor=""
while :; do
  url="$BASE/office/sales-orders?limit=100"
  [ -n "$cursor" ] && url="$url&cursor=$cursor"
  page=$(curl -sS "$url" -H "Authorization: Bearer $ATLAS_OFFICE_KEY")
  jq -r '.data.items[] | [.id, .status, .quantity] | @tsv' <<<"$page"
  cursor=$(jq -r '.data.next_cursor // empty' <<<"$page")
  [ -z "$cursor" ] && break
done

# Only rows changed since a time:      ?updated_since=2026-10-15T09:00:00Z
# CSV for a spreadsheet or Power Query: curl "$BASE/office/sales-orders.csv" -H "Authorization: Bearer $ATLAS_OFFICE_KEY"
# Cheap polling: send If-None-Match with the ETag header from the last response; a 304 means nothing changed.

// Page through a list (Node 20+).  Lists are newest first; limit is 1..100 (default 50).
// Pass data.next_cursor back unchanged; null means the last page.
const BASE = process.env.ATLAS_BASE ?? "https://automationatlas.io/labs/api/v1";
const headers = { Authorization: `Bearer ${process.env.ATLAS_OFFICE_KEY}` };

async function* listAll(path, params = {}) {
  let cursor = null;
  do {
    const query = new URLSearchParams({ limit: "100", ...params, ...(cursor ? { cursor } : {}) });
    const res = await fetch(`${BASE}${path}?${query}`, { headers });
    const json = await res.json();
    if (!res.ok) throw new Error(`${res.status} ${json.error.code}`);
    yield* json.data.items;
    cursor = json.data.next_cursor;
  } while (cursor);
}

for await (const order of listAll("/office/sales-orders")) {
  console.log(order.id, order.status, order.quantity);
}
// Only rows changed since a time: listAll(path, { updated_since: "2026-10-15T09:00:00Z" })
// CSV: GET /office/sales-orders.csv. Cheap polling: send If-None-Match with the last ETag; 304 means unchanged.

"""Page through a list.  pip install requests; then: source atlas-keys.env

Lists are newest first; limit is 1..100 (default 50).
Pass data.next_cursor back unchanged; null means the last page.
"""
import os

import requests

BASE = os.environ.get("ATLAS_BASE", "https://automationatlas.io/labs/api/v1")
HEADERS = {"Authorization": f"Bearer {os.environ['ATLAS_OFFICE_KEY']}"}


def list_all(path, **params):
    cursor = None
    while True:
        query = {"limit": 100, **params, **({"cursor": cursor} if cursor else {})}
        res = requests.get(f"{BASE}{path}", headers=HEADERS, params=query, timeout=30)
        body = res.json()
        if not res.ok:
            raise SystemExit(f"{res.status_code} {body['error']['code']}")
        yield from body["data"]["items"]
        cursor = body["data"]["next_cursor"]
        if not cursor:
            return


for order in list_all("/office/sales-orders"):
    print(order["id"], order["status"], order["quantity"])
# Only rows changed since a time: list_all(path, updated_since="2026-10-15T09:00:00Z")
# CSV: GET /office/sales-orders.csv. Cheap polling: send If-None-Match with the last ETag; 304 means unchanged.

#!/usr/bin/env bash
# Get a sandbox, waiting in the queue when Atlas Labs is full.
# POST /sandboxes answers 201 with your keys, or 202 with a queue ticket when every slot is taken.
# Poll the ticket until a poll answers 201: that body is the only time the keys appear, and a
# ready ticket must be claimed within 120 s or it is forfeited (410 ticket_forfeited).
# Needs: curl, jq.
set -euo pipefail
BASE="${ATLAS_BASE:-https://automationatlas.io/labs/api/v1}"
ORIGIN=$(printf '%s' "$BASE" | sed -E 's#^(https?://[^/]+).*#\1#') # `poll` is a path, not a URL
headers=$(mktemp) body=$(mktemp)
trap 'rm -f "$headers" "$body"' EXIT

# Run one request; sets $status, leaves the response in $body and its headers in $headers.
call() { status=$(curl -sS -D "$headers" -o "$body" -w '%{http_code}' "$@"); }
retry_after() { awk -F': *' 'tolower($1) == "retry-after" { gsub(/\r/, "", $2); print $2 }' "$headers"; }

for attempt in 1 2 3 4 5; do
  call -X POST "$BASE/sandboxes" -H "Content-Type: application/json" -d '{"preset":"starter"}'
  # 503 queue_full: the queue itself is full. Retry-After says when to try again (30 s).
  if [ "$status" = 503 ] && [ "$attempt" -lt 5 ]; then
    pause=$(retry_after); sleep "${pause:-30}"; continue
  fi
  break
done

if [ "$status" = 202 ]; then
  poll=$(jq -r .data.poll "$body")
  echo "queued at position $(jq -r .data.position "$body"), about $(jq -r .data.eta_s "$body") seconds"
  while :; do
    pause=$(retry_after); pause=${pause:-3}
    [ "$pause" -ge 3 ] 2>/dev/null || pause=3 # unauthenticated calls share 30 per minute per IP group
    sleep "$pause"
    call "$ORIGIN$poll"
    case "$status" in
      202) echo "position $(jq -r .data.position "$body")" ;;
      429 | 5??) ;; # keep the place, wait Retry-After
      *) break ;;    # 201 keys, 410 forfeited, 404 unknown or already claimed
    esac
  done
fi

if [ "$status" != 201 ]; then
  echo "HTTP $status: $(cat "$body")" >&2
  exit 1
fi

# Owner-only file. Do not commit it.
(umask 077
 printf 'export ATLAS_FACTORY_KEY=%s\nexport ATLAS_OFFICE_KEY=%s\n' \
   "$(jq -r .data.factory_key "$body")" "$(jq -r .data.office_key "$body")" > atlas-keys.env)
chmod 600 atlas-keys.env  # umask only applies to a new file
jq '{sandbox_id: .data.sandbox_id, name: .data.public_name, expires_at: .data.expires_at}' "$body"
echo "Keys saved to atlas-keys.env. Run: source atlas-keys.env"

// Get a sandbox, waiting in the queue when Atlas Labs is full (Node 20+, no dependencies).
// POST /sandboxes answers 201 with your keys, or 202 with a queue ticket when every slot is taken.
// Poll the ticket until a poll answers 201: that body is the only time the keys appear, and a
// ready ticket must be claimed within 120 s or it is forfeited (410 ticket_forfeited).
import { chmodSync, writeFileSync } from "node:fs";

const BASE = process.env.ATLAS_BASE ?? "https://automationatlas.io/labs/api/v1";
const ORIGIN = new URL(BASE).origin; // `poll` is a path such as /labs/api/v1/queue/tkt_..., not a URL
const POLL_FLOOR_MS = 3000; // unauthenticated calls share 30 per minute per IP group
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
const retryAfterMs = (res, fallbackMs) => {
  const seconds = Number(res.headers.get("retry-after"));
  return Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : fallbackMs;
};

async function create(body) {
  for (let attempt = 1; ; attempt += 1) {
    const res = await fetch(`${BASE}/sandboxes`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(body),
    });
    // 503 queue_full: the queue itself is full. Retry-After says when to try again (30 s).
    if (res.status === 503 && attempt < 5) {
      await sleep(retryAfterMs(res, 30_000));
      continue;
    }
    return res;
  }
}

let res = await create({ preset: "starter" });
let json = await res.json();

if (res.status === 202) {
  const { poll } = json.data;
  console.log("queued at position", json.data.position, "about", json.data.eta_s, "seconds");
  for (;;) {
    await sleep(Math.max(POLL_FLOOR_MS, retryAfterMs(res, 0)));
    res = await fetch(ORIGIN + poll);
    json = await res.json().catch(() => ({}));
    if (res.status === 202) {
      console.log("position", json.data.position);
      continue;
    }
    if (res.status === 429 || res.status >= 500) continue; // keep the place, wait Retry-After
    break; // 201 keys, 410 forfeited, 404 unknown or already claimed
  }
}
if (res.status !== 201) {
  const e = json.error ?? {};
  throw new Error(`HTTP ${res.status} ${e.code}: ${e.hint ?? e.message}`);
}
const sandbox = json.data;

// Owner-only file. Do not commit it.
writeFileSync(
  "atlas-keys.env",
  `export ATLAS_FACTORY_KEY=${sandbox.factory_key}\nexport ATLAS_OFFICE_KEY=${sandbox.office_key}\n`,
  { mode: 0o600 },
);
// `mode` only applies when the file is created; tighten one that already existed.
chmodSync("atlas-keys.env", 0o600);
console.log(sandbox.sandbox_id, sandbox.public_name, "expires", sandbox.expires_at);
console.log("Keys saved to atlas-keys.env. Run: source atlas-keys.env");

"""Get a sandbox, waiting in the queue when Atlas Labs is full.

POST /sandboxes answers 201 with your keys, or 202 with a queue ticket when every slot is taken.
Poll the ticket until a poll answers 201: that body is the only time the keys appear, and a
ready ticket must be claimed within 120 s or it is forfeited (410 ticket_forfeited).

Needs: pip install requests
"""
import os
import time
from urllib.parse import urlsplit

import requests

BASE = os.environ.get("ATLAS_BASE", "https://automationatlas.io/labs/api/v1")
parts = urlsplit(BASE)
ORIGIN = f"{parts.scheme}://{parts.netloc}"  # `poll` is a path such as /labs/api/v1/queue/tkt_..., not a URL
POLL_FLOOR_S = 3  # unauthenticated calls share 30 per minute per IP group


def retry_after(res, fallback):
    try:
        seconds = float(res.headers.get("Retry-After", ""))
        return seconds if seconds > 0 else fallback
    except ValueError:
        return fallback


def create(body):
    for attempt in range(1, 6):
        res = requests.post(f"{BASE}/sandboxes", json=body, timeout=30)
        # 503 queue_full: the queue itself is full. Retry-After says when to try again (30 s).
        if res.status_code == 503 and attempt < 5:
            time.sleep(retry_after(res, 30))
            continue
        return res
    return res


res = create({"preset": "starter"})

if res.status_code == 202:
    data = res.json()["data"]
    poll = data["poll"]
    print("queued at position", data["position"], "about", data["eta_s"], "seconds")
    while True:
        time.sleep(max(POLL_FLOOR_S, retry_after(res, 0)))
        res = requests.get(ORIGIN + poll, timeout=30)
        if res.status_code == 202:
            print("position", res.json()["data"]["position"])
            continue
        if res.status_code == 429 or res.status_code >= 500:
            continue  # keep the place, wait Retry-After
        break  # 201 keys, 410 forfeited, 404 unknown or already claimed

if res.status_code != 201:
    err = res.json().get("error", {})
    raise SystemExit(f"HTTP {res.status_code} {err.get('code')}: {err.get('hint') or err.get('message')}")
sandbox = res.json()["data"]

# Owner-only file. Do not commit it.
fd = os.open("atlas-keys.env", os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
with os.fdopen(fd, "w") as f:
    f.write(f"export ATLAS_FACTORY_KEY={sandbox['factory_key']}\n")
    f.write(f"export ATLAS_OFFICE_KEY={sandbox['office_key']}\n")
os.chmod("atlas-keys.env", 0o600)  # the mode above only applies to a new file

print(sandbox["sandbox_id"], sandbox["public_name"], "expires", sandbox["expires_at"])
print("Keys saved to atlas-keys.env. Run: source atlas-keys.env")

// Only needed when POST /sandboxes answers 428 pow_required (an operator switch, off by default).
// Find a nonce so SHA-256(challenge + nonce) has at least `difficulty` leading zero bits, then retry
// with the header  Atlas-PoW: <challenge>.<nonce>. Take difficulty from the response, never hard-code it.
import { createHash } from "node:crypto";

const BASE = process.env.ATLAS_BASE ?? "https://automationatlas.io/labs/api/v1";

function leadingZeroBits(buf) {
  let bits = 0;
  for (const byte of buf) {
    if (byte === 0) { bits += 8; continue; }
    for (let mask = 0x80; mask > 0; mask >>= 1) {
      if (byte & mask) return bits;
      bits += 1;
    }
  }
  return bits;
}

export function solve(challenge, difficulty) {
  for (let nonce = 0; ; nonce += 1) {
    const digest = createHash("sha256").update(challenge + nonce, "utf8").digest();
    if (leadingZeroBits(digest) >= difficulty) return String(nonce);
  }
}

export async function createSandboxWithPow(body = {}) {
  const post = (headers = {}) =>
    fetch(`${BASE}/sandboxes`, {
      method: "POST",
      headers: { "Content-Type": "application/json", ...headers },
      body: JSON.stringify(body),
    });
  let res = await post();
  if (res.status === 428) {
    const { challenge, difficulty } = (await res.json()).error.details;
    res = await post({ "Atlas-PoW": `${challenge}.${solve(challenge, difficulty)}` });
  }
  return res;
}

"""Only needed when POST /sandboxes answers 428 pow_required (an operator switch, off by default).

Find a nonce so SHA-256(challenge + nonce) has at least `difficulty` leading zero bits, then retry
with the header  Atlas-PoW: <challenge>.<nonce>. Take difficulty from the response, never hard-code it.
"""
import hashlib
import os

import requests

BASE = os.environ.get("ATLAS_BASE", "https://automationatlas.io/labs/api/v1")


def leading_zero_bits(data: bytes) -> int:
    bits = 0
    for byte in data:
        if byte == 0:
            bits += 8
            continue
        for shift in range(7, -1, -1):
            if byte & (1 << shift):
                return bits
            bits += 1
    return bits


def solve(challenge: str, difficulty: int) -> str:
    nonce = 0
    while True:
        digest = hashlib.sha256((challenge + str(nonce)).encode()).digest()
        if leading_zero_bits(digest) >= difficulty:
            return str(nonce)
        nonce += 1


def create_sandbox_with_pow(body=None):
    body = body or {}
    res = requests.post(f"{BASE}/sandboxes", json=body, timeout=30)
    if res.status_code == 428:
        details = res.json()["error"]["details"]
        nonce = solve(details["challenge"], details["difficulty"])
        res = requests.post(
            f"{BASE}/sandboxes",
            json=body,
            headers={"Atlas-PoW": f"{details['challenge']}.{nonce}"},
            timeout=30,
        )
    return res