Actions

The actions API covers direct invocation, custom action management, and the response contract for signed HTTP actions.

Agents call actions as tools during a session. Use direct invocation to test credentials or to call an action from your own code outside a session.

Manage custom actions

Custom actions use the same private or team ownership boundary as other build resources in the current organization. Register, update, or delete one with:

POST   /v1/actions
PATCH  /v1/actions/{action_name}
DELETE /v1/actions/{action_name}
POST   /v1/actions/{action_name}/secret/rotate

Creating an HTTP action returns its signing secret once. Store it immediately. Worker-backed actions omit the endpoint URL and become ready when a connected worker advertises the registered action name.

The action catalog is the read surface for both custom and platform actions, so a newly registered custom action appears in GET /v1/catalog/actions.

Inspect and invoke actions

The catalog describes actions available to the current organization:

GET /v1/catalog/actions
GET /v1/catalog/actions/{action_name}

Invoke one action with:

POST /v1/actions/{action_name}/invoke

Supply a stable Idempotency-Key header when the action can cause an external side effect. Mobius can deduplicate the request, but it cannot roll back a message, charge, or provider update that already succeeded.

Mobius does not insert a human confirmation when an assistant invokes a built-in, MCP, custom HTTP, or worker action. Assistant tool dispatch still checks the action grant and freezes and revalidates the selected connected account immediately before a provider call. A denial never falls through to a different account.

Calling the invoke endpoint directly is an authenticated API operation by your software, so its roles, action scope, and idempotency key are the controls. If a workflow needs human review, create an interaction or enforce the review in your action before the external change. A standalone interaction does not become an authorization token for a later action call.

Catalog entries include definition_scope. Custom definitions take precedence over provider and built-in definitions with the same name.

Return context from a custom HTTP action

A signed custom HTTP action can return a tool result and named application state in one response. Opt in with this exact media type:

HTTP/1.1 200 OK
Content-Type: application/vnd.mobius.action+json
 
{
  "output": {
    "ok": true,
    "shortlisted": "Northstar"
  },
  "context": [
    {
      "name": "naming-board",
      "content": "Current naming board:\nChosen: none\nShortlisted: Northstar"
    }
  ]
}

output becomes the ordinary tool result. Each changed context item is recorded after that result as caller-owned application context. Returning the same byte-identical value again is safe; Mobius skips it while it remains in the active model window.

The SDK names are:

Context limits

• At most 8 context items and 16 KiB of context content per response.
• Names must match ^[a-z][a-z0-9-]*$ and be at most 64 characters.
• Content must be non-empty UTF-8 and at most 8 KiB per item.
• One turn records at most 64 KiB of action-returned context in total.

Mobius drops an invalid context item and reports it in action-result metadata while preserving valid items and output. A non-object body using the Mobius media type fails the action call. An HTTP status of 400 or higher fails before the body is interpreted.

Only signed customer-defined HTTP actions can return context. Integration, MCP, built-in, and worker actions cannot use this channel. The context channel also requires an active agent turn; a direct action job has no conversation to receive it.

Any other response content type keeps the ordinary action contract. For application/json, the entire body is the tool result, even when it contains keys named output or context.

Next

• Choose actions in the actions concept.
• Attach state at turn start with agent invocation context.
• Inspect every endpoint in the interactive API reference.