Copy page

Getting Started

Answer

Generate a grounded AI answer to a user question. The endpoint is fully autonomous by default: it runs web search, fetch, reranking, and cited answer generation in a single call.

Code
POST https://api.staan.ai/v2/answer

Quick start

Code
curl https://api.staan.ai/v2/answer \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the latest advances in fusion energy?",
    "mode": "short",
    "language": "fr",
    "markdown": true
  }'

Code
import requests

response = requests.post(
    "https://api.staan.ai/v2/answer",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "query": "What are the latest advances in fusion energy?",
        "mode": "short",
        "language": "fr",
        "markdown": True,
        "related_queries": True,
    },
)
data = response.json()
print(data["answer"])

Code
const res = await fetch('https://api.staan.ai/v2/answer', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: 'What are the latest advances in fusion energy?',
    mode: 'short',
    language: 'fr',
    markdown: true,
  }),
});
const { answer, sources, citations } = await res.json();

How it works

When sources is not provided, the pipeline runs fully automatically:

1. Query rewrite — reformulates the query for better search recall (disable with query_rewrite: false)
2. Web search — retrieves relevant pages, with optional domain filter
3. Fetch and chunk — downloads and splits page content
4. Rerank — selects the most relevant passages
5. Answer generation — produces a cited answer

When you supply sources, web search is bypassed and the pipeline starts at step 3 (or skips it entirely with sources_mode: "context").

Request body

Parameter	Type	Default	Description
query	string	—	Required. User question (1–2,000 characters).
stream	boolean	false	Stream the response as Server-Sent Events.
mode	"short" | "long"	"short"	Response length. Use "long" for detailed answers.
language	"fr" | "en"	"fr"	Answer language.
markdown	boolean	false	Format the answer with Markdown.
query_rewrite	boolean	true	Rewrite the query before search. Ignored when sources is set.
filter	string	—	Restrict search to a domain (e.g. "lemonde.fr"). Ignored when sources is set.
related_queries	boolean	false	Return four follow-up question suggestions.
sources	SourceItem[]	—	Caller-supplied sources (max 10). Bypasses web search.
sources_mode	"search" | "context"	"search"	How to handle supplied sources. See Caller-supplied sources.
history	HistoryMessage[]	—	Conversation history for multi-turn. Max 20 messages (10 turns).

Response

Non-streaming (stream: false)

Code
{
  "request_id": "01938fc2-1b3a-7e4d-9c12-a4f8e3c20d91",
  "answer": "Les dernières avancées en fusion nucléaire incluent...",
  "citations": [
    { "position": 142, "source_id": "1" },
    { "position": 310, "source_id": "3" }
  ],
  "sources": [
    {
      "id": "1",
      "url": "https://www.cea.fr/...",
      "title": "CEA — Fusion nucléaire"
    },
    {
      "id": "2",
      "url": "https://www.nature.com/...",
      "title": "Nature — Fusion milestone"
    },
    {
      "id": "3",
      "url": "https://www.iter.org/...",
      "title": "ITER — Latest news"
    }
  ],
  "related_queries": [
    "How does ITER work?",
    "What is the difference between fission and fusion?"
  ],
  "usages": [
    { "step": "query_rewrite", "input_tokens": 95, "output_tokens": 12 },
    { "step": "answer", "input_tokens": 2840, "output_tokens": 194 }
  ]
}

Response fields

Field	Type	Description
request_id	string	Request identifier.
answer	string	Generated answer text.
citations	array	Inline citation markers: { position, source_id }.
sources	array	Sources used: { id, url, title }.
related_queries	array	Follow-up suggestions (only if related_queries: true).
usages	array	Token usage per pipeline step: { step, input_tokens, output_tokens }.

Streaming

Set stream: true to receive a text/event-stream response. Events arrive in this order:

Event	Payload	Description
sources	Array<{ id, url, title }>	Emitted first — sources used for the answer.
assistant	string	Answer text chunk. Concatenate all chunks for the full answer.
citation	{ reference_ids: number[] }	Source references at the current position.
related	{ related_queries: string[] }	Follow-up suggestions (if related_queries: true).
usage	{ step, input_tokens, output_tokens }	Token usage for one pipeline step.
done	{ finish_reason: string }	End of generation.
usages	Array<{ step, input_tokens, output_tokens }>	Aggregated usage, emitted after done.

Code
event: sources
data: [{"id":"1","url":"https://www.cea.fr/...","title":"CEA — Fusion"}]

event: assistant
data: "Les dernières avancées en fusion nucléaire"

event: citation
data: {"reference_ids":[1]}

event: assistant
data: " incluent la réalisation d'un gain énergétique net..."

event: done
data: {"finish_reason":"stop"}

event: usages
data: [{"step":"answer","input_tokens":2840,"output_tokens":194}]

Caller-supplied sources

Provide sources when you already have a document set or SERP. Web search, query_rewrite, and filter are all ignored.

Source object

Field	Type	Required	Description
url	string	No	Page URL. If set without content, the API may fetch the page.
title	string	No	Document title.
content	string	No	Pre-extracted text (max 50,000 characters).

sources_mode

Value	Behaviour
"search"	Fetch URLs, chunk, and rerank (default). Use when you have URLs or snippets and want Staan to retrieve and rank passages.
"context"	Inject content directly — no fetch, chunk, or rerank. Use for short, pre-processed text where you control the context. In this mode, only the first 5,000 characters per source are injected.

Code
{
  "query": "What is the return policy?",
  "sources": [
    {
      "url": "https://www.example.com/returns",
      "title": "Return Policy",
      "content": "Our return policy allows customers to return any item within 30 days..."
    }
  ],
  "sources_mode": "context",
  "language": "fr"
}

Multi-turn conversations

Pass prior turns in history to maintain conversation context.

Rules:

• Strict alternation user → assistant, starting with user
• Max 20 messages (10 turns)
• user content: max 2,000 characters; assistant: max 10,000

Code
{
  "query": "And what about its applications in medicine?",
  "history": [
    { "role": "user", "content": "What is nuclear fusion?" },
    {
      "role": "assistant",
      "content": "Nuclear fusion is the process by which two light atomic nuclei combine..."
    }
  ],
  "language": "fr"
}

Error codes

HTTP status	Meaning
401	Missing or invalid Bearer token.
500	Internal server error.