---
title: "Ask the Clarm agent a question"
method: POST
path: "/api/agent/chat"
tags: ["Agent"]
---

# Ask the Clarm agent a question

`POST /api/agent/chat`

Sends one natural-language question to the Clarm agent and returns the complete answer with source citations. No authentication required. The agent answers questions about the Clarm product, pricing, integrations, compliance posture, and use cases, grounded in the approved content indexed for the public clarm.com agent. Rate limited at the edge: 20 requests per minute per client IP and 200 requests per hour across the endpoint. Over-limit requests return 429 with a Retry-After header carrying the number of seconds to wait.

## Request body

- union — One question for the Clarm agent. Supply exactly one of the four accepted keys; `message` is canonical and the others are accepted aliases.
  - object
    - `message` string, required — The question to ask, 1 to 2000 characters.
    - `query` string — Alias for `message`.
    - `question` string — Alias for `message`.
    - `text` string — Alias for `message`.
  - object
    - `message` string — The question to ask, 1 to 2000 characters.
    - `query` string, required — Alias for `message`.
    - `question` string — Alias for `message`.
    - `text` string — Alias for `message`.
  - object
    - `message` string — The question to ask, 1 to 2000 characters.
    - `query` string — Alias for `message`.
    - `question` string, required — Alias for `message`.
    - `text` string — Alias for `message`.
  - object
    - `message` string — The question to ask, 1 to 2000 characters.
    - `query` string — Alias for `message`.
    - `question` string — Alias for `message`.
    - `text` string, required — Alias for `message`.

## Response `200`

The agent answered.

- AgentChatResponse — The agent answer plus the sources it drew on.
  - `answer` string, required — The complete answer text.
  - `citations` Citation[] — Sources the answer drew on. Omitted when the agent cited nothing.
    - `title` string, required — Human-readable title of the source document.
    - `url` string, uri, required — Canonical URL of the source document.
  - `meta` AgentChatMeta, required — Provenance for the answer and pointers to further machine-readable context.
    - `model` string, required — Identifier of the answering agent.
    - `note` string, required — Short provenance note naming Clarm as the answering party.
    - `llms_txt` string, uri, required — URL of the curated site summary.
    - `llms_full_txt` string, uri, required — URL of the extended reference.

## Other responses

- `400` — The body was not JSON, carried no question, or the question exceeded 2000 characters.
- `413` — The request body exceeded the 8 KiB limit.
- `429` — Rate limit exceeded for this client IP or for the endpoint as a whole.
- `500` — The agent produced no answer, or the request failed unexpectedly.
- `502` — The upstream agent could not be reached.

---

[API](https://skmtc.dev/clarm/apis/clarm-public-api.md) · [All operations](https://skmtc.dev/clarm/apis/clarm-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/clarm/clarm-public-api/revisions/ff890a5d2a91/schema)