REST API documentation

Atlas exposes a hand-curated, hardened public REST surface under /v1/. Auth, rate limits, idempotency, pagination, webhooks - everything you need to integrate, plus one-click downloads of the spec, a Postman collection, and the matching environment.

Mint API token

Live fromhttps://api-atlas.wrxstack.com/v1/openapi.json

Download the spec, collection, and environment

All three artefacts are generated server-side from the same source of truth - the hand-written OpenAPI 3.1 doc. Nothing is stale.

OpenAPI 3.1 spec

atlas-public-api.openapi.json

Machine-readable spec with x-required-scopes, x-ratelimit-class, and x-rate-limits extensions.

Postman collection

atlas-public-api.postman_collection.json

Postman v2.1, grouped by tag. Bearer auth + Idempotency-Key + sample bodies wired to {{baseUrl}}/{{apiKey}}/{{idempotencyKey}}.

Postman environment

atlas-public-api.postman_environment.json

Companion environment template. Paste your PAT into apiKey and you're sending real requests.

Interactive Redoc viewer

https://api-atlas.wrxstack.com/v1/docs

Three-pane reference renderer with searchable endpoint nav, schemas, and try-it examples. Always reflects the live spec.

Mint a token + send your first request

The whole API is one Authorization header away. Mint a Personal Access Token, then curl any /v1/ endpoint with it.

Open Settings API access and click New token. Pick the narrowest scope set (start with tasks:read).
Copy the token. It starts with atlas_pat_ and is shown once.
Replace the placeholder in the snippet below and run it.

bash

curl -H "Authorization: Bearer atlas_pat_REPLACE_ME" \
  https://api-atlas.wrxstack.com/v1/tasks?limit=50

Authentication

Every /v1 request carries a bearer token. The same header accepts a Personal Access Token (atlas_pat_...) or a session JWT - PATs are the recommended path for server-to-server use because they're scope-bounded and revocable independently of the user's session.

http

Authorization: Bearer atlas_pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Error format

Every 4xx and 5xx response uses RFC 9457 problem+json. Always check Content-Type - successful responses are application/json, errors are application/problem+json.

http

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

{
  "type": "https://api.atlas-todo.com/errors/insufficient-scope",
  "title": "insufficient_scope",
  "status": 403,
  "detail": "PAT is missing the 'tasks:write' scope.",
  "missingScope": "tasks:write",
  "requestId": "req_01HW3T..."
}

Status	When you see it
400	Body failed Zod validation. `errors[]` lists the failing fields.
401	Missing or expired token. Mint or rotate the PAT.
403 (insufficient_scope)	PAT is valid but missing a required scope.
403 (pat-ip-blocked)	PAT has an IP allowlist and the request came from outside it.
404	Resource not found OR the calling tenant cannot see it.
409	Optimistic-concurrency conflict - re-read and retry with the new version.
422	Request was understood but business rules rejected it (e.g. cyclic dependency).
429	Rate-limited. `Retry-After` and `X-RateLimit-Reset` headers included.
5xx	Atlas is degraded. Safe to retry with exponential backoff (300ms 800ms 2s).

Rate limits

Every route is classified as read, write, or ai. Each class has its own bucket per tenant; the limits below are defaults - your tenant may have a higher ceiling configured.

Class	Default ceiling	Applies to
`read`	300/m	GET requests on /v1/* (excluding /v1/ai/*)
`write`	60/m	POST/PATCH/PUT/DELETE on /v1/*
`ai`	20/m	Any /v1/ai/* call (read or write)

429 response shape

When you hit a bucket Atlas returns 429 with three headers: Retry-After (seconds), X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (Unix seconds when the bucket resets). Honour Retry-After - it's authoritative.

Idempotency

Every POST route accepts an Idempotency-Key header. Replaying the same key (same tenant) within 24h returns the original 2xx response - verbatim, including the resource id. Crucial for safe retries on flaky networks.

bash

curl -X POST https://api-atlas.wrxstack.com/v1/tasks \
  -H "Authorization: Bearer atlas_pat_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "projectId": "prj_...",
    "title": "Review Q3 forecast",
    "priority": "HIGH",
    "dueOn": "2026-05-01T17:00:00Z"
  }'

Use a UUID per logical operation - uuidgen on the shell, randomUUID() in Node, or any stable hash you can re-derive on retry. Don't reuse a key for different requests - Atlas matches on the key, not the body.

Pagination

List endpoints return a cursor: pass nextCursor back as ?cursor= to get the following page. Cursors are opaque - never parse or modify them.

bash

# First page
curl -H "Authorization: Bearer atlas_pat_..." \
  "https://api-atlas.wrxstack.com/v1/tasks?limit=50"
#  { "items": [...], "nextCursor": "eyJpZCI6Li4ufQ==" }

# Next page
curl -H "Authorization: Bearer atlas_pat_..." \
  "https://api-atlas.wrxstack.com/v1/tasks?limit=50&cursor=eyJpZCI6Li4ufQ=="

Webhooks

Subscribe to delivery URLs via /v1/webhooks. Atlas signs every payload with HMAC-SHA256 and retries failed deliveries with an exponential ladder (1s 5s 25s 2m 10m 1h, capped at 24h total).

http

POST https://your.app/atlas-webhook
Content-Type: application/json
X-Atlas-Event: task.created
X-Atlas-Signature: sha256=...
X-Atlas-Delivery: dlv_01HW3T...

typescript

# Verify the X-Atlas-Signature header (Node.js)
import crypto from 'node:crypto';

function verify(rawBody: string, headerValue: string, secret: string): boolean {
  const sig = headerValue.replace(/^sha256=/, '');
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(sig, 'hex'), Buffer.from(expected, 'hex'));
}

Replay any failed delivery from Settings Webhooks or via POST /v1/webhooks/{id}/deliveries/{deliveryId}/replay.

SDKs and clients

The official TypeScript client mirrors the REST surface 1:1. For AI agents, the MCP server wraps the same endpoints in a model-friendly tool catalogue.

typescript

import { createAtlasClient } from '@atlas/client';

const atlas = createAtlasClient({
  baseUrl: 'https://api-atlas.wrxstack.com',
  // PATs are passed verbatim - no refresh logic needed.
  getAccessToken: () => process.env.ATLAS_API_KEY ?? null,
});

const { items } = await atlas.tasks.list({ limit: 50 });
const created = await atlas.tasks.create({
  projectId: 'prj_...',
  title: 'Review Q3 forecast',
  priority: 'HIGH',
});

Building an AI agent integration? See the MCP setup guide for Claude Desktop, Cursor, and Cline configuration.

Drive Atlas from Postman in 90 seconds

The downloadable collection comes pre-wired with bearer auth, idempotency keys, sample bodies, and 2xx response examples. The companion environment file holds your token.

Download the collection and the environment.
In Postman: Import drop both files. Pick the new environment from the top-right environment selector.
Click the eye icon on the environment, paste your PAT into apiKey, and save.
Open any request and hit Send. The pre-request script auto-fillsidempotencyKey when blank, so creates are safe to retry out of the box.

Security model

Defence in depth across every public route.

SHA-256 hashed PATs. Plaintext tokens are never stored - only a one-way hash. Revocation is immediate.
Scope gates per route. See the table above - and the live spec embeds x-required-scopes on every operation.
Per-tenant rate limits. Defaults published above; per-tenant overrides via the PUBLIC_API_RATE_OVERRIDES env JSON.
Optional IP allowlist. Mint a PAT with allowedIps; calls from outside fail with 403 pat-ip-blocked.
Audit log. Every PAT-driven mutation is recorded in Activity with the actor, route, and resource id.

FAQ

Can I use a session cookie / JWT instead of a PAT?: Yes - the bearer header accepts either. JWT-authenticated calls bypass the scope gate (the session is implicitly all-scopes). PATs are still recommended for server-to-server because they're tenant-scoped, scope-narrowed, and revocable independently of any user session.
Why does my POST occasionally return the same id twice?: You sent the same Idempotency-Key twice within 24h. That's by design - the second call returns the original 2xx response so you don't double-create. Use a fresh UUID for each logical create.
How do I update a task without overwriting concurrent edits?: Pass the task's current version field as If-Match: <version>. If the task changed in the meantime you'll get a 409; re-read, merge, and retry.
Is there a sandbox / staging environment?: Self-host Atlas with a separate Postgres for sandbox. The same OpenAPI spec applies; just point your PAT-minting client and baseUrl at the sandbox URL.
How do I get notified when the spec changes?: Watch the release notes - every public-API change is documented there. The spec also bumps info.version on breaking changes.

HTTP/1.1 403 Forbidden Content-Type: application/problem+json { "type": "https://api.atlas-todo.com/errors/insufficient-scope", "title": "insufficient_scope", "status": 403, "detail": "PAT is missing the 'tasks:write' scope.", "missingScope": "tasks:write", "requestId": "req_01HW3T..." }

Status

When you see it

400

Body failed Zod validation. `errors[]` lists the failing fields.

401

Missing or expired token. Mint or rotate the PAT.

403 (insufficient_scope)

PAT is valid but missing a required scope.

403 (pat-ip-blocked)

PAT has an IP allowlist and the request came from outside it.

404

Resource not found OR the calling tenant cannot see it.

409

Optimistic-concurrency conflict - re-read and retry with the new version.

422

Request was understood but business rules rejected it (e.g. cyclic dependency).

429

Rate-limited. `Retry-After` and `X-RateLimit-Reset` headers included.

5xx

Atlas is degraded. Safe to retry with exponential backoff (300ms 800ms 2s).

Class

Default ceiling

Applies to

read

300/m

GET requests on /v1/* (excluding /v1/ai/*)

write

60/m

POST/PATCH/PUT/DELETE on /v1/*

ai

20/m

Any /v1/ai/* call (read or write)

curl -X POST https://api-atlas.wrxstack.com/v1/tasks \ -H "Authorization: Bearer atlas_pat_REPLACE_ME" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "projectId": "prj_...", "title": "Review Q3 forecast", "priority": "HIGH", "dueOn": "2026-05-01T17:00:00Z" }'

# First page curl -H "Authorization: Bearer atlas_pat_..." \ "https://api-atlas.wrxstack.com/v1/tasks?limit=50" # { "items": [...], "nextCursor": "eyJpZCI6Li4ufQ==" } # Next page curl -H "Authorization: Bearer atlas_pat_..." \ "https://api-atlas.wrxstack.com/v1/tasks?limit=50&cursor=eyJpZCI6Li4ufQ=="

# Verify the X-Atlas-Signature header (Node.js) import crypto from 'node:crypto'; function verify(rawBody: string, headerValue: string, secret: string): boolean { const sig = headerValue.replace(/^sha256=/, ''); const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex'); return crypto.timingSafeEqual(Buffer.from(sig, 'hex'), Buffer.from(expected, 'hex')); }

import { createAtlasClient } from '@atlas/client'; const atlas = createAtlasClient({ baseUrl: 'https://api-atlas.wrxstack.com', // PATs are passed verbatim - no refresh logic needed. getAccessToken: () => process.env.ATLAS_API_KEY ?? null, }); const { items } = await atlas.tasks.list({ limit: 50 }); const created = await atlas.tasks.create({ projectId: 'prj_...', title: 'Review Q3 forecast', priority: 'HIGH', });