Develop

The API is how your software talks to Mobius directly. Your product can put its own interface in front of an agent, an internal service can send it work, or a setup process can create the same resources repeatedly.

Use an SDK when one is available for your language. Use the raw HTTP API when you need direct control or are integrating from a different stack. Both use the same resources, authentication, errors, and idempotency rules described here.

Choose the right entry point

Start from the job your software needs to do:

Send a message to an agent. Start with agent invocation. It handles conversation lookup, creation, and streaming through one operation.

React to something outside Mobius. Have your own service call agent invocation when the outside event happens. Your code decides which agent, which conversation, and which idempotency key, so a redelivered event does not produce a second turn.

Repeat the same request on a schedule. See routines. Creating one through the API still requires a human owner, an existing session, and explicit spending ceilings.

Create the same setup repeatedly. See blueprints and provisioning.

Operate from a terminal or pipeline. Prefer the mobius CLI when it already exposes the task. It handles authentication, formatting, and pagination for you.

What a request looks like

Here's the whole idea. Ask Mobius for your agents, using curl, a program for making web requests that's already on your Mac:

curl https://api.mobiusops.com/v1/agents \
  -H "Authorization: Bearer $MOBIUS_API_KEY"

{
  "items": [
    {
      "id": "agt_9q2m7x5v3p8n4r6t",
      "name": "Scout",
      "status": "active",
      "created_at": "2026-06-15T14:00:00Z",
      "updated_at": "2026-06-15T14:00:00Z"
    }
  ],
  "has_more": false
}

A web address, a key that proves who you are, and some structured text back. That's the shape of every request on this page. Everything else is detail.

Every address starts with https://api.mobiusops.com/v1. There is no v0, and the v1 won't change under you.

Three ways in

Most of the API works like the request above: you ask, we answer, done. Two things don't, because they're still happening while you're listening.

The streams use Server-Sent Events, which is a long-lived HTTP response the browser and most languages already know how to read. Nothing exotic.

Agent conversations mostly go through one address:

POST /v1/agents/invoke

Send a message, get a reply or a stream of one. We find or create the conversation for you. Reach for the lower-level session endpoints only when your own software wants to own the conversation:

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

Start with invoke. See agent invocation for the request shape and sessions and turns for direct control.

Your key

Every request carries a key in a header called Authorization:

Authorization: Bearer mbx_...

"Bearer" is just the word the header expects before the key. It doesn't mean anything you need to care about.

Keys starting with mbx_ are API keys, which you create in the app under Settings > Access. One key reaches one organization, and that is the whole boundary: a key made in Ridgeline Dental's organization cannot touch Acme's.

A key carries no permissions of its own. It signs in as an API client and inherits that client's roles. Change the roles, change what the key can do, without reissuing anything.

Keys starting with mbc_ are different: those belong to the mobius CLI and act as the person who logged in. You won't create those by hand.

Warning: Anyone holding the key can do everything the key can do. Put it in your secret store, not in a script, a config file you commit, or an email.

What comes back

IDs tell you what they are. Every ID starts with a short prefix, so a stray one in a log is identifiable at a glance: agent_ for agents, ses_ for sessions, turn_ for turns, rtn_ for routines, job_ for worker jobs.

Long lists arrive in pages. A list response includes has_more and next_cursor. If has_more is true, send next_cursor back as cursor on your next request and you'll get the following page. Don't try to read next_cursor; it's deliberately meaningless.

Times are UTC, written like 2026-06-15T14:00:00Z.

Errors explain themselves. Anything that isn't a success comes back with a code you can branch on and a message you can show a human:

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

When details.fields is present, each field is a path into what you sent. If you're building a form, show the message next to that field. Some operational failures use details too, for things like rate limits and duplicate-request conflicts.

Sending the same thing twice

Networks drop responses. Your request went through, you never heard back, and now you don't know whether to retry.

For anything that shouldn't happen twice, send an Idempotency-Key header with a value you make up. If we've already handled a request with that key, we return the original result instead of doing the work again. Invoking an agent and invoking an action both accept it.

Pick a key that describes the thing, not the attempt: ticket-4182-triage, not a random string you generate on each retry. A random one defeats the entire point.

Use the CLI or an SDK when you can

The mobius CLI and the Go, TypeScript, and Python libraries speak this same API and handle the tedious parts. Some things you should not build by hand:

• Streaming a turn. The libraries reassemble the event stream, handle reconnects, and give you the reply as it arrives.
• Running a worker. The libraries handle the connection, the leases, the heartbeats, and the reconnects. This one is genuinely hard to get right.
• Checking a signed callback is really from us. The libraries ship a verification helper that does the signature check, the clock-drift check, and the replay check in one call.
• Paging through a long list. The CLI follows the cursors for you; the libraries hand you something you can loop over.

If you catch yourself implementing any of those, look in the mobius repo first.

The rest of these pages

Putting an agent in your own software

• Agent invocation: start a conversation, stream the reply, retry safely.
• Sessions and turns: read a transcript, stream it, steer a reply mid-flight, keep a long conversation from growing forever.
• Agent configuration: configure the standing behavior once and optionally select a model when creating a session.
• Structured output: get an answer back in a shape your code can use.
• Embedded OAuth return: let your users connect their own Google or Slack account from inside your product.

Setting up clients in bulk

• Provisioning: create agents with stable identities your own system can reconcile against.
• Blueprints: stamp out the same setup repeatedly.
• Access control: who and what can do which things.

Reaching in and out

• Actions: run one specific thing directly, and the reply format your own HTTP actions have to return.
• Interactions: the approvals and questions an agent waits on, and the signed callback that tells you the answer.
• Event catalog: every event Mobius records, and what's inside it.

Data

• Artifacts: the files an agent produced.
• Tables: shared rows your agents read and write.

Scheduled work

• Routines: recurring agent work, its schedule, its spending ceilings, and its occurrence history.

The full list

Every address, every field, every error code lives in the interactive reference. It's generated from the API itself, so it can't drift. If a page here disagrees with it, believe the reference and tell us.