API & Integrations

Everything programmatic lives behind one kind of credential: an API key from Settings → API keys (/settings/api), scoped to exactly what it may do. Keys are server-to-server credentials — never ship one in browser code, a mobile app, or anything a customer can inspect.

Authentication

Every request carries the key in a header — either works:

text

Authorization: Bearer theaicmo_...
X-Api-Key: theaicmo_...

Keys are shown once at creation. Each key carries scopes (ticked when you create it) and per-minute/per-day rate limits; 429 responses include a Retry-After header.

Send a service message

Scope: send:transactional. Receipts, password resets, notifications — delivered on your transactional identity and never blocked by marketing opt-outs (a receipt is not a promotion).

bash

curl -X POST https://theaicmo.com/api/send \
  -H "X-Api-Key: theaicmo_..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "to": "customer@example.com",
    "subject": "Your order shipped",
    "html": "<p>It is on the way.</p>",
    "idempotency_key": "order-1042-shipped"
  }'

Suppression, blacklist and consent gates still apply — the API refuses with a clear code rather than quietly skipping.

Trigger a journey

Scope: journeys:trigger. Start a published journey for one person from your own systems — "order shipped", "deposit made", "ticket resolved".

bash

curl -X POST https://theaicmo.com/api/journeys/trigger \
  -H "X-Api-Key: theaicmo_..." \
  -H "Content-Type: application/json" \
  -d '{
    "journey_id": "<the journey id>",
    "email": "customer@example.com",
    "event": { "order_number": "1042", "amount": 89.90 },
    "idempotency_key": "order-1042-shipped"
  }'

Event properties (up to 20) reach your message copy as personalization. Every entry door still applies: suppression, contact status, and the journey's own re-entry rules. The journey's id and a ready-made curl live on the journey's trigger settings in the builder.

Loyalty: balance, rewards, redemption

Scope: loyalty. Render points and tier inside your product, list the rewards shop, and redeem — full walkthrough in the Loyalty Program guide.

bash

curl -H "X-Api-Key: theaicmo_..." \
  "https://theaicmo.com/api/loyalty/balance?identity=customer@example.com"

Redemptions are idempotent (same idempotency_key returns the original receipt) and can never overdraw a balance.

Run a tool

Scope: tools:execute. Any generation tool, programmatically — same tools, same credits as in the product.

bash

curl -X POST https://theaicmo.com/api/execute-tool-api \
  -H "Authorization: Bearer theaicmo_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tool_id": "social-post-generator",
    "parameters": {
      "productName": "Aurora Coffee",
      "platform": "linkedin",
      "variations": 2
    }
  }'

The response carries the generated output plus credits_used and credits_remaining. Tool ids and per-tool credit prices are listed on each tool's page in the product.

Errors

Status	Meaning
401	Missing or invalid key
402	Insufficient credits (tools) or insufficient points (loyalty)
403	Key lacks the required scope
404	Resource not found or not yours
409	Idempotency conflict — same key, different payload
429	Rate limited — honor `Retry-After`

Error bodies are JSON with a stable error code and a human message.