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?"
}'
import requests
import json
url = "https://api.documentation.ai/api/v1/assistant/answers"
headers = {
"Content-Type": "application/json",
"Idempotency-Key": "ticket-48213-message-3",
"Authorization": "Bearer YOUR_API_TOKEN"
}
data = {
"message": "How do I reset my password?"
}
response = requests.post(url, headers=headers, json=data)
print(response.json())
const response = await fetch("https://api.documentation.ai/api/v1/assistant/answers", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Idempotency-Key": "ticket-48213-message-3",
"Authorization": "Bearer YOUR_API_TOKEN"
},
body: JSON.stringify({
"message": "How do I reset my password?"
})
});
const data = await response.json();
console.log(data);
package main
import (
"fmt"
"net/http"
"bytes"
"encoding/json"
)
func main() {
data := []byte(`{
"message": "How do I reset my password?"
}`)
req, err := http.NewRequest("POST", "https://api.documentation.ai/api/v1/assistant/answers", bytes.NewBuffer(data))
if err != nil {
panic(err)
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Idempotency-Key", "ticket-48213-message-3")
req.Header.Set("Authorization", "Bearer YOUR_API_TOKEN")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
fmt.Println("Response Status:", resp.Status)
}
require 'net/http'
require 'json'
uri = URI('https://api.documentation.ai/api/v1/assistant/answers')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri)
request['Content-Type'] = 'application/json'
request['Idempotency-Key'] = 'ticket-48213-message-3'
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request.body = '{
"message": "How do I reset my password?"
}'
response = http.request(request)
puts response.body
{
"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"
}
{
"error": "invalid_request",
"message": "message must not be empty."
}
{
"error": "key_invalid",
"message": "This key is not valid. Check it was copied in full."
}
{
"error": "credits_exhausted",
"message": "This account has no AI credits left and overage is off. Add credits or turn on overage in the dashboard."
}
{
"error": "plan_not_included",
"message": "The Assistant API needs a Standard plan or higher."
}
{
"error": "site_not_published",
"message": "This documentation has not been published yet."
}
{
"error": "request_in_progress",
"message": "The same request is still being answered. Retry in a moment for its answer.",
"retry_after_seconds": 2
}
{
"error": "request_too_large",
"message": "Requests are limited to 64 KB."
}
{
"error": "rate_limited",
"message": "This key allows 60 requests a minute. Retry after 12 seconds.",
"retry_after_seconds": 12
}
{
"error": "internal_error",
"message": "Something went wrong on our side. Retry shortly."
}
{
"error": "temporarily_unavailable",
"message": "The assistant could not answer right now. Retry shortly.",
"retry_after_seconds": 5
}
/answers
Target server for requests. Edit to use your own host.
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.
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.The media type of the request body
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.
The question, up to 16,000 characters.
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.
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.
true to receive the answer as stream events.
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.
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.
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
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
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.
ticket-48213-message-3Body
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.
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.
true to receive the answer as stream events.
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.
markdownhtmltextslackHow 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.
The reader you are asking for, with the secret key only. It only narrows what the key reads.
Responses
The answer's id, starting with ans_. Send it to Rate an answer.
The conversation_id you sent, or null.
true when the assistant answered from your docs. Credits are used only then.
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.
no_answer_foundtimeoutsmall_talkThe answer in the requested format, with full links. Empty when not answered, except for small_talk.
The format of answer.
markdownhtmltextslackThe assistant's confidence, from 0 to 1. null after a timeout.
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.
Questions the reader may ask next. Often empty, so treat it as optional.
When the answer was given, in ISO 8601 UTC.