POST /answer

1 min read

Asks the assistant one question and returns the answer, with the documents it came from. This is the endpoint the website widget uses, and the one to use for your own integration.

POST https://answers.snoowl.com/api/v1/answer
Authorization: Bearer ansk_…
Content-Type: application/json

Accepts a secret key, a website key or a preview key. See Keys.

Request

Field	Type	Required	Description
`question`	string	Yes	The customer’s question. Leading and trailing spaces are trimmed. 1 to 2,000 characters.
`history`	array	No	The conversation so far, oldest first, as `{ "role": "user" \| "assistant", "content": "…" }` objects. Only the last six are used. Other roles are ignored.
`session_id`	string	No	Your ID for this conversation. Shown in Conversations to group its answers. Up to 80 characters are kept.

Send history for follow-up questions. Without it, a question such as “and on the yearly plan?” can’t be understood. Include the assistant’s earlier answers as assistant turns, and leave out the question you’re asking now. Long turns are shortened: the assistant reads up to 1,000 characters of each.

Any other fields are ignored. In particular, the model and tone always come from Assistant settings.

Example

curl https://answers.snoowl.com/api/v1/answer \
  -H "Authorization: Bearer YOUR_ENDPOINT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "How do I get a refund?"}'

const res = await fetch("https://answers.snoowl.com/api/v1/answer", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_ENDPOINT_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    question: "How do I get a refund?",
    history: [], // earlier turns: [{ role: "user" | "assistant", content }]
  }),
});
const { answer, status, citations } = await res.json();
// status is "answered" or "declined" (your decline message, when the docs don't cover it)

import requests

res = requests.post(
    "https://answers.snoowl.com/api/v1/answer",
    headers={"Authorization": "Bearer YOUR_ENDPOINT_KEY"},
    json={"question": "How do I get a refund?"},
)
data = res.json()
print(data["answer"], data["status"], data["citations"])

A follow-up question, with the conversation so far:

{
  "question": "And on the yearly plan?",
  "history": [
    { "role": "user", "content": "How do I get a refund?" },
    { "role": "assistant", "content": "You can ask for a refund within 30 days of paying, from Billing › Invoices." }
  ],
  "session_id": "chat-8f41c2"
}

Response

A 200 with the answer:

{
  "answer": "Yearly plans can be refunded within 30 days of paying. After that, the plan runs to the end of its year.",
  "status": "answered",
  "citations": [
    {
      "doc": "Refunds",
      "url": "https://help.example.com/billing/refunds",
      "quote": "Annual plans: you can ask for a full refund within 30 days of payment. After 30 days, the plan stays active until the end of the billing year…"
    }
  ],
  "latency_ms": 1840,
  "answer_id": "3f2a9c1e5b7d40a8b1c2"
}

Field	Type	Description
`answer`	string	The answer, or your decline message. May contain light Markdown: `bold`, `code`, `-` bullets and `1.` steps.
`status`	string	`answered`, or `declined` when your documents don’t cover the question.
`citations`	array	The documents the answer used, one entry per document, in the order used. Empty when declined.
`citations[].doc`	string	The document’s name: the file name, the page title, or the name you gave pasted text.
`citations[].url`	string or null	The page’s address, for documents added as a web page or from a sitemap. `null` for files and pasted text.
`citations[].quote`	string	The passage the answer used, up to 280 characters, with `…` when shortened.
`latency_ms`	integer	How long the answer took on Snoowl’s side, in milliseconds.
`answer_id`	string	This answer’s ID. Send it to POST /feedback with a thumbs up or down.

A declined answer looks like this:

{
  "answer": "I'm sorry, I can't find that in our documentation. Please contact our support team.",
  "status": "declined",
  "citations": [],
  "latency_ms": 420,
  "answer_id": "9b07e4d2a1c34f5e8d6a"
}

Use status, not the text, to tell the two apart. For example, offer a “Contact support” button when status is declined.

Errors

Errors use the error format every endpoint uses. The ones to expect here:

Status	Why
`400`	`question` is empty or over 2,000 characters
`401`	The key is missing, unknown or revoked
`402`	The workspace’s prepaid balance is used up
`403`	A website key used from a site that isn’t on its list
`429`	The key’s per-minute limit or monthly cap is reached
`503`	The answer couldn’t be written just now. Retry after a short wait. Not charged.

Each answer is charged and logged in Conversations. See Billing.