---
title: "Send chat message"
method: POST
path: "/v1/agents/{agent_id}/chat"
tags: ["Agent Chat"]
---

# Send chat message

`POST /v1/agents/{agent_id}/chat`

## Request

- Base URL: `https://api.1claw.co`
- URL: `https://api.1claw.co/v1/agents/{agent_id}/chat`
- Auth: HTTP bearer

Send a message to an agent and receive a response via Shroud LLM.
Supports SSE streaming when Accept: text/event-stream is set.

Agents can call this endpoint on other agents within the same
organization for inter-agent communication (agent-to-agent chat).
The caller must be authenticated and belong to the same org as
the target agent.

## Path parameters

- `agent_id` string, uuid, required

## Request body

- SendChatMessageRequest
  - `message` string: User message text. Optional when `messages` includes a user turn.
  - `conversation_id` string, uuid
  - `mode` string
  - `model` string
  - `provider` string
  - `system_prompt` string: Stored on new conversations when `conversation_id` is omitted.
  - `system` string: Per-request system prompt alias (same precedence as `system_prompt_override`).
  - `system_prompt_override` string: Per-request override; highest precedence except inline `messages` system role.
  - `messages` object[]: Optional OpenAI-shaped history. When set, used for LLM context instead of DB history.
    - `role` string, required
    - `content` string, required
  - `llm_api_key_vault_id` string
  - `llm_api_key_path` string

## Response `200`

Chat response

- SendChatMessageResponse
  - `conversation_id` string, uuid
  - `message` ChatMessageResponse
    - `id` string, uuid
    - `conversation_id` string, uuid
    - `role` string
    - `content` string
    - `tool_calls` unknown
    - `tool_results` unknown
    - `tokens_prompt` integer
    - `tokens_completion` integer
    - `model` string
    - `created_at` string, date-time

## Other responses

- `401`: Authentication required or invalid
- `403`: Insufficient permissions

---

[API](https://skmtc.dev/1claw/apis/1claw-api.md) · [All operations](https://skmtc.dev/1claw/apis/1claw-api/llms.txt) · [OpenAPI document](https://skmtc.dev/1claw/apis/1claw-api/revisions/ae109b496830?raw)