Atlas API reference

Atlas exposes a plain, versioned HTTP+JSON API. Everything below /api/v1/ is namespaced and stable within a major version; the only unauthenticated route is GET /health.

Alpha

Atlas is in alpha. The surface below is accurate for the current release, but endpoints and fields may still change before 1.0. Pin a version for anything you depend on.

Base URL and versioning

All API paths are prefixed with /api/v1. In the examples below Atlas is running locally on its default port 8400 — substitute your own host and the TLS URL your reverse proxy serves.

export ATLAS=https://atlas.example.com

Authentication

Atlas has three auth surfaces that coexist. Every /api/v1/* route requires one of them (only /health is anonymous):

Surface	Who	How
OIDC session	Interactive humans	Log in through your own OpenID Connect provider — see SSO setup.
Forward-auth	Interactive humans	A reverse proxy injects trusted identity headers (used when OIDC is unset).
Machine token	Automation / agents	`Authorization: Bearer atlas_sk_…` — see Automation with machine tokens.

How access is decided:

An interactive admin may call every route.
An interactive read-only user may call any read (GET) route, but no writes.
A machine token may call exactly the routes its granted scopes cover, and can never reach a delete or a token-management route (those stay admin-interactive-only).

Each endpoint below lists the scope a machine token needs. Interactive humans follow the admin / read-only split above regardless of the scope column.

Errors

Errors return a JSON body and a conventional status code:

Status	Meaning
`401`	No/invalid credentials, or a revoked/expired token.
`403`	Authenticated, but not permitted (missing scope, or a non-admin attempting a write).
`404`	No such customer / resource.
`422`	Malformed body or an unknown enum/scope value.
`429`	Rate limit exceeded (machine tokens are per-token rate-limited).

Health

`GET /health`

Anonymous liveness probe. Returns 200 when the service and its database are reachable. Safe to point a load balancer or an uptime monitor at.

curl $ATLAS/health

Customers

The core noun. A customer is identified by a URL-safe slug.

Method	Path	Scope (token)	Purpose
`GET`	`/api/v1/customers`	`customers:read`	List customers.
`GET`	`/api/v1/customers/{slug}`	`customers:read`	One customer with detail.
`POST`	`/api/v1/customers`	`customers:write`	Create a customer.
`PATCH`	`/api/v1/customers/{slug}`	`customers:write`	Update fields.
`DELETE`	`/api/v1/customers/{slug}`	admin only	Delete. Never reachable by a token.
`GET`	`/api/v1/customers/{slug}/deployments`	`customers:read`	That customer's deployments.
`GET`	`/api/v1/customers/{slug}/subscriptions`	`customers:read`	That customer's subscriptions.
`POST`	`/api/v1/customers/{slug}/contacts`	`contacts:write`	Add a contact.
`GET`	`/api/v1/customers/{slug}/touchpoints`	`customers:read`	Interaction log.
`POST`	`/api/v1/customers/{slug}/touchpoints`	`contacts:write`	Log an interaction.
`GET`	`/api/v1/customers/{slug}/agreements`	`customers:read`	Agreements on file.
`GET`	`/api/v1/customers/{slug}/usage`	`customers:read`	Usage records.
`POST`	`/api/v1/customers/{slug}/usage`	`subscriptions:write`	Record usage.

Create a customer:

curl -X POST $ATLAS/api/v1/customers \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "acme-co",
    "name": "Acme Co.",
    "primary_email": "ops@acme.example",
    "status": "trial"
  }'

Customer fields: slug (required, ^[a-z0-9][a-z0-9-]*$), name (required), primary_email, status (lead · trial · paying · churned · internal, default lead), notes, and optional sales-motion fields (pipeline_stage, next_action, next_action_date, source). A create returns 201 with the full customer including its generated id and timestamps.

Deployments

A deployment is one customer running one product at a version — the "who's running what, where, last seen when" row.

Method	Path	Scope (token)	Purpose
`GET`	`/api/v1/deployments`	`deployments:read`	List deployments (filter with `?product=`).
`POST`	`/api/v1/deployments`	`deployments:write`	Register a deployment.
`PATCH`	`/api/v1/deployments/{id}`	`deployments:write`	Update version / last-seen.

curl -X POST $ATLAS/api/v1/deployments \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_slug": "acme-co",
    "product": "atlas",
    "version": "1.4.2",
    "channel": "stable",
    "endpoint_url": "https://atlas.acme.example",
    "instance_id": "acme-prod-1"
  }'

Deployment fields: customer_slug (required), product (required), version (required), channel (canary · beta · stable), endpoint_url, instance_id, first_deployed_at.

The product catalog is a fixed enum in alpha

In the current release product must be one of Atlas's built-in product identifiers. Making the catalog operator-configurable so you can track your own product names is on the roadmap; until then, contact support if you need the catalog adjusted for your deployment.

Subscriptions

The recurring-revenue row for a customer × product.

Method	Path	Scope (token)	Purpose
`GET`	`/api/v1/subscriptions`	`subscriptions:read`	List subscriptions.
`POST`	`/api/v1/subscriptions`	`subscriptions:write`	Create a subscription.

Subscription fields: customer_slug (required), product (required), status (trialing · active · past_due · cancelled, default trialing), mrr_cents (non-negative integer; 0 = complimentary), renewal_date, and optional billing references (stripe_customer_id, stripe_subscription_id). mrr_cents feeds the revenue rollups, so it is validated non-negative.

Contacts

People at a customer, added under the customer resource (POST /api/v1/customers/{slug}/contacts, scope contacts:write).

Contact fields: name (required), email (required), role (technical · billing · admin · other, default other), last_contacted_at.

Reporting

Read-only rollups for dashboards and status checks.

Method	Path	Scope (token)	Purpose
`GET`	`/api/v1/summary`	`customers:read`	Top-line counts + revenue rollup.
`GET`	`/api/v1/summary/trend`	`customers:read`	Trend over time.
`GET`	`/api/v1/summary/rollout`	`deployments:read`	Version-rollout spread across deployments.
`GET`	`/api/v1/status`	`customers:read`	Health-style status view.
`GET`	`/api/v1/events`	`customers:read`	The audit event stream (who changed what).
`GET`	`/api/v1/signals`	`customers:read`	Derived signals (at-risk, stale, etc.).

Leads

Method	Path	Scope (token)	Purpose
`POST`	`/api/v1/leads`	`customers:write`	Capture a lead. Atlas derives + dedupes the slug and defaults `status=lead`.

curl -X POST $ATLAS/api/v1/leads \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Jane Doe", "email": "jane@prospect.example", "source": "website" }'

Token administration

Machine tokens are created, listed, and revoked under /api/v1/admin/tokens. These routes are interactive-admin-only — no machine token can mint or revoke another token, by design. See Automation with machine tokens for the full lifecycle.

Getting help

Email support@seglamater.com for API help, managed hosting, or consulting.