Driving the Assistant

The assistant that runs inside the app is also reachable with an API key, so your own program can hand Monofile a task, watch it work, and stop it. With Calling Tools you drive each tool yourself. Here you describe the goal and the assistant picks the tools.

Start a task

POST /api/chats/stream creates a conversation and starts a run in one request.

{
  "mode": "agent",
  "effort": "balanced",
  "messages": [
    { "role": "user", "parts": [{ "type": "text", "text": "Read /Notes/plan.md and tidy its headings." }] }
  ]
}

curl -N https://www.monofile.ai/api/chats/stream \
  -H "Authorization: Bearer $MONOFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "agent",
    "effort": "balanced",
    "messages": [
      { "role": "user", "parts": [{ "type": "text", "text": "Read /Notes/plan.md and tidy its headings." }] }
    ]
  }'

The response is a stream of UI message events, the text as the model writes it plus a marker for every tool call and its result. Three headers tell you what you are watching:

To continue an existing conversation, post to /api/chats/{chatId}/stream with the full message history.

The run keeps going without you

Closing the connection does not stop the task. The server keeps running it and records every event it streams, so a long task survives your process exiting and you can rejoin the stream. See Long-Running Tasks.

Reconnect

Replays every event from the start of the run, then keeps streaming live until the run settles. Recorded events last seven days. A 204 means the run is over and its events are gone, so read the saved conversation with GET /api/chats/{chatId} instead.

Poll

Returns { "run": { ... } } with the run's status, error, costCents, budgetCents, token and step counts and timestamps. Statuses are queued, running, cancelling, waiting_approval, completed, failed and cancelled. The next read of a run that has produced nothing for 15 minutes marks it failed with an "interrupted" error.

Stop

Stops the run and keeps what it already did. The reply is { "runId", "mode", "status" }. mode is requested when the loop will stop at its next step, with status cancelling until it does, or finished when the run was already over.

Treat the finish of the stream and the finish of the run as two different things. The stream ends first; the conversation and the run ledger settle a moment later. If you need the saved transcript, poll until the status is terminal.

One run per conversation

A conversation runs one task at a time. Posting a new message while a run is live returns 409 with code: "RUN_ACTIVE" and the id of the run already in flight. Either wait for it, reconnect to it, or cancel it.

Approvals

Some actions pause for approval: reverting a whole run, deleting a version, revoking a share link, a destructive shell command. The run's status becomes waiting_approval and the stream carries a tool part awaiting a decision. Your client answers by sending the conversation back with an approval response attached, the same way the web client does. To avoid approval prompts entirely, run in read-only mode. See Approvals.

What it costs

Monofile meters runs in credits against the workspace that owns the key, with a per-run budget. When the budget runs out, the run stops. GET /api/chats/{chatId}/runs/{runId} reports costCents as it goes. See AI Credits and Usage.

Next steps