Develop

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

Use a loop action step when the call belongs to a durable process. Use direct invocation to test credentials or call an action outside a loop.

Inspect and invoke actions

The catalog describes actions available to the current project:

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

Invoke one action with:

POST /v1/projects/{project}/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.

Catalog entries include definition_scope. Resolution precedence is project custom, organization custom, then provider/built-in. An organization definition still signs the current project and actor into signed_context_v1 and records usage against that project.

Manage organization actions and signing keys

Organization Owners and Admins can manage this lifecycle in the app under Organization > Actions. Use the API directly for automation or provisioning:

Organization Owner/Admin callers manage shared HTTP definitions with:

GET    /v1/organization/actions
POST   /v1/organization/actions
GET    /v1/organization/actions/{action_id}
PATCH  /v1/organization/actions/{action_id}
DELETE /v1/organization/actions/{action_id}
POST   /v1/organization/actions/{action_id}/secret/rotate
POST   /v1/organization/actions/{action_id}/secret/versions/{secret_version}/activate
POST   /v1/organization/actions/{action_id}/secret/versions/{secret_version}/revoke

Create returns version 1's base64 signing secret once. Rotation returns a new pending version's secret once but keeps signing with the current active version. Install the pending key in the receiver, then activate it. Activation signs new deliveries with the new version and leaves the old version in retiring state for 24 hours by default; overlap_seconds may shorten that window but cannot exceed 24 hours. Organization action endpoints must be public HTTPS URLs; Mobius blocks private, loopback, link-local, and redirect destinations when delivering signed requests.

Read responses return secret_ref, lifecycle metadata, and active_signing_version when one exists, never previous key material. Select verification keys from X-Mobius-Secret-Ref and X-Mobius-Secret-Version. Do not revoke the active version until another version is active, unless the action has first been disabled. Revocation also requires removing the compromised key from the receiver; Mobius cannot erase a copied HMAC key outside its control.

If you revoke the active version while disabled, rotate and activate a replacement before enabling the action again. Deleting an organization action removes it from future project catalogs; it does not cancel work that already froze that action ID. Disable the action or revoke its signing version to stop such work at invocation time.

Return context from a custom HTTP action

A signed project-owned 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. A loop action step also ignores context because it has no active agent turn.

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.