Python SDK

import os

from atlas_sdk import Client

# Read the token from the environment - never hard-code it in source.
token = os.environ["ATLAS_TOKEN"]

client = Client(token=token)

import os

from atlas_sdk import Client

client = Client(token=os.environ["ATLAS_TOKEN"])

# List endpoints answer an { "items": [...], "nextCursor": ... } envelope.
page = client.atlas_get_tasks(query={"limit": 5})
for task in page["items"]:
    print(task["id"], task["title"])

from atlas_sdk import (
    ApiError,
    UnauthorizedError,
    ForbiddenError,
)

try:
    client.atlas_post_tasks(body={"title": ""})
except ForbiddenError as err:
    # 403: the token is missing a scope. The scopes are in the problem body.
    problem = err.body or {}
    print("need scopes:", problem.get("requiredScopes"))
except UnauthorizedError:
    # 401: token invalid or revoked - re-authenticate.
    raise
except ApiError as err:
    # 409 / 422 / 429 and anything else land here with .status set.
    problem = err.body or {}
    print(err.status, problem.get("title"), problem.get("requestId"))
    if err.status == 422:
        for field in problem.get("errors", []):
            print(field["path"], field["message"])
    raise

import random
import time

from atlas_sdk import ApiError

RETRYABLE = {429, 500, 502, 503, 504}

def with_retries(call, *, max_attempts=5):
    """Retry on 429 and 5xx with exponential backoff and jitter."""
    for attempt in range(1, max_attempts + 1):
        try:
            return call()
        except ApiError as err:
            if err.status not in RETRYABLE or attempt == max_attempts:
                raise
            problem = err.body or {}
            rate_limit = problem.get("rateLimit") or {}
            # The 429 body carries the authoritative retry delay, in seconds.
            delay = rate_limit.get("retryAfterSec")
            if delay is None:
                delay = min(2 ** (attempt - 1), 30) + random.random()
            time.sleep(delay)

page = with_retries(lambda: client.atlas_get_tasks(query={"limit": 50}))

import json
import os
import uuid
from urllib import request as urlrequest

from atlas_sdk import Client

class IdempotentClient(Client):
    """The generated client sends a fixed header set; this thin extension adds
    an Idempotency-Key to writes so a retried request replays (24h) instead of
    creating a duplicate."""

    def write(self, method, path, body, *, key):
        req = urlrequest.Request(
            f"{self._base_url}{path}",
            data=json.dumps(body).encode(),
            method=method.upper(),
            headers={
                "Authorization": f"Bearer {self._token}",
                "Content-Type": "application/json",
                "Accept": "application/json",
                "Idempotency-Key": key,
            },
        )
        with urlrequest.urlopen(req, timeout=self._timeout) as resp:
            raw = resp.read()
            return json.loads(raw) if raw else None

client = IdempotentClient(token=os.environ["ATLAS_TOKEN"])

# Generate one key per logical write and reuse it on every retry.
key = str(uuid.uuid4())
task = client.write("POST", "/tasks", {"projectId": "prj_123", "title": "Ship it"}, key=key)

from atlas_sdk import Client

client = Client(
    token=os.environ["ATLAS_TOKEN"],
    base_url="https://api.atlas.app/v1",  # override for staging or self-hosted
    timeout=30.0,                          # seconds, applied per request
)