> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sempera.org/llms.txt
> Use this file to discover all available pages before exploring further.

# API chat

> Authenticated text conversations with a published agent, channel enablement, workspace-bound continuations and preview tool policy.

API chat sends a text message to an agent's published configuration. It is authenticated server-to-server access, not a public widget. It uses the existing typed runtime and its workspace privacy, model admission and daily message caps. Integration tools retain preview policy; enabling the channel is not approval for live integration writes.

Apply migration 0218\_agent\_api\_chat\_channels before serving these routes. No provider is contacted by that migration or by channel setup. Missing storage fails closed.

## Channel configuration

GET /v1/agents/\{agent\_id}/channels/api-chat requires agents:read and a workspace-bound credential able to read the agent.

PATCH /v1/agents/\{agent\_id}/channels/api-chat requires agents:write and the configure\_integration role capability. Send exactly \{"enabled":true} or \{"enabled":false}. The response is read back from the same workspace's durable channel row. Writes are audited. A session write also requires the usual CSRF proof.

## Messages

POST /v1/agents/\{agent\_id}/chat requires sessions:write and talk\_to\_agent. The channel must be enabled. Send \{"message":"Hello"}. The message limit is 4,000 characters. Optional session\_id continues the returned opaque chat handle. The workspace, agent and credential must all match the opening request. A wrong or expired handle returns 404, a simultaneous turn returns 409, and capacity or daily-message limits return 429. Disabled channels return 403 before inference. Provider or published-configuration unavailability is reported, never replaced with a simulated answer.

A successful response includes id, object (chat), agent\_id, channel (api\_chat), reply, ended, tool\_policy (preview), expires\_in\_seconds and note. Responses are no-store. Conversation evidence remains in the existing typed conversation store, with its preview classification intact. API chat does not relabel these records as live phone calls.

In Conversations, these records carry the API chat channel and their last recorded activity time. Ordinary typed previews remain Web chat. The session read returns channel `api_chat` for API chat records ([Sessions and calls](https://docs.sempera.org/sessions-and-calls.md)).

Sessions expire after 30 minutes idle. At most 20 are held per workspace and 200 per process, including openings in flight. A server restart ends open handles. Continue with the same credential; do not share a handle between users. API keys belong on your server and must never be embedded in browser JavaScript. No additional public ingress or provider activation is introduced.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.