---
title: "Ask, answers from your docs"
url: /interfaces/ask
---

# Ask, answers from your docs

> Cited answers over your product's docs for your Customers and their agents, on the docs, in the portal and over MCP, with a person one step away.

Ask answers a reader's question from your product's own docs, cites each page it used, and says so when no page answers.

**One question, asked to answered.** A reader asks.

1. Search: the docs.
2. Draft (pages found): from those pages. Or no answer: the results.
3. Cite (drafted): page and section.
4. Answer (every line cited): cited.
5. Help (not enough): a person.

Each question is kept, answered or not.

## An answer, line by line
A Customer's agent asks over the docs MCP why a lookup cost nothing, and gets this.

```http title="Response"
HTTP/1.1 200 OK
Content-Type: application/json
X-Cost: price=0, currency="USD"
X-Request-Id: req_47b0e9c25d1a3f86c0e7

{
  "question": "Why did a lookup for initech.com cost nothing?",
  "answer": "A lookup that finds no company is a miss, and a miss is free.",
  "citations": [
    { "page": "/docs/errors#not_found", "section": "not_found" }
  ],
  "version": "v4",
  "answered": true
}
```

| Field | What it holds |
| --- | --- |
| `answer` | At most 120 words, each sentence backed by a [citation](/interfaces/ask.md#answers); a sentence no page supports is dropped before the answer leaves |
| `citations` | Up to 8 pages and sections, each at the [Version](/reference/platform.md#version) the reader calls |
| `answered` | `false` when no page answers; then `reason` says why and `results` holds the search results |
| `handoff` | With `handoff` on, the link that opens a [help request](/interfaces/support.md) with the question attached |

A price is never paraphrased: it prints from the Offer, as the reference does.

## Where a reader asks
| Who asks | Where | What comes back |
| --- | --- | --- |
| A developer reading the docs | The search box, under the results | The answer, each sentence linked to its section |
| A Customer's agent | `ask` on the docs MCP at `/docs` | The answer as text, with `citations` and `version` as data |
| A member in the portal | The help page, before a help request | The answer, then a button that opens the request with the question attached |

With `signedIn`, Ask also reads a signed-in reader's own plan and usage, for questions such as "how many calls are left".

## When Ask does not answer
Ask never acts, never reads another Customer's records, and never charges the reader. Each way it declines says why.

| The case | The reader gets |
| --- | --- |
| No page supports an answer | `answered: false`, `reason: "no_page"`, the search results, and the help link when `handoff` is on |
| A question about another Customer, or one that asks Ask to act or spend | `answered: false`, `reason: "out_of_scope"`, and the Verb's docs page when one does what was asked |
| Text in the question that tries to instruct Ask | Read as words to search, never as an order, as [untrusted text](/trust/security.md#places) is everywhere |
| A usage question from a reader who is not signed in | The docs' answer alone, with `reason: "sign_in"` and the sign-in link |
| The reader's questions for the day are spent | 429 [`ask_limited`](/reference.md#ask_limited), with `Retry-After` and the search results in `results` |
| Your AI allowance is spent and your spend cap holds | 503 [`ask_paused`](/reference.md#ask_paused), with the search results; search never stops |
| A question over 500 characters | 400 [`invalid_param`](/reference.md#invalid_param), naming the limit |
| The model behind Ask does not answer in 20 seconds | `answered: false`, `reason: "unavailable"`, and the search results |

Every question is kept, answered or not, with `Question.list` on the [Operator plane](/trust/planes.md). An unanswered one joins the unmet asks your product reports on [its life](/lifecycle.md#learn).

## Thirty questions a day
The lookup by domain answers 30 questions a reader a day, and hands the rest to a person.

```ts title="definition.ts"
import { define, secret } from 'apis.dev'

/** Any company by its domain, with its headcount and sector, and cited answers over its docs. */
export default define({
  name: 'companyfacts', domain: 'companyfacts.apis.dev',
  sources: {
    firms: { origin: 'https://firms.example.com', key: secret('FIRMS_KEY') },
  },
  Company: {
    domain:    { type: 'url!#',   from: 'firms', map: 'website' },
    employees: { type: 'number?', from: 'firms', map: 'headcount' },
    sector:    { type: 'string?', from: 'firms', map: 'industry' },
  },
  offer: {
    'Company.get': 0.002, 'Company.search': 0.005,
    free: { 'Company.get': 100 },
  },
  docs: { ask: { day: 30, handoff: true, signedIn: true } },  // on your AI allowance
})
```

## How much a reader may ask
| What | How much |
| --- | --- |
| Questions a reader asks each day | `day`, from 1 to 500; 20 when the file names none |
| A question | 500 characters |
| An answer | 120 words and 8 citations |
| Languages | The reader's [locale](/interfaces/locales.md) where the docs are written in it; else the docs' first locale, said so in the answer |
| Kept | Every question and answer, 400 days, then cold with the rest of the product's history |
| Who pays | Your AI allowance; a reader never pays for a question. Ask is a Launch feature |