mobius

Get started free
Get started free

API

Provision projects and agents

Use external_ref plus if_exists: "adopt" when your product provisions one Mobius project per tenant and one or more agents inside it. The same request can run during signup, retry after a timeout, or run again during reconciliation without creating duplicate resources.

Create or adopt a project

Choose a durable tenant or workspace identifier from your system. Do not use a display name that a customer can change.

POST /v1/projects
Authorization: Bearer <api-key>
Content-Type: application/json
 
{
  "name": "Acme workspace",
  "handle": "acme-workspace",
  "external_ref": "workspace_789",
  "if_exists": "adopt",
  "access_mode": "restricted"
}

Mobius returns 201 Created for a new project or 200 OK for the active project that already owns workspace_789. On adoption, the existing project is returned unchanged; fields such as name, description, access_mode, and tags are not updated.

Store the returned handle or id. If you supply a handle on a later adopt request, it must match the adopted project. An archived project keeps its external identity and returns 409 project_archived; adoption never silently unarchives it or creates a replacement.

Create or adopt an agent

Use a stable identity inside the project. This lets your backend keep the same agent even if its display name or definition changes.

POST /v1/projects/acme-workspace/agents
Authorization: Bearer <api-key>
Content-Type: application/json
 
{
  "name": "Scout",
  "description": "Acme's support agent",
  "external_ref": "primary-support-agent",
  "if_exists": "adopt"
}

Mobius returns 201 Created for a new agent or 200 OK for the live agent that already owns that external reference. Adoption does not update mutable agent fields. Update the returned agent explicitly when its name, model, instructions, toolkits, or other configuration should change.

A deleted agent still owns its external_ref and returns a conflict. This prevents a later resource from silently assuming the deleted agent's durable identity, sessions, or audit meaning.

Identity rules

  • external_ref is unique within its scope: the organization for projects and the project for agents.
  • Treat it as assign-once. You may add it to a resource that does not have one, or repeat the same value, but you cannot change an existing value.
  • if_exists: "adopt" requires external_ref. Without it, the request returns 400 because Mobius has no durable identity to match.
  • The default if_exists: "error" keeps the ordinary create contract and returns 409 for duplicate names, handles, or external references.
  • An agent with external_ref: "primary-support-agent" is also addressable by an organization definition resolver as agent/primary-support-agent.

Reconcile after ambiguous failures

If your client times out before receiving the response, repeat the same adopt request. A 200 or 201 response is success. Treat conflicts as state that needs operator attention rather than generating a new external reference.

The response is the source of truth. Do not assume the request's mutable fields were applied when the status is 200.

Next