Agent Runs

A completion answers once. A run keeps going — calling tools, reading what came back, and deciding again — until the job is done or the step budget is spent.

The same API key works here. Authentication is unchanged; what changes is the shape of the interaction, and one property worth understanding before you write any code against it.

A run does not belong to its request

POST /runs streams as a convenience, because it is the low-latency path and the common case. But the run loop writes every part to storage as it goes and does not stop when the socket does. Closing the connection loses the view, not the work.

That is not a detail — it is the design, and it is what makes the next section a documented boundary rather than a failure mode.

Streams reconnect at ~290 seconds

On https://mume.ai a streaming response is proxied, and the proxy closes the connection at 290 seconds. A run can be far longer than that. When the stream ends before the run does, reattach:

Bash

# the last chunk index you received
curl "https://mume.ai/api/v1/runs/$RUN_ID/stream?after=418" \
  -H "Authorization: Bearer $MUME_API_KEY"

after replays everything past that index and then continues live. A client that handles this correctly sees an hour-long run as one continuous stream across several connections.

If you would rather hold a single socket for the whole run, call the runs service directly at https://gateway-sandbox-94714072483.us-central1.run.app/agentRuns/v1 — same paths, same key, no proxy in front and so no cap. The reconnecting client is still the more robust of the two, because a network is not a promise.

Finding an agent

Every run names an agentId, so the first thing an integration needs is a list of them. Two endpoints, and they cover different sets.

Bash

curl https://mume.ai/api/v1/agents/public

JSON

{
  "object": "list",
  "data": [
    {
      "id": "blog-to-carousel",
      "name": "Blog to Carousel",
      "tagline": "One post becomes a set of social cards that actually match each other.",
      "icon": "image",
      "tools": ["readFile", "writeFile", "generateImage", "viewImage", "bash"],
      "publishedAt": "2026-08-13T23:21:18.937Z",
      "version": 3,
      "featured": true
    }
  ]
}

That is the community directory — agents people published, not ours. The platform's own agents are not in it; their ids are the slugs on the agents page (csv-analyst, invoice-extractor, podcast-producer, and so on). Making one list of both is open work, and until it lands the site is the reliable index of the first-party set.

Either kind of id resolves through the same lookup, which is how you check one before spending a run on it:

Bash

curl https://mume.ai/api/v1/agents/csv-analyst \
  -H "Authorization: Bearer $MUME_API_KEY"

JSON

{
  "object": "agent",
  "id": "csv-analyst",
  "version": 1,
  "tools": ["readFile", "writeFile", "editFile", "glob", "grep", "bash", "…"],
  "trust": "platform",
  "policies": { "stepBudget": 100 },
  "promptChars": 4800
}

promptChars rather than the prompt: no API returns an agent's system prompt, including to its own author. What you get is enough to know what the agent may do — its tools, its trust tier and its step budget — which is what decides whether a run of it is safe to start on someone's behalf.

Start a run

Bash

curl https://mume.ai/api/v1/runs \
  -H "Authorization: Bearer $MUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "csv-analyst",
    "sessionId": "sess_01H…",
    "messages": [
      { "role": "user", "parts": [{ "type": "text", "text": "What is wrong with sales.csv?" }] }
    ]
  }'

The response is the stream — server-sent events carrying an AI SDK UI-message stream, byte-identical to what the chat surface consumes.

Body

Field	Notes
`messages`	Required. UI-message parts, not chat-completion strings.
`agentId`	Which agent to run. Resolved against the published registry — see Agents for the ids you can use. Omit it for a plain tool-using run with no agent prompt.
`sessionId`	Groups runs that share a workspace. Reuse it and the next run sees the files the last one wrote.
`model`	Overrides the agent's own choice, unless the definition pins it.
`tools`, `mcpServers`	Extra tools for this run, including your own MCP servers. See MCP Servers.
`approvalMode`	`manual` parks writes for a decision instead of performing them. See below.
`stepBudget`	How many model turns the run may take. Clamped by the agent's own limit and by your account tier, so the effective number can be lower than you asked for.
`reasoningEffort`	`none` to `high`, on models that support it.
`webSearch`	Grounds the run in live results. Works on any model — see Web Search.

Read a run without streaming it

Bash

curl https://mume.ai/api/v1/runs/$RUN_ID \
  -H "Authorization: Bearer $MUME_API_KEY"

Status, step count and outcome, with no stream attached. This is the endpoint to poll from a worker that started a run and does not want to hold a connection at all.

GET /api/v1/runs?sessionId=… lists the runs in a session. The sessionId parameter is required — a bare GET /runs answers 400 rather than every run you have ever started.

Answer a tool the run parked

Two things stop a run mid-flight and wait for you. Both are answered with a POST, and the stream resumes on its own once you do.

Approvals

Under approvalMode: "manual" a write is described rather than done, and the run waits:

Bash

curl https://mume.ai/api/v1/runs/$RUN_ID/approve \
  -H "Authorization: Bearer $MUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "toolCallId": "call_01H…", "approved": true }'

Refusing is not an error. approved: false hands the model a refusal it can reason about, and the run carries on without the write.

Client-side tools

A tool your own application implements is parked for you to execute and return:

Bash

curl https://mume.ai/api/v1/runs/$RUN_ID/tool-output \
  -H "Authorization: Bearer $MUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "toolCallId": "call_01H…", "output": { "rows": 412 } }'

Stop a run

Bash

curl -X POST https://mume.ai/api/v1/runs/$RUN_ID/cancel \
  -H "Authorization: Bearer $MUME_API_KEY"

A request to stop, not a kill. The run finishes the tool call it is inside and then ends, so a file being written is not left half-written.

What a run costs

Every model turn inside a run is billed like any other completion, so a run that takes twenty steps costs roughly twenty completions. There is no per-run fee on top. stepBudget is the ceiling worth setting deliberately — Credits & Usage is where the spending shows up.

Not part of this API

The sandbox a run works inside — its filesystem, its shell — is reached by the agent's own tools, not by you. Those endpoints exist but are internal, and they answer 404 on this base URL rather than pretending otherwise. Running your own containers on the platform is a separate offer; talk to us if that is what you need.