Ask

Discover APIs for a question

POST /v2/ask requires ask:create. It uses the Ask page’s interpreter and source searches, returning choices from Apiosk and Coinbase Bazaar. Discovery makes no paid provider request and creates no plan or approval. The two surfaces share the discovery implementation. Separate requests can produce different wording or alternative providers because model interpretation and directory listings vary; responses are not guaranteed to be identical.

curl https://gateway.apiosk.com/v2/ask \
  -H "Authorization: Bearer $APIOSK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"Find filed accounts for Mollie B.V."}'

The body contains question only: 1–16000 UTF-16 code units. The response has parsed_request, apis, both origin results in searches, and errors. status is choices, needs_input when no choices match, or partial if an origin search is unavailable. Inspect every choice’s executable flag.

Choice field	Meaning
`api_id`	Opaque selection ID to copy into `/v2/execute`; do not construct it
`capability`	Exact operation for this selection; copy it alongside `api_id`
`name`, `source_slug`, `origin`, `url`	Source/provider identity and published URL
`executable`	The server has admitted an executable contract for this choice
`inputs`	Declared input fields, required flags and JSON schemas
`input_values`	Literal values bound from the question and declared defaults
`missing_inputs`	Required fields you must supply before execution
`outputs`	Declared output fields and schemas, or `null` if unpublished
`lookup`	Available native name lookup when a company identifier is missing
`buyer_price`	Current per-call buyer price in millionths of USDC (`buyer_atomic`)

Output values arrive after execution. Discovery returns output contracts; it does not fabricate source data. A directory-only choice has executable: false. Even an executable choice may need additional inputs. Review the fields and total spending cap; a native lookup can add steps and cost.

Execute the selected API

POST /v2/execute requires sources:execute, Idempotency-Key, and max_spend. It uses the same selected-source preparation, approval, executor and ledger as the Ask page. It does not reinterpret the question or choose a replacement API.

curl https://gateway.apiosk.com/v2/execute \
  -H "Authorization: Bearer $APIOSK_KEY" \
  -H "Idempotency-Key: my-selected-api-request-1" \
  -H "Content-Type: application/json" \
  -d '{
    "api_id":"COPY_FROM_ASK",
    "capability":"COPY_FROM_ASK",
    "input":{"company.name":"Mollie B.V."},
    "max_spend":"0.10",
    "wait_seconds":25
  }'

Replace the example input with the selected choice’s input_values, plus any missing fields. Preserve the exact field names. max_spend is the approved total in USD, not an atomic amount. The current price, key limits and balance are checked before purchase. Reuse the same idempotency key and selection/input for retries; changed selection/input under that key returns 409. Registered APIs return completed with results/data and usage. External providers return the saved purchase view: succeeded, result, result_present and ledger-backed billing. Both return id; running uses HTTP 202. Read GET /v2/runs/{id} to recover progress and results. A successful payment with result_present: false needs read-only recovery, never another purchase. External execution is asynchronous; wait_seconds applies to registered APIs. To verify a deployment, send the same question through Ask and this endpoint, compare source IDs, capabilities, input/output contracts and prices, then run one selected API within an approved cap. Repeat the identical execution request and check that the run ID, saved output and ledger charge are unchanged.

View saved annual accounts

The App presents supported structured annual accounts with named key figures, balance-sheet and income-statement tables, and numbers formatted for the browser’s locale. The financial year and source dates remain visible. A currency is shown only when supplied by the source; the billing currency does not establish the currency of the accounts. The filing year may be older than the current year. Opening the full result reuses the saved data without another provider purchase. Choose View full answer to open it. On phones, pull down from the drawer’s handle or header to close it; a short pull settles back into place. The close button remains available, and the answer scrolls between the fixed header and footer. Full source data and JSON preserve the original response. CSV exports the labelled financial fields and their source values. The HTTP API continues to return source data rather than the App’s display formatting.

Optional multi-source planner

The previous question-to-plan contract is available at /v2/ask/plan. Move clients that send execution_mode, limit or wait_seconds with a question to that path. Its saved-run, approval and continuation endpoints are unchanged. Explicit workflow requests remain supported by /v2/ask.

POST /v2/ask/plan

Requires ask:create.

curl https://gateway.apiosk.com/v2/ask/plan \
  -H "Authorization: Bearer $APIOSK_KEY" \
  -H "Idempotency-Key: intent-signals-2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{"question":"Find the registered address and the latest filed accounts for Mollie B.V.","limit":5}'

Field	Type	Default	Meaning
`question`	string, 1–4000 chars	required unless `workflow` is supplied	The question, in the user’s own words
`execution_mode`	`"plan"` or `"auto"`	`"plan"`	`auto` runs the plan straight away when it fits `max_spend`
`max_spend`	decimal USD	none	Required with `auto`; the ceiling for the whole plan
`limit`	integer 1–50	none	Cap the number of result documents returned
`wait_seconds`	integer 0–55	25	With `auto`, how long to wait before answering `202`

{
  "id": "5c1f…",
  "status": "requires_approval",
  "question": "Find the registered address and the latest filed accounts for Mollie B.V.",
  "plan": {
    "quote_ref": "9ad2…",
    "expires_at": "2026-09-22T18:40:00Z",
    "steps": [
      { "source_id": "kvk-dutch-business-register", "operation": "company_registry.search", "name": "Company search",
        "conditional": false,
        "estimated_cost": { "amount": 0.023, "amount_micro_usd": "23000", "currency": "USD" } },
      { "source_id": "kvk-dutch-business-register", "operation": "company.financial-statements", "name": "Annual accounts",
        "conditional": false,
        "estimated_cost": { "amount": 0.115, "amount_micro_usd": "115000", "currency": "USD" } }
    ],
    "estimated_total": { "amount": 0.138, "amount_micro_usd": "138000", "currency": "USD" }
  },
  "usage": { "sources": [], "cost": { "amount": 0, "amount_micro_usd": "0", "currency": "USD" } },
  "errors": []
}

The plan and amounts above illustrate the response shape; read live source details for current prices. Planning is free. estimated_total is the maximum the run may cost; you are charged what the sources actually cost, which can be less.

Run it later

POST /v2/asks/{id}/run

Requires ask:execute.

curl https://gateway.apiosk.com/v2/asks/5c1f…/run \
  -H "Authorization: Bearer $APIOSK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"max_spend":1.00,"limit":5}'

Running an ask twice returns the same run. It never starts a second purchase.

Run it immediately

{
  "question": "Find the registered address and the latest filed accounts for Mollie B.V.",
  "execution_mode": "auto",
  "max_spend": 1.00,
  "limit": 5
}

With auto, Apiosk runs the plan without a second call, but only when all four hold: the plan’s maximum cost is within max_spend, within the key’s per-request limit, within what the key may still spend this month, and within the organisation’s balance. If the plan costs more than max_spend, you get the plan back, unrun and unbilled:

{
  "id": "5c1f…",
  "status": "requires_approval",
  "approval_required_reason": {
    "code": "max_spend",
    "message": "The plan's maximum cost is above max_spend, so it was not run. Nothing was charged."
  },
  "plan": { "estimated_total": { "amount": 1.44, "amount_micro_usd": "1440000", "currency": "USD" } }
}

Clarify before buying

A needs_input response may contain field schemas, a natural language message, or both. Ask the person for the missing context; never fill it in by guessing. A needs_selection response offers candidates, so ask which entity they meant. When the response includes continuation, use POST /v2/asks/{id}/continue to select a candidate or supply the requested structured value on the same saved task. A paid search is not repeated. Selection resumes the remaining work under the original valid approval; a new quote created by supplied input requires an explicit /run. A natural-language clarification without continuation still requires a new clarified Ask. Inspect the earlier run’s results and usage first; do not automatically repeat a paid request. Document uploads use the App.

Statuses

`status`	Meaning	What to do
`requires_approval`	A priced plan is ready	`POST /v2/asks/{id}/run`
`running`	The plan is executing (HTTP `202`)	Poll `GET /v2/runs/{id}`
`completed`	Every step finished	Read `answer`, `results`, `usage`
`partial`	Some steps failed or were skipped	Read `errors` beside the results you did get
`needs_input`	The question is missing something	Use `continuation` for structured input, or read the clarification in `message`
`needs_selection`	Several entities match	Choose from `candidates` and continue the saved task through `/continue`
`unsupported`	No source can answer this	Nothing was charged
`failed`	The run failed (HTTP `502`)	`error` and `errors` say why; see `usage` for what was charged

Status codes

Status	Code	Meaning
200	—	A plan, or a finished run
202	—	Still running after `wait_seconds`
400	`invalid_request`	`question` empty or over 4000 characters, or `auto` without `max_spend`
401	`invalid_api_key`	See Authentication
402	`insufficient_balance` / `spend_limit_exceeded`	Nothing was charged
403	`insufficient_scope`	`ask:create`, and `ask:execute` for running
409	`idempotency_conflict` / `plan_expired` / `plan_not_ready`	Ask again for a fresh plan
422	`unsupported`	No source can answer the question
429	`rate_limit_exceeded`	Wait a minute, then retry with the same key
502	`source_error`	The run failed; read `usage` for what was charged

Buy data

Use cases

Operating it

API Reference

Ask

Discover APIs for a question

Execute the selected API

View saved annual accounts

Optional multi-source planner

Run it later

Run it immediately

Clarify before buying

Statuses

Status codes

​Discover APIs for a question

​Execute the selected API

​View saved annual accounts

​Optional multi-source planner

​Run it later

​Run it immediately

​Clarify before buying

​Statuses

​Status codes

Discover APIs for a question

Execute the selected API

View saved annual accounts

Optional multi-source planner

Run it later

Run it immediately

Clarify before buying

Statuses

Status codes