Atlas Events API

The Atlas Events API ingests product, workflow, audit, and system events from your applications, attaches actor and tenant context, and routes them to downstream workflows. Use it when you need a single, auditable pipeline for events that drive automations, analytics snapshots, compliance trails, or partner integrations.

Events are accepted synchronously, durably queued, and delivered to configured workflows and webhook subscribers with at-least-once semantics. Each event carries a deterministic event_id and supports caller-supplied idempotency keys, so retries from clients, proxies, or background jobs are safe.

Send your first event in three steps.

1. 1

   Create an event stream

   A stream groups related events and defines retention and routing.

   bash

   Copy

   curl https://api.atlasevents.dev/v1/event-streams \
     -H "Authorization: Bearer $ATLAS_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "orders-prod",
       "description": "Production order lifecycle events",
       "retention_days": 30
     }'

2. 2

   Send an event

   Publish to the stream with an idempotency key so retries are safe.

   bash

   Copy

   curl https://api.atlasevents.dev/v1/events \
     -H "Authorization: Bearer $ATLAS_API_KEY" \
     -H "Idempotency-Key: 6f1a3b9c-0d29-4d6b-9c0e-1f4b7a2e88aa" \
     -H "Content-Type: application/json" \
     -d '{
       "stream": "orders-prod",
       "type": "order.fulfilled",
       "occurred_at": "2026-05-18T14:22:11Z",
       "data": { "order_id": "ord_8K2N1Q7", "total_cents": 4299 }
     }'

3. 3

   Check delivery status

   Inspect lifecycle state and per-subscriber delivery attempts.

   bash

   Copy

   curl https://api.atlasevents.dev/v1/events/evt_01HX9YQK2T7V3M4ZB6F5N0WJ1A \
     -H "Authorization: Bearer $ATLAS_API_KEY"

Authenticate every request with a bearer token in the Authorization header. Tokens are scoped to a single workspace and environment (live or test) and can be restricted to specific streams.

Authorization: Bearer atlas_live_sk_9f4c2c1e6b8a4d2bb7e6c0a8d3f1e5c2

Create a named stream to group related events. Streams define retention and the default set of workflow and webhook routes. A workspace can operate up to 100 streams; contact platform support for higher limits.

Request body

curl https://api.atlasevents.dev/v1/event-streams \
  -H "Authorization: Bearer $ATLAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "audit-prod",
    "description": "Production audit log stream",
    "retention_days": 90,
    "default_routes": ["wf_compliance_archive"]
  }'

{
  "id": "stm_01HX9Z0F8C5G3R8K2V1NQ7M4WP",
  "object": "event_stream",
  "name": "audit-prod",
  "description": "Production audit log stream",
  "retention_days": 90,
  "default_routes": ["wf_compliance_archive"],
  "created_at": "2026-05-18T14:21:00Z",
  "workspace_id": "ws_4F9KQ2C7Z1"
}

Publish an event to a stream. Atlas validates the payload, assigns an event_id, and durably enqueues it for routing. Requests return as soon as the event is accepted; delivery happens asynchronously.

Request body

POST /v1/events
Authorization: Bearer atlas_live_sk_***
Idempotency-Key: 6f1a3b9c-0d29-4d6b-9c0e-1f4b7a2e88aa
Content-Type: application/json

{
  "stream": "orders-prod",
  "type": "order.fulfilled",
  "occurred_at": "2026-05-18T14:22:11Z",
  "data": {
    "order_id": "ord_8K2N1Q7",
    "currency": "USD",
    "total_cents": 4299,
    "line_items": [
      { "sku": "BK-1042", "qty": 1, "unit_cents": 4299 }
    ]
  },
  "actor": {
    "type": "user",
    "id": "usr_7T3Q9HBN2P",
    "tenant_id": "tnt_acme_eu",
    "ip": "203.0.113.42",
    "user_agent": "AcmeCheckout/3.4 (iOS 18.2)"
  },
  "metadata": {
    "region": "eu-west-1",
    "channel": "web",
    "experiment": "checkout_v7"
  }
}

{
  "id": "evt_01HX9YQK2T7V3M4ZB6F5N0WJ1A",
  "object": "event",
  "stream": "orders-prod",
  "type": "order.fulfilled",
  "status": "accepted",
  "received_at": "2026-05-18T14:22:11.482Z",
  "occurred_at": "2026-05-18T14:22:11Z",
  "idempotency_key": "6f1a3b9c-0d29-4d6b-9c0e-1f4b7a2e88aa",
  "routes": [
    { "workflow_id": "wf_billing_sync", "status": "queued" },
    { "workflow_id": "wf_search_index", "status": "queued" }
  ]
}

Return the current lifecycle state of an event and per-route delivery attempts. Use this to power in-product status indicators or to troubleshoot stuck events without scraping logs.

Path parameter

Lifecycle states

• acceptedValidated and queued. Not yet routed.
• processingBeing delivered to one or more routes.
• deliveredAll routes acknowledged successfully.
• retriedAt least one route failed and is scheduled for retry.
• failedAll retries exhausted. No further delivery attempts.

{
  "id": "evt_01HX9YQK2T7V3M4ZB6F5N0WJ1A",
  "object": "event",
  "stream": "orders-prod",
  "type": "order.fulfilled",
  "status": "retried",
  "received_at": "2026-05-18T14:22:11.482Z",
  "occurred_at": "2026-05-18T14:22:11Z",
  "attempts": [
    {
      "workflow_id": "wf_billing_sync",
      "status": "delivered",
      "attempt": 1,
      "completed_at": "2026-05-18T14:22:12.910Z"
    },
    {
      "workflow_id": "wf_search_index",
      "status": "retry_scheduled",
      "attempt": 2,
      "next_attempt_at": "2026-05-18T14:24:42.000Z",
      "last_error": {
        "code": "upstream_timeout",
        "message": "Search indexer did not respond within 5s"
      }
    }
  ]
}

Subscribe to delivery outcomes to drive async workflows in your own systems. Atlas signs every webhook with HMAC-SHA256 and retries failed deliveries with exponential backoff.

Event types

• event.delivered

  All routes acknowledged successfully.

• event.failed

  Delivery exhausted retries on at least one route.

• event.retry_scheduled

  A failed attempt has been queued for retry.

POST https://hooks.acme.example/atlas
X-Atlas-Signature: t=1747579332,v1=4a9e3b1c8d2f...
Content-Type: application/json

{
  "id": "whd_01HX9ZB44X1A9KP6T2Q0F3R5XM",
  "type": "event.delivered",
  "created_at": "2026-05-18T14:22:13.014Z",
  "data": {
    "event_id": "evt_01HX9YQK2T7V3M4ZB6F5N0WJ1A",
    "stream": "orders-prod",
    "workflow_id": "wf_billing_sync",
    "attempt": 1,
    "latency_ms": 1428
  }
}

Retry behavior

Atlas retries non-2xx responses up to 8 times over 24 hours with exponential backoff and jitter (30s, 1m, 5m, 15m, 1h, 3h, 6h, 12h). Endpoints returning 410 Gone are disabled until reactivated in the dashboard.

Atlas returns conventional HTTP status codes and a structured error body. The code field is stable and safe to switch on; the message field is human-readable and may change.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Request quota exceeded for workspace ws_4F9KQ2C7Z1.",
    "request_id": "req_01HX9ZD2M1Y0K8X6V3N7P5Q2W4",
    "details": { "retry_after_ms": 1200 }
  }
}

Default platform limits are sized for production workloads. Higher tiers are available for enterprise workspaces.

When throttled, Atlas returns 429 with Retry-After (seconds) and X-RateLimit-Remaining headers. Use exponential backoff starting at the suggested delay and add full jitter to avoid thundering-herd retries from clustered workers.

List endpoints use forward-only cursor pagination. Pass limit (1–100, default 25) and the next_cursor returned by the previous page. Cursors are opaque and stable for 24 hours.

curl "https://api.atlasevents.dev/v1/events?stream=orders-prod&limit=50&cursor=evt_01HX9YQK2T7V3M4ZB6F5N0WJ1A" \
  -H "Authorization: Bearer $ATLAS_API_KEY"

{
  "object": "list",
  "data": [
    { "id": "evt_01HX9YR8...", "type": "order.fulfilled", "status": "delivered" },
    { "id": "evt_01HX9YS3...", "type": "order.refunded",  "status": "delivered" }
  ],
  "has_more": true,
  "next_cursor": "evt_01HX9YS3K4P2QV8M1R7Z6N0WJ1B"
}

• Use idempotency keys for every write

  Generate a UUID per logical event in your producer, not per retry. This makes Atlas safe behind any HTTP client, queue worker, or proxy.

• Always include actor context

  Send actor.type, id, and tenant_id. Downstream audit, support, and abuse-detection workflows are dramatically more useful when the originator is known.

• Keep secrets out of metadata

  Metadata is indexed and visible in dashboards, exports, and replay tooling. Treat it as logged-forever data: no tokens, no PII you would not log.

• Alert on failed and retried events

  Subscribe to event.failed and event.retry_scheduled in your observability stack. Failures often signal upstream incidents before they reach users.

• Use webhooks for anything that can wait > 100 ms

  Push side effects (search indexing, billing sync, notifications) into workflows triggered by webhooks. Keep the producing request path lean.