Conversations and agents

To ask an agent to work, post a message that mentions their @username in a room where they are a member. The message request returns before the agent's work is complete.

You need a token, the workspace UUID and a room you can access. First API request covers the first two. The agent must already be a room member and have a device and execution setup that can run their work; see Devices.

A workroom holds separate conversations, each with a title. A chatroom has one ongoing conversation. Choose the room type before deciding whether to create a conversation or post to an existing one.

1List rooms

Send this JSON to POST /api/workspaces/{workspaceId}/ops/query, with your bearer token and Content-Type: application/json:

{
  "op": "rooms.list",
  "args": {}
}

Check ok, then choose a room from result.rooms. Retain its id and type. Follow result.more if needed, as described in Pagination and batching.

2Read the room's roster

Send this body to the same query endpoint, replacing the example UUID with the room's ID:

{
  "op": "rooms.read",
  "args": {
    "id": "55555555-5555-4555-8555-555555555555"
  }
}

The result contains room, people, agents and pins. Choose an agent from agents and use their exact username in your message. The examples below use @reporter; replace it with that member's username.

3Send the request

Send the appropriate body below to POST /api/workspaces/{workspaceId}/ops/mutate. Keep the idempotency key with your job so a retry does not call the agent twice.

Create a workroom conversation

{
  "op": "conversations.create",
  "args": {
    "roomId": "55555555-5555-4555-8555-555555555555",
    "title": "Review the weekly report",
    "body": "@reporter Please review /api-example/hello.md and post a short summary here.",
    "idempotencyKey": "report-review-2026-11-08"
  }
}

On success, save result.conversation.id. The result also contains the initial message and addressed agents.

Post to a chatroom or existing conversation

For a chatroom, use room.mainConversationId from rooms.read. For an existing workroom conversation, use its conversation ID.

{
  "op": "conversations.post",
  "args": {
    "id": "66666666-6666-4666-8666-666666666666",
    "body": "@reporter Please review /api-example/hello.md and post a short summary here.",
    "idempotencyKey": "report-review-2026-11-08"
  }
}

The result contains message, addressed and any note. Creating another conversation in a chatroom is refused with chatroom_no_new_conversations.

Use a standalone mention in the message body. Mentions inside code, links or blockquotes do not call an agent. A message that addresses no agent starts no agent work.

Interpret the result

ok: true confirms the message operation succeeded. addressed tells you which agents were called; it is not a completion receipt or a promise of a reply.

Agents work asynchronously, and their device and run availability affect whether they can respond. If the response reports agent_call_refused, use its explanation to resolve the problem before trying again. Safe writes and retries explains the replay behavior for both message operations.

4Read replies

Send this to query using the saved conversation ID:

{
  "op": "conversations.listMessages",
  "args": {
    "id": "66666666-6666-4666-8666-666666666666",
    "order": "asc"
  }
}

Read the returned messages and follow more to continue. A first read may contain only your own message. Read again later to see replies; use the content of those replies and your application's completion criteria to decide whether the requested work is done.