Reference

Complete route index for the Axum API

Source-backed route inventory organized by domain, with the credential each domain accepts and the standard JSON error envelope.

Base URL

Every route on this page is written the way the API registers it, without a prefix. Join it to your base URL:

Deployment	Base URL	Example
Hosted	`https://api.useeventstack.com`	`https://api.useeventstack.com/events`
Local development	`http://localhost:3001`	`http://localhost:3001/events`

Every SDK takes the base URL as configuration, so you never concatenate it yourself.

Credentials

There is no single credential for the whole API. Which one a route accepts follows from what it does, and sending the wrong one is a 403, not a401. See Authentication for the full rules.

Credential	Routes	Transport
API key	Event ingestion and the reads a service needs: events, traces, contracts, projections, replay, failed events	`Authorization: Bearer useeventstack_…`. No CSRF token.
User session	Management: organizations, members, API keys, contracts, workflows, custom action upload and review, integrations, billing, and the AI preview	`HttpOnly` session cookie. Unsafe methods also require the CSRF cookie echoed in `x-useeventstack-csrf`.
Provider signature	`/integrations/:adapter_id/webhook`, `/stripe/webhook`	The provider's own signature. No session, no API key.
None	`/health`, `/plans`, `/public/:slug/changelog`, `/contact/submit`	Public.

An API key cannot become a user session, and it is refused on session-only routes. Everything else authenticated: anonymous requests get 401.

Headers and errors

Project-scoped routes require the project header, and the project is verified to belong to the organization before any query runs:

Authorization: Bearer <api-key>          # or the session cookie
Content-Type: application/json
x-useeventstack-organization: <organization-uuid>
x-useeventstack-project: <project-uuid>
x-useeventstack-environment: production | sandbox

For an API key, the organization, project and environment come from the key itself. Sending headers that disagree with it is a 400(project_mismatch, environment_mismatch) rather than a silent override.

Every error uses the same envelope:

{
  "error": {
    "code": "bad_request",
    "message": "...",
    "correlation_id": "uuid",
    "details": {}
  }
}

Quote the correlation_id in a support request: it is in the server logs next to the underlying cause, which the message itself never leaks.

Events

Method	Route	Notes
`POST`	`/events`	Emit event. Supports `x-useeventstack-idempotency-key` header.
`GET`	`/events`	Up to 100 results. Filters: `event_type`, `correlation_id`, `environment`
`GET`	`/events/:id`	Single event detail
`GET`	`/events/:id/trace`	Full causation trace chain
`GET`	`/event-graph`	Workflow event graph. Params: `root`, `environment`

Workflows

Method	Route
`GET`, `POST`	`/organizations/:org_id/workflows`
`GET`, `PUT`, `DELETE`	`/organizations/:org_id/workflows/:id`
`POST`	`/organizations/:org_id/workflows/:id/enable`
`POST`	`/organizations/:org_id/workflows/:id/disable`
`GET`	`/workflows/query`
`GET`	`/intelligence`

Custom actions

Method	Route	Notes
`GET`, `POST`	`/organizations/:org_id/custom-actions`	POST is multipart (name, file)
`GET`, `DELETE`	`/organizations/:org_id/custom-actions/:id`
`POST`	`/organizations/:org_id/custom-actions/:id/simulate`	`{"payload": ...}`
`POST`	`/organizations/:org_id/custom-actions/:id/review`	Admin only. `status: "approved" \| "rejected"`
`GET`, `POST`	`/organizations/:org_id/custom-actions/:id/secrets`	POST: `{key, value}`. GET: keys only

Marketplace

Publish contracts, approved actions and workflows as an immutable version, and install one into a project. See the Marketplace guide.

Method	Route	Notes
`GET`, `POST`	`/organizations/:org_id/marketplace/listings`	POST: `{slug, name, summary, description, visibility}`
`GET`	`/organizations/:org_id/marketplace/listings/:listing_id`	Listing plus its versions
`POST`	`/organizations/:org_id/marketplace/listings/:listing_id/versions`	Admin only. Immutable once published
`POST`	`/organizations/:org_id/marketplace/listings/:listing_id/versions/:version_id/install`	Actions land `pending`, workflows `disabled`
`GET`	`/organizations/:org_id/marketplace/installations`	Scoped to the active project
`DELETE`	`/organizations/:org_id/marketplace/installations/:installation_id`	Admin only. Retains event contracts

Projections and replay

Method	Route	Notes
`GET`	`/projections`	Query projection state
`POST`	`/projections/rebuild`	Reset and replay all projections
`POST`	`/replay`	`event_id` required, `skip_external_side_effects` optional
`POST`	`/replay/bulk`	`event_ids` or `event_type`/`since`. Limit: 1–1000
`GET`	`/dead-letter-events`	List quarantined events
`GET`	`/failed-events`	List failed events
`POST`	`/platform/dead-letter-events/clear`	Reprocess DLQ

Authentication

Method	Route
`POST`	`/auth/signup`, `/auth/login`, `/auth/logout`
`POST`	`/auth/forgot-password`, `/auth/reset-password`, `/auth/verify-email`
`POST`	`/auth/change-password`, `/auth/resend-verification`
`GET`	`/auth/sessions`, `/auth/mfa/status`, `/me`
`POST`	`/auth/mfa/setup`, `/auth/mfa/enable`, `/auth/mfa/verify`, `/auth/mfa/disable`

Organizations

Method	Route
`GET`, `POST`	`/organizations`
`GET`, `PUT`	`/organizations/:org_id`
`GET`	`/organizations/:org_id/members`
`GET`, `POST`	`/organizations/:org_id/api-keys`
`DELETE`	`/organizations/:org_id/api-keys/:key_id`
`GET`, `POST`	`/organizations/:org_id/event-contracts`
`GET`, `POST`	`/organizations/:org_id/projects`
`GET`, `POST`	`/organizations/:org_id/invitations`
`GET`	`/organizations/:org_id/audit-logs`

Integrations

Method	Route
`GET`, `POST`	`/organizations/:org_id/integrations`
`POST`	`/integrations/:adapter_id/webhook`
`POST`	`/integrations/:adapter_id/test`
`GET`	`/integrations/health`
`POST`	`/organizations/:org_id/schemas/sync`
`POST`	`/stripe/webhook`

Billing and platform

Method	Route	Notes
`GET`	`/plans`	Available plans
`GET`	`/organizations/:org_id/billing`	Current billing status
`GET`	`/organizations/:org_id/usage`	Usage metrics
`POST`	`/organizations/:org_id/billing/checkout`	Stripe checkout session
`POST`	`/organizations/:org_id/billing/portal`	Stripe billing portal
`GET`	`/health`	System health (public)
`GET`	`/runtime/metrics`	Runtime statistics

Platform admin routes (/platform/*) require platform-admin access and are not general SDK substitutes.

Operations AI (preview)

Experimental and off by default

These routes exist but the assistant is a work in progress and is disabled unless the deployment enables it. See Operations AI before building against them.

Method	Route	Notes
`GET`	`/ai/status`	Whether the assistant is available. Never invokes a model.
`POST`	`/ai/chat`	`503 ai_assistant_not_configured` when disabled
`GET`	`/ai/conversations`	Conversations for this user, organization and project
`GET`, `DELETE`	`/ai/conversations/:id`	Read or delete one conversation

User session only — an API key is refused with 403. The project header is mandatory, and every tool is read-only.