Skip to main content

Programmatic v1 admin API

Stable v2026.05 · semver-versioned · 12-month deprecation window on breaking changes

What this is​

The v1 admin API is the stable, semver-versioned programmatic surface for Sumeru Systems. It's what you build against when:

  • Pulling customer / order / attribution data into your data warehouse
  • Building custom integrations beyond Zapier's reach
  • Operating at agency scale across many shops
  • Embedding Sumeru data in your own admin UI
  • Triggering campaigns / journeys from external systems

This page is the narrative companion to the auto-generated reference at /developers/api/v1-admin/ — produced from the OpenAPI 3.1 spec by npm run gen:api. Run that command to populate the per-operation reference pages.

Authentication​

Bearer token in Authorization header — see Authentication & scopes.

GET /api/v1/customers HTTP/1.1
Host: api.sumeru.systems
Authorization: Bearer copt_live_aB3xY9zKqMnPwR2vT4uH7jL5sQ8eFc1g

Stability​

The v1 admin API is stable. Backwards-compatible additions ship continuously. Breaking changes will get a v2 endpoint with 12 months of v1 deprecation overlap.

Stability is per-endpoint; the reference page declares each:

X-Sumeru-Stability: stable

Endpoint catalog​

14 endpoints, organized by resource:

Decision intelligence​

EndpointMethodScope
/api/v1/decision-intelligence/runsGETanalytics:read
/api/v1/decision-intelligence/runs/{run_id}GETanalytics:read

SEO​

EndpointMethodScope
/api/v1/seo-intelligence/keywordsGETanalytics:read
/api/v1/seo-intelligence/keywords/{kw_id}GETanalytics:read

Customers​

EndpointMethodScope
/api/v1/customersGET (list)customers:read
/api/v1/customers/{customer_id}GETcustomers:read
/api/v1/customers/{customer_id}PATCHcustomers:write

Orders​

EndpointMethodScope
/api/v1/ordersGET (list)orders:read
/api/v1/orders/{order_id}GETorders:read

Attribution​

EndpointMethodScope
/api/v1/attributionGETattribution:read

Campaigns​

EndpointMethodScope
/api/v1/campaignsGET (list), POST (create)campaigns:read, campaigns:write
/api/v1/campaigns/{id}/launchPOSTcampaigns:write

Journeys​

EndpointMethodScope
/api/v1/journeysGET (list), POST (create)journeys:read, journeys:write
/api/v1/journeys/{id}/enrollmentsGET (list)journeys:read

Products​

EndpointMethodScope
/api/v1/productsGET (list), POST (create)products:read, products:write
/api/v1/products/{id}GET, PATCHproducts:read, products:write

Inventory​

EndpointMethodScope
/api/v1/inventoryGET, PATCH (bulk)products:read, products:write

Usage​

EndpointMethodScope
/api/v1/usageGET(any token)

Response shape​

Single resource:

{
  "data": {
    "id": "cus_abc123",
    "type": "customer",
    "attributes": {
      "email": "jane@example.com",
      "lifecycle_stage": "loyal",
      "total_spent": 487.20
    },
    "relationships": {
      "orders": { "links": { "related": "/api/v1/customers/cus_abc123/orders" } }
    }
  }
}

Lists:

{
  "data": [ { ... }, { ... } ],
  "pagination": {
    "next_cursor": "...",
    "has_next": true
  }
}

Pagination​

Cursor-based:

GET /api/v1/customers?limit=50
GET /api/v1/customers?limit=50&cursor=eyJpZCI6ImN1c19hYmMxMjMifQ==

limit max: 100. Cursors are opaque + version-stable.

Rate limits​

See Rate limits per tier. Headers:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 421
X-RateLimit-Reset: 1715346000

When limited, 429 with Retry-After:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

Idempotency​

POST + PATCH support Idempotency-Key:

POST /api/v1/campaigns HTTP/1.1
Authorization: Bearer copt_live_...
Idempotency-Key: my-campaign-2026-05-10-spring
Content-Type: application/json

{ "name": "Spring Sale", ... }

Same key + same body in 24h returns same response. Different body returns 409.

Error model​

Standard error envelope (see API overview):

{
  "error": {
    "code": "validation_failed",
    "message": "audience_id required for campaign creation",
    "details": { "field": "audience_id" },
    "request_id": "req_abc123"
  }
}

Worked examples​

Read recent customers​

curl -H "Authorization: Bearer copt_live_..." \
  "https://api.sumeru.systems/api/v1/customers?filter[lifecycle_stage]=loyal&sort=-last_order_at&limit=10"

Update a customer's tag​

curl -X PATCH \
  -H "Authorization: Bearer copt_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "data": { "attributes": { "tags": ["vip", "wholesale"] } } }' \
  "https://api.sumeru.systems/api/v1/customers/cus_abc123"

Launch a campaign​

curl -X POST \
  -H "Authorization: Bearer copt_live_..." \
  -H "Idempotency-Key: launch-spring-2026-05-10" \
  "https://api.sumeru.systems/api/v1/campaigns/cam_abc123/launch"

List a journey's enrollments​

curl -H "Authorization: Bearer copt_live_..." \
  "https://api.sumeru.systems/api/v1/journeys/jrn_abc/enrollments?filter[status]=active&limit=100"

Pull attribution for a date range​

curl -H "Authorization: Bearer copt_live_..." \
  "https://api.sumeru.systems/api/v1/attribution?filter[date_from]=2026-05-01&filter[date_to]=2026-05-09&include=touchpoints"

SDK examples​

Node.js​

import { SumeruES } from '@sumeru/sdk';

const sumeru = new SumeruES({ apiKey: process.env.ATLANTIS_API_KEY });

const customer = await sumeru.customers.get('cus_abc123');
console.log(customer.lifecycle_stage);

await sumeru.campaigns.launch('cam_abc123', {
  idempotencyKey: 'launch-spring-2026-05-10',
});

Python​

from sumeru_es import SumeruES

sumeru = SumeruES(api_key=os.environ['ATLANTIS_API_KEY'])

customer = sumeru.customers.get('cus_abc123')
print(customer.lifecycle_stage)

sumeru.campaigns.launch('cam_abc123',
    idempotency_key='launch-spring-2026-05-10')

Auto-generated reference​

The full per-operation reference (request schemas, response schemas, every parameter, every example) is auto-generated from the OpenAPI spec at /developers/api/v1-admin/.

See also​