Mobius

Sign inGet started
GuidesAPI Reference
Sign inGet started

API reference

API overview

This page is the short orientation for the HTTP layer. Most users won't spend time here directly: the mobius CLI and the SDKs (Go, TypeScript, Python) speak the same protocols and handle reconnects, retries, pagination, and signature verification for you. Reach for the raw API when you're embedding Mobius in a system that can't use a SDK or when you need a request shape that isn't in the helpers.

When you do need it, every endpoint, parameter, header, and schema is in the interactive reference, generated from openapi/openapi-public.yaml.

Surfaces

ProtocolSurface
HTTP/JSONEverything CRUD-shaped. The bulk of the API.
Server-Sent EventsRun event streams and agent session events.
WebSocketThe worker socket.

Base URL:

https://api.mobiusops.ai

Every endpoint is under /v1. There is no v0.

Authentication

Every request carries a bearer token:

Authorization: Bearer mbx_...

Tokens are API keys bound to a machine principal in one project. Permissions come from the principal's role assignments, not the key. The same bearer is used for the worker WebSocket upgrade.

Project scope

Most endpoints are project-scoped. The handle is part of the path:

/v1/projects/{project}/...

A handful of org-level endpoints (/v1/projects, /v1/audit-logs) are the exception, and they're explicit about it.

Conventions

IDs. Every resource has a typed prefix so a stray ID is identifiable at a glance: aut_ for automations, run_ for runs, job_ for jobs, iact_ for interactions, key_ for API keys, and so on.

Pagination. List endpoints use cursor pagination. The response includes next_cursor and has_more; pass next_cursor as cursor on the next request. Cursors are opaque (base64url).

Errors. Non-2xx responses include a JSON body with code, message, and details.

Timestamps. RFC 3339 UTC.

Idempotency. Run start, action invocation, and a few other "this should not run twice" endpoints accept an Idempotency-Key header. Worker job reports also dedupe internally.

Prefer the CLI and SDKs

A few examples of "use the helper, not the raw API":

  • Streaming a run. mobius automations stream-automation-run-events handles reconnects and replays from the last sequence number you saw.
  • Running a worker. The SDKs handle the WebSocket, lease tokens, heartbeats, backpressure, and generation streaming.
  • Verifying a webhook. The SDKs ship verifyWebhook helpers that do the HMAC, timestamp drift check, and replay dedupe in one call.
  • Pagination. The CLI follows cursors automatically when you ask for "all of it"; the SDKs return iterators.

If you find yourself implementing any of that by hand, look in the mobius repo first.

When you do hit HTTP directly

The interactive reference is the source of truth. Request shapes, response examples, header semantics, and error codes all live there. If a concept doc disagrees with the reference, trust the reference.