API

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 the repetitive parts for you.

Use the raw API when you're embedding Mobius in a system that can't use an SDK. Also use it when you need a request shape that is not in the helpers yet. This is the common path when Mobius is the agentic backend for a product. For internal business operations, start with the app and the mobius CLI unless a service needs to call Mobius directly.

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

Start with the narrative API pages when you need operational context:

• Agent invocation shows how to call POST /agents/invoke, choose inline or separate streaming, and retry safely.
• Sessions and turns covers transcript pagination, streaming, nudges, compaction, and recovery.
• Agent definitions covers sending an agent's behavior with the request or resolving it from your own backend.
• Actions documents direct invocation and the custom HTTP action response contract.
• Interactions, access control, and webhooks cover human waits, permissions, and outbound event delivery.
• Artifacts, tables, and environments cover the data and workspace APIs.
• Blueprints explains repeatable project setup.
• Secrets covers versioned secret values and rotation.
• Recover a failed run covers POST /runs/{run_id}/resume and POST /runs/{run_id}/retry.
• Event catalog documents source events.
• Agent messaging explains the product model behind API-based conversations.

Surfaces

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_...

Most machine-to-machine requests use a project API key. Project keys are bound to an API client in one project, and permissions come from the API client's role assignments, not the key. The same project bearer is used for the worker WebSocket upgrade.

Organization-level API keys use the same mbx_... prefix but are not pinned to one project. They authenticate as the organization's system principal with the role chosen at creation time.

Use org-level keys only for cross-project administration. Workers and project-pinned model endpoints should use a project key.

CLI credentials use the mbc_... prefix and authenticate as the logged-in human user. The CLI and SDKs choose the right credential shape for most calls.

Project scope

Most endpoints live under a project. The handle is part of the path:

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

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

Agent messaging

Call POST /v1/projects/{project}/agents/invoke for most embedded chat surfaces. Mobius resolves or creates a session, appends the input message, starts a turn, and returns either a stream or a cursor for the session stream.

Use the lower-level session endpoints when you need more control:

POST /v1/projects/{project}/sessions
POST /v1/projects/{project}/sessions/{session_id}/turns
GET /v1/projects/{project}/sessions/{session_id}/stream

Use the lower-level session and turn APIs when your client owns session creation or transcript pagination. See Agent invocation for the request shape, streaming modes, idempotency, and reconnect rules, or Sessions and turns for direct session control.

Conventions

IDs. Every resource has a typed prefix so a stray ID is identifiable at a glance. For example, loops use loop_, runs use run_, jobs use job_, and API keys use key_.

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 optional details. Request-body validation errors can include field-level detail:

{
  "error": {
    "code": "bad_request",
    "message": "invalid request body",
    "details": {
      "fields": [
        {
          "field": "actions.selector_type",
          "message": "expected string, got number",
          "expected": "string",
          "actual": "number"
        }
      ]
    }
  }
}

Treat details.fields[].field as a dotted request-body path and show message next to that field when you can. Some operational failures also use details for machine-readable context, such as idempotency conflicts or rate limits.

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":

• Recovering a run. mobius runs resume and mobius runs retry assemble the right recovery request and print the updated run.
• 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.