Mojo UpDocs
API reference

Cloud agents

Register a cloud run

POST/cloud-agents/v1/runs

A desktop workbench registers a task it sends to a provider's cloud agent. The organisation checks the project, the policy's cloudAgents.allowed and maxConcurrent, and that startedBy (when sent) is the token's person. When the run names a workspace and tools, the answer carries the MCP endpoint and a per-run credential (kept only as a hash, at most four hours) for the provider. A node is refused.

Authorization

deviceToken
AuthorizationBearer <token>

A device access token from the device-code flow (aioe_at_…). A DPoP-bound token is sent as Authorization: DPoP <token> with a fresh DPoP proof on every request.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/cloud-agents/v1/runs" \  -H "Content-Type: application/json" \  -d '{    "provider": "github-copilot",    "team": "string",    "member": "string",    "task": "string",    "tools": [      "string"    ],    "expiresAt": "string"  }'
{  "runId": "string",  "mcp": {    "url": "http://example.com",    "token": "stringstringstri",    "expiresAt": "string"  }}

Report what happened to a cloud run

POST/cloud-agents/v1/runs/{runId}/events

Only the device that registered the run. Events carry the provider's task id, page and pull request, and a sentence, never task text.

Authorization

deviceToken
AuthorizationBearer <token>

A device access token from the device-code flow (aioe_at_…). A DPoP-bound token is sent as Authorization: DPoP <token> with a fresh DPoP proof on every request.

In: header

Path Parameters

runId*string

The run, as registered.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

curl -X POST "https://example.com/cloud-agents/v1/runs/string/events" \  -H "Content-Type: application/json" \  -d '{    "events": [      {        "at": "string",        "kind": "started"      }    ]  }'
Empty

End a cloud run

POST/cloud-agents/v1/runs/{runId}/end

Only the device that registered the run. The run's credential stops working at once. Ending twice is harmless.

Authorization

deviceToken
AuthorizationBearer <token>

A device access token from the device-code flow (aioe_at_…). A DPoP-bound token is sent as Authorization: DPoP <token> with a fresh DPoP proof on every request.

In: header

Path Parameters

runId*string

The run, as registered.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

curl -X POST "https://example.com/cloud-agents/v1/runs/string/end" \  -H "Content-Type: application/json" \  -d '{}'
Empty

The workbench's tools, for the provider's agent

POST/cloud-agents/v1/runs/{runId}/mcp

MCP Streamable HTTP, JSON answers only, authenticated with the run's credential as a Bearer token. Each JSON-RPC message (a batch is several) is relayed to the workbench that started the run as the Control API method cloudMcp.call, signed for the run's person with the scope tasks:write. A notification is answered 202. A workbench that is not connected is a JSON-RPC error -32000. At most 1 MB a request and 300 requests a minute per run. GET and DELETE answer 405.

Authorization

cloudRunCredential
AuthorizationBearer <token>

A cloud run's credential (aioe_cr_…), handed to the provider when the run is registered. It works for that run only, until the run ends or expires.

In: header

Path Parameters

runId*string

The run, as registered.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

body*unknown

A JSON-RPC 2.0 message, or an array of them.

Response Body

application/json

curl -X POST "https://example.com/cloud-agents/v1/runs/string/mcp"
null