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

# Chat API

> Send customer questions to your AI agent and get back answers with citations.

The Chat API puts your AI agent inside your own app or portal. The agent answers from your public knowledge base and code and follows your [Policies](https://docs.decimal.app/policies.md), the same as the [Chat Widget agent](https://docs.decimal.app/chat-widgets/overview.md).

| Endpoint | Scope |
| - | - |
| [Send a message](https://docs.decimal.app/api-reference/chat/send-a-message.md) | `chat:write` |
| [Get conversation](https://docs.decimal.app/api-reference/chat/get-conversation.md) | `chat:read` |

## How a conversation works

Sending a message returns `202 Accepted` with a `conversation_id` and `status: "processing"`. The agent works in the background. Poll the conversation until `status` changes:

| Status | Meaning |
| - | - |
| `processing` | The agent is still working. Poll again. |
| `completed` | The answer is in `messages`. |
| `failed` | Something went wrong. Send the message again. |

```bash theme={null}
curl -X POST https://api.getdecimal.ai/v0/chat \
  -H "Authorization: Bearer sk-de-..." \
  -H "Content-Type: application/json" \
  -d '{"message": "How do I configure SSO?"}'
# → 202 { "conversation_id": "abc123", "status": "processing" }

curl https://api.getdecimal.ai/v0/chat/abc123 \
  -H "Authorization: Bearer sk-de-..."
```

`messages` holds the whole conversation, oldest first. Each message has a `role` of `user` or `assistant`. Assistant messages also carry `sources`: the title and URL of each article or code permalink the answer drew on. Show them as citations.

## Follow-up questions

Send the next message with the same `conversation_id`. The agent keeps the earlier messages as context.

Wait for the conversation to finish first. Sending to a conversation that's still `processing` returns `409` with code `conflict`.

## Limits

* A message can be up to 16,000 characters.
* Send an [idempotency key](https://docs.decimal.app/api-reference/idempotency.md) with each message so a retry after a timeout doesn't post it twice.
* Polling counts toward your [rate limits](https://docs.decimal.app/api-reference/rate-limits.md).

When the customer needs a person, [escalate the conversation](https://docs.decimal.app/api-reference/escalation/overview.md) to your helpdesk.


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