Assistant APIAsk a question

Ask a question

Answers a question from your documentation. Credits are used only when answered is true.

With "stream": true, the response is text/event-stream instead: answer.delta events carry the answer as it is written, and answer.completed carries the object below. See Stream events.

curl -X POST "https://api.documentation.ai/api/v1/assistant/answers" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-48213-message-3" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
  "message": "How do I reset my password?"
}'
{
  "id": "ans_7f3c2a9e41b84d0e9a1c6b5d2e8f0a13",
  "conversation_id": null,
  "answered": true,
  "reason": null,
  "answer": "Open **Account > Security** and choose **Reset password**. See [Reset your password](https://docs.acme.com/account/reset-password).",
  "format": "markdown",
  "confidence": 0.92,
  "sources": [
    {
      "title": "Reset your password",
      "url": "https://docs.acme.com/account/reset-password"
    }
  ],
  "follow_up_questions": [
    "How do I turn on two-factor authentication?"
  ],
  "created_at": "2026-11-06T09:30:00.000Z"
}
POST
/answers
POST
Base URLstring

Target server for requests. Edit to use your own host.

Bearer Token
Bearer Tokenstring
Required

An Assistant API key from Settings > Assistant API: the secret key (asst_sk_...) from servers and tools, or the publishable key (asst_pk_...) or a reader credential (asst_rc_...) from pages on the key's allowed origins. See Authentication.

An Assistant API key from Settings > Assistant API: the secret key (asst_sk_...) from servers and tools, or the publishable key (asst_pk_...) or a reader credential (asst_rc_...) from pages on the key's allowed origins. See Authentication.
Content-Typestring
Required

The media type of the request body

Options: application/json
header
Idempotency-Keystring

Requests with the same key and the same body within 10 minutes return the first answer, uncharged, with the Idempotent-Replayed: true header. Without it, the same message after the same earlier messages counts as a repeat. In a page, only the same visitor's requests count as repeats. A repeat sent while the first is still being answered waits for that answer. Publishing a change to which pages need sign-in, or to their roles, ends the 10 minutes early. Send it if your tool retries after giving up on a slow answer. With it, an answer keeps being written after your tool hangs up, so the retry gets it, charged once. Without it, hanging up stops the answer, and nothing is charged.

Min length: 1 • Max length: 200
messagestring
Required

The question, up to 16,000 characters.

Min length: 1 • Max length: 16000
conversation_idstring

Your own id for the conversation, up to 200 characters, such as a ticket id. Earlier messages are kept for you, separately for each key, for 30 days after the last one. Secret key only: pages send history. Can't be sent with history.

Min length: 1 • Max length: 200
historyarray

Earlier messages, oldest first. At most 49, so the conversation holds 50 with the new message. The assistant reads the latest 10 of them, or 4 in Lite mode, as on your docs site, so you can send a whole thread. Can't be sent with conversation_id.

streamboolean

true to receive the answer as stream events.

formatstring

The answer's format. HTML escapes any HTML in the answer. slack is Slack's own message formatting, ready to post as a message's text.

Options: markdown, html, text, slack
timeout_secondsnumber

How long to wait for an answer, from 3 to 120 seconds, counted from when the request arrives. Defaults to 25, or 120 with stream. Past it, the response is not answered, with reason set to timeout, and nothing is charged.

Min: 3 • Max: 120
readerobject

The reader you are asking for, with the secret key only. It only narrows what the key reads.

Request Preview
Response

Response will appear here after sending the request

Authentication

header
Authorizationstring
Required

Bearer token. An Assistant API key from Settings > Assistant API: the secret key (asst_sk_...) from servers and tools, or the publishable key (asst_pk_...) or a reader credential (asst_rc_...) from pages on the key's allowed origins. See Authentication.

Headers

Idempotency-Keystring

Requests with the same key and the same body within 10 minutes return the first answer, uncharged, with the Idempotent-Replayed: true header. Without it, the same message after the same earlier messages counts as a repeat. In a page, only the same visitor's requests count as repeats. A repeat sent while the first is still being answered waits for that answer. Publishing a change to which pages need sign-in, or to their roles, ends the 10 minutes early.

Send it if your tool retries after giving up on a slow answer. With it, an answer keeps being written after your tool hangs up, so the retry gets it, charged once. Without it, hanging up stops the answer, and nothing is charged.

Example:
ticket-48213-message-3

Body

application/json
messagestring
Required

The question, up to 16,000 characters.

Example:
How do I reset my password?
conversation_idstring

Your own id for the conversation, up to 200 characters, such as a ticket id. Earlier messages are kept for you, separately for each key, for 30 days after the last one. Secret key only: pages send history. Can't be sent with history.

historyarray

Earlier messages, oldest first. At most 49, so the conversation holds 50 with the new message. The assistant reads the latest 10 of them, or 4 in Lite mode, as on your docs site, so you can send a whole thread. Can't be sent with conversation_id.

streamboolean

true to receive the answer as stream events.

formatstring

The answer's format. HTML escapes any HTML in the answer. slack is Slack's own message formatting, ready to post as a message's text.

Allowed values:markdownhtmltextslack
timeout_secondsnumber

How long to wait for an answer, from 3 to 120 seconds, counted from when the request arrives. Defaults to 25, or 120 with stream. Past it, the response is not answered, with reason set to timeout, and nothing is charged.

readerobject

The reader you are asking for, with the secret key only. It only narrows what the key reads.

Responses

idstring

The answer's id, starting with ans_. Send it to Rate an answer.

conversation_idstring

The conversation_id you sent, or null.

answeredboolean

true when the assistant answered from your docs. Credits are used only then.

reasonstring

Why answered is false. small_talk is a reply to a greeting or thanks, such as "hi": send answer as it is, without handing off. null when answered.

Allowed values:no_answer_foundtimeoutsmall_talk
answerstring

The answer in the requested format, with full links. Empty when not answered, except for small_talk.

formatstring

The format of answer.

Allowed values:markdownhtmltextslack
confidencenumber

The assistant's confidence, from 0 to 1. null after a timeout.

sourcesarray

The pages the answer cites, with full URLs. An answer from a PDF your team uploaded lists the PDF by name, with url set to null, as it has no web address.

follow_up_questionsstring[]

Questions the reader may ask next. Often empty, so treat it as optional.

created_atstring

When the answer was given, in ISO 8601 UTC.