---
title: "Chat with a Coherence agent"
method: POST
path: "/agents/messages"
tags: ["Agents"]
---

# Chat with a Coherence agent

`POST /agents/messages`

## Request

- Base URL: `https://api.getcoherence.io/v1`
- URL: `https://api.getcoherence.io/v1/agents/messages`
- Auth: HTTP bearer

Send a message to a Coherence agent (Nash by default). The agent runs its multi-step tool loop inside the workspace (for example records, documents, research and outreach drafts) and returns its final natural-language response. Tools the agent invokes still flow through the workspace's approval system, so this cannot bypass approval gates. Requires the `agents:write` scope, and the key's user must hold the `agents:run` permission (403 otherwise).

**Response modes.** By default the endpoint returns a single JSON object once the run completes. To receive incremental progress, request a stream by sending `Accept: text/event-stream` (or adding `?stream=true`); the response is then a Server-Sent Events stream. Named events: `open` (`{ agentId }`), `token` (`{ text }` — a chunk of the final answer; concatenate across events), `tool_call` (`{ tool, label }`), `done` (the same object as the synchronous JSON body), and `error` (`{ message }`). Lines beginning with `:` are keepalives. Raw model reasoning and raw tool output are never streamed. Disconnecting the client aborts the run.

## Query parameters

- `stream` 'true'

## Request body

- object
  - `message` string, required
  - `agentId` string, uuid: Optional. Targets a specific agent (with its custom system prompt). Omit to use the default Nash agent.

## Response `200`

Agent response. `application/json` for the default synchronous mode; `text/event-stream` when a stream is requested via `Accept: text/event-stream` or `?stream=true`.

- AgentResponse
  - `response` string: The agent's final natural-language reply
  - `success` boolean
  - `durationMs` integer
  - `toolCalls` integer
  - `error` string

## Other responses

- `401`: Authentication failed or missing.
- `404`: Agent not found (when agentId is provided)

---

[API](https://skmtc.dev/getcoherence/apis/coherence-api.md) · [All operations](https://skmtc.dev/getcoherence/apis/coherence-api/llms.txt) · [OpenAPI document](https://skmtc.dev/getcoherence/apis/coherence-api/revisions/622d56f657b1?raw)