API reference

Builder tier unlocks a real HTTP API so you can wire Stratam into your own code without going through chat. Same data model as the dashboard — everything you do via the UI you can also do here.

Auth

Every request needs a session cookie OR (Builder+) a personal API key.

Session-cookie path: log in via /login, then Set-Cookie: stratam_session=<token>. Same auth model as the dashboard — cookie is HttpOnly + Secure + SameSite=Strict.

API-key path (Phase 18.1 deferred — coming soon): create one from /settings → API keys, pass as Authorization: Bearer skk_<token> on every request.

Conventions

  • JSON in, JSON out.
  • Errors: {ok: false, error: "human-readable message"} with appropriate 4xx/5xx status.
  • Success: {ok: true, ...payload}.
  • UUIDs are RFC4122 — validated at the route layer; bad UUIDs return 400 before the DB sees them.
  • Timestamps: ISO-8601 UTC strings.

Vault

GET /api/vault/list

Query params: scope=personal|org, org_id=<uuid>, q=<search>, tag=<tag>, limit=N, offset=N

Returns paginated vault entries.

POST /api/vault/remember

Body: {content, tags?}

Save a vault entry. Returns {ok, entry_id}.

POST /api/vault/update

Body: {entry_id, content?, tags?, org_id?}

GET /api/vault/export.md, /api/vault/export.json

Bulk download with Content-Disposition: attachment.

Monitors

GET /api/monitors

List the user's monitors.

POST /api/monitors/create

Body: {label, instruction, schedule_kind, schedule_spec, notify_channel?, notify_target?}

POST /api/monitors/update, POST /api/monitors/pause, POST /api/monitors/resume, POST /api/monitors/delete

All take {monitor_id, ...optional patch fields}.

POST /api/monitors/run-now

Body: {monitor_id}

Synchronous fire. Blocks until the LLM call finishes. Returns {ok, run_id, reply_preview, latency_ms}.

GET /api/monitors/runs?monitor_id=&status=&limit=

Run history. Each row carries status, cost, latency, the reply, the error if any.

GET /api/monitors/cron-preview?spec=&count=

Validate a cron expression + see the next N fire times.

Conversations

GET /api/conversations

List threads with filters: channel=, q=, include_archived=1, only_pinned=1, since=, limit=, offset=.

GET /api/conversations/search?q=

Postgres FTS across all message bodies. Returns ranked hits with snippets.

GET /api/conversations/thread/<uuid>?limit=N

Thread metadata + last N messages.

POST /api/conversations/pin, /archive, /star, /bulk-mark-read

Notifications

GET /api/notifications

In-app inbox. Same data the bell badge counts.

POST /api/notifications/mark-read, /mark-all-read, /dismiss

POST /api/notifications/prefs

Set email digest frequency + mute hours.

Webhooks

Inbound (issue your own URLs)

  • POST /api/webhooks/inbound/create — {name, action, action_target?, expected_token?, rate_limit_pm?}
  • GET /api/webhooks/inbound — list with full URLs
  • POST /api/webhooks/inbound/{toggle,delete} — {id, enabled} or {id}

External systems POST to /w/in/<slug> to fire your chosen action: drop a notification, save the payload to your vault, fire a monitor, or inject as a conversation message.

Outbound (subscribe to events)

  • POST /api/webhooks/outbound/create — {name, target_url, events[], secret?} — secret returns ONCE
  • GET /api/webhooks/outbound — list (secret never returned again)
  • POST /api/webhooks/outbound/{events,toggle,delete} — patch / disable / delete
  • GET /api/webhooks/deliveries?outbound_id=&limit= — delivery audit log

Supported events: monitor.fired, monitor.failed, vault.entry, conversation.start, notification.new.

Signature: X-Stratam-Signature: sha256=<hmac> (when secret set) — verify on your side via hmac.compare_digest.

Analytics

GET /api/analytics/summary?days=

Headline KPI tiles.

GET /api/analytics/{actions,channels,monitors,projection}?days=

Various breakdowns.

GET /api/analytics/tokens?days=

Builder/Admin only — daily token spend curve.

GET /api/analytics/export.csv?days=

Raw CSV — one row per assistant message.

Rate limits

There's no per-key rate limit yet (deferred — Phase 32). Your monthly action cap caps the LLM call rate via tier:

  • Sidekick: 100 actions/month
  • Operator: based on $15 compute included
  • Builder: based on $50 compute included

When you hit the cap, every endpoint that would consume an action returns the canned cap-exceeded message instead. Settings → upgrade to bump the cap.

← All docs Found a bug in this page?