Introduction

The allqus API gives your application the same answers as allqus.com: it searches the web for your question and writes a short, up-to-date answer with numbered citations. You can also get the raw web results, or use the OpenAI-compatible chat endpoint with the official OpenAI SDKs.

All requests and responses are JSON (UTF-8) over HTTPS. Times are Unix seconds; amounts are in Swiss francs (CHF).

Authentication

Create a key in the Console. Send it in the Authorization header of every request (the x-api-key header works too):

Authorization: Bearer aq_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Quick start

1. Sign in and open the Console.
2. Top up your balance: any amount from CHF 5, paid through Stripe.
3. Create a key and save it on your server, e.g. export ALLQUS_API_KEY=aq_live_…
4. Send your first question:

curl https://allqus.com/api/v1/answer \
  -H "Authorization: Bearer $ALLQUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What are the opening hours of the Kunsthaus Zürich?"}'

POST /answer

Answers a question from current web sources. Price: CHF 0.08 per successful request. Typical time: 5–25 seconds (use streaming to show text as it arrives).

Request body

Response

{
  "id": "ans_6f1c0a9e2b7d4c18a3e5f0b2",
  "object": "answer",
  "created": 1793491200,
  "model": "allqus-answer",
  "question": "What are the opening hours of the Kunsthaus Zürich?",
  "answer": "The Kunsthaus Zürich is open Tuesday to Sunday from 10:00 to 18:00, and until 20:00 on Thursdays [1]. It is closed on Mondays [1][2].",
  "sources": [
    { "n": 1, "title": "Visit – Kunsthaus Zürich", "url": "https://www.kunsthaus.ch/en/visit/", "domain": "kunsthaus.ch" },
    { "n": 2, "title": "Kunsthaus Zürich – Zürich Tourism", "url": "https://www.zuerich.com/en/visit/...", "domain": "zuerich.com" }
  ],
  "related": ["How much is a ticket for the Kunsthaus?", "Is the Kunsthaus free on Wednesdays?"],
  "usage": { "price_chf": 0.08, "balance_chf": 41.92 }
}

Citations in answer look like [1] and refer to sources[].n. Show the sources next to the answer so your users can check the facts.

Answer format. answer is Markdown: short paragraphs, ### headings, lists, tables and **bold**. Answers about amounts start with the headline figure in bold (for example **Total:** $800,000), and “which is best” questions get a numbered list of options, best first. Render it with any Markdown library, or strip the Markdown if you need plain text. The answer is written in the language of the question.

Simple sums, greetings and translations are answered without a web search, so sources can be empty; the answer then has no citations.

Streaming

With "stream": true the response is text/event-stream. Events arrive in this order: sources → many delta → related → done. The done event has the complete answer and the usage. If something fails, an error event is sent instead of done and you are not charged.

event: sources
data: {"sources":[{"n":1,"title":"…","url":"https://…","domain":"…"}]}

event: delta
data: {"text":"Heat pumps move heat "}

event: delta
data: {"text":"from outside air into your home [1]."}

event: done
data: {"id":"ans_…","object":"answer","answer":"…","sources":[…],"related":[…],"usage":{"price_chf":0.08,"balance_chf":41.84}}

POST /chat/completions

OpenAI-compatible version of /answer, priced at CHF 0.08 per successful request. Use the official OpenAI SDKs with base_url set to https://allqus.com/api/v1 and model allqus-answer (any model name is accepted).

import os
from openai import OpenAI

client = OpenAI(base_url="https://allqus.com/api/v1", api_key=os.environ["ALLQUS_API_KEY"])

completion = client.chat.completions.create(
    model="allqus-answer",
    messages=[{"role": "user", "content": "Latest news about Swiss interest rates?"}],
)
print(completion.choices[0].message.content)

• The last user message is answered; up to 6 earlier user/assistant pairs are used as context. System messages are ignored, because allqus answers from sources.
• stream and stream_options.include_usage are supported. Parameters such as temperature, tools or response_format are accepted but ignored.
• message.content ends with a numbered “Sources:” list. The response also has a sources array (in the last stream chunk when streaming).

{
  "id": "chatcmpl-6f1c0a9e2b7d4c18a3e5f0b2",
  "object": "chat.completion",
  "created": 1793491200,
  "model": "allqus-answer",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "The SNB lowered its policy rate to … [1].\n\nSources:\n[1] SNB monetary policy assessment – https://www.snb.ch/…" },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 2104, "completion_tokens": 186, "total_tokens": 2290 },
  "sources": [{ "n": 1, "title": "SNB monetary policy assessment", "url": "https://www.snb.ch/…", "domain": "snb.ch" }]
}

POST /search

Ranked web results without AI writing, for your own ranking, retrieval (RAG) or agents. Price: CHF 0.03 per successful request. GET /search?query=…&limit=… works too.

curl https://allqus.com/api/v1/search \
  -H "Authorization: Bearer $ALLQUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "best hiking trails Engadin", "limit": 5}'

GET /balance and GET /models

Both are free. /balance returns your prepaid balance and the current prices; /models lists allqus-answer for OpenAI-compatible tools.

curl https://allqus.com/api/v1/balance -H "Authorization: Bearer $ALLQUS_API_KEY"

Pricing & billing

• Prepaid: top up any amount from CHF 5 in the Console; payments go through Stripe and you get a receipt by email. Credit stays valid for 24 months after your last top-up.
• Charged per request: the price is reserved when a request starts. If the request fails (any 5xx, or the stream ends with an error event), it is refunded automatically.
• Balance too low: requests are refused with 402 insufficient_balance; nothing is charged.
• Every response has the headers x-allqus-price-chf, x-allqus-balance-chf and x-request-id. Your spending per day and each request are listed in the Console.
• Prices can change with 30 days' notice by email; your balance is never reduced by a price change.

Rate limits & timeouts

• 60 requests per minute per key. Above that you get 429 rate_limited with a Retry-After header (seconds). Need more? Contact us.
• Answers usually take 5–25 seconds; set your HTTP client timeout to at least 60 seconds, or use streaming.
• Questions and queries can be up to 400 characters; history up to 6 turns of 6,000 characters each.

Errors

Errors use the same format as the OpenAI API, so existing error handling keeps working:

{ "error": { "type": "billing_error", "code": "insufficient_balance", "message": "Your prepaid balance is too low for this request. …" } }

Best practices

• Show the sources with every answer and link to them; answers are written by AI and can contain mistakes.
• Cache answers to questions your users ask often (for minutes or hours, depending on how fast the topic changes) to save cost.
• Retry only on 429 and 5xx, with exponential backoff (e.g. 1 s, 2 s, 4 s). Don't retry 4xx errors other than 429.
• Log the x-request-id header; include it when you contact support about a request.
• Watch your balance with GET /balance and top up before it runs out.

Data & privacy

• Questions you send through the API are answered and then kept, with the answer, in allqus's internal search history for a limited time (90 days) for quality, support and abuse prevention. Only the allqus team can see them; they are never shown publicly or to other customers, and never used to train AI models.
• For billing and support we keep, per request: time, endpoint, key, price, status, duration and token counts, for 13 months.
• To answer, the question is sent to our AI and search provider. Details in the privacy policy and the API terms.
• Don't send personal data of other people unless you are allowed to and it is needed for the question.

Changelog

• 3 November 2026: clearer answers: the key figure in bold, numbered sections with tables for amounts, and a ranked list for “which is best” questions, all as plain Markdown (also when streaming). Related questions are always in the language of the question. Sums, greetings and translations are answered faster, without a web search (sources is then empty). A backup AI takes over if the main one is unavailable, so fewer requests fail. No changes to endpoints, parameters or prices.
• 1 November 2026: v1 released with /answer (with streaming), /chat/completions, /search, /balance and /models.