Ask a question

curl -X POST https://api.avina.io/v1/ask \
  -H "Authorization: Bearer $AVINA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "question": "What does this company sell, and who does it sell to?",
    "about": { "company_domain": "northwindpay.example" },
    "max_credits": 1
  }'

import os
import uuid
import requests

response = requests.post(
    "https://api.avina.io/v1/ask",
    headers={
        "Authorization": f"Bearer {os.environ['AVINA_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "question": "What does this company sell, and who does it sell to?",
        "about": {"company_domain": "northwindpay.example"},
        "max_credits": 1,
    },
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.avina.io/v1/ask", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AVINA_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    question: "What does this company sell, and who does it sell to?",
    about: { company_domain: "northwindpay.example" },
    max_credits: 1,
  }),
});
const data = await response.json();
console.log(data);

{
  "object": "answer",
  "id": "9b2f6c1e-4d7a-4b0e-8f3a-2c5d1e7a9b04",
  "status": "queued",
  "question": "What does this company sell, and who does it sell to?",
  "about": { "company_domain": "northwindpay.example" },
  "outcome": null,
  "answer": null,
  "data": null,
  "citations": [],
  "credits_charged": 0,
  "error": null,
  "created_at": "2026-11-12T17:20:03Z",
  "completed_at": null,
  "url": "https://api.avina.io/v1/ask/9b2f6c1e-4d7a-4b0e-8f3a-2c5d1e7a9b04"
}

curl -X POST https://api.avina.io/v1/ask \
  -H "Authorization: Bearer $AVINA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "question": "What does this company sell, and who does it sell to?",
    "about": { "company_domain": "northwindpay.example" },
    "max_credits": 1
  }'

import os
import uuid
import requests

response = requests.post(
    "https://api.avina.io/v1/ask",
    headers={
        "Authorization": f"Bearer {os.environ['AVINA_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "question": "What does this company sell, and who does it sell to?",
        "about": {"company_domain": "northwindpay.example"},
        "max_credits": 1,
    },
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.avina.io/v1/ask", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AVINA_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    question: "What does this company sell, and who does it sell to?",
    about: { company_domain: "northwindpay.example" },
    max_credits: 1,
  }),
});
const data = await response.json();
console.log(data);

{
  "object": "answer",
  "id": "9b2f6c1e-4d7a-4b0e-8f3a-2c5d1e7a9b04",
  "status": "queued",
  "question": "What does this company sell, and who does it sell to?",
  "about": { "company_domain": "northwindpay.example" },
  "outcome": null,
  "answer": null,
  "data": null,
  "citations": [],
  "credits_charged": 0,
  "error": null,
  "created_at": "2026-11-12T17:20:03Z",
  "completed_at": null,
  "url": "https://api.avina.io/v1/ask/9b2f6c1e-4d7a-4b0e-8f3a-2c5d1e7a9b04"
}

Coming Soon. Ask is not available yet, and these endpoints are not live. This page is the planned contract, published early so you can design against it. Fields can change before release. Ask is not part of the OpenAPI specification until then.

Ask takes a question in plain language and returns a direct answer. Every factual claim in the answer carries a numbered citation, and when the evidence does not support an answer, the response says so instead of guessing. Like a search, a question is answered in the background. POST /ask returns 202 with an id. Poll GET /ask/{ask_id} until status is completed or failed.

Asking a question spends credits for the research it needs, at provider cost plus the 5% platform fee. Set max_credits to cap it. Reading an answer is free. See Pricing.

Headers

string

A unique string for this request, 1 to 255 characters. Retrying with the same key and body returns the original response instead of asking again.

Body

string

required

The question, in plain language. Ask one thing at a time for the clearest answer.Maximum 1,000 characters.

object

Limits the question to one company or one person. Send exactly one of the two fields. Without about, the question is answered from across the data network, which suits market questions.

Show properties

string

The company’s website domain, such as northwindpay.example.

string

The person’s LinkedIn profile URL.

object

A JSON Schema describing the shape you want the answer in. When you send one, the response also carries data, an object that matches the schema. Useful when code or an AI agent will read the answer. A field the evidence cannot fill is null.

number

The most credits this question may spend. 1 credit = $1.00. When the limit is reached, research stops and the answer is written from what was found.

Response

202 The question was accepted. The same object is returned by GET /ask/{ask_id}.

string

required

Always answer.

string

required

The answer’s identifier. Use it to read the answer.

string

required

queued and running are in progress. completed and failed are final.

string

required

The question as you sent it.

object | null

required

The company or person the question was limited to, or null.

string | null

required

How well the question could be answered. null until status is completed.

answered: the evidence supports a full answer.
partially_answered: part of the question could be answered. answer says which part could not.
insufficient_evidence: no reliable answer was found. answer explains what was missing.

string | null

required

The answer, in Markdown. Citations appear as numbered markers such as [1], each matching an entry in citations. null until status is completed.

object | null

required

The answer in the shape of your output_schema. null when you did not send one.

object[]

required

The sources the answer relies on, in the order they are first cited.

Show item properties

integer

required

The marker used in answer, starting at 1.

string | null

required

The source page. null when the source is a data record with no public page.

string

required

The page title, or a short description of the data record.

string | null

The passage that supports the claim, quoted from the source.

string | null

When the source was published, when known.

number

required

Credits charged for this question so far. Final once status is completed or failed.

string | null

required

A message when status is failed.

string

required

When the question was asked.

string | null

required

When the answer was finished.

string

required

The URL to read this answer from.

Get an answer

GET /ask/{ask_id} returns the same answer object. Poll it every 2 seconds, slowing to every 10, until status is completed or failed. Reading an answer is free.

string

required

The answer’s id, returned when the question was asked.

cURL

curl https://api.avina.io/v1/ask/$ASK_ID \
  -H "Authorization: Bearer $AVINA_API_KEY"

200 (completed)

{
  "object": "answer",
  "id": "9b2f6c1e-4d7a-4b0e-8f3a-2c5d1e7a9b04",
  "status": "completed",
  "question": "What does this company sell, and who does it sell to?",
  "about": { "company_domain": "northwindpay.example" },
  "outcome": "answered",
  "answer": "Northwind Pay sells payments infrastructure for lenders: APIs for sending loan funds and collecting repayments [1]. Its customers are mid-market consumer and small-business lenders in the US [1][2].",
  "data": null,
  "citations": [
    {
      "number": 1,
      "url": "https://northwindpay.example/product",
      "title": "Product | Northwind Pay",
      "quote": "Disburse loans and collect repayments through one API.",
      "published_at": null
    },
    {
      "number": 2,
      "url": "https://northwindpay.example/customers",
      "title": "Customers | Northwind Pay",
      "quote": "Trusted by mid-market lenders across the United States.",
      "published_at": "2026-09-14"
    }
  ],
  "credits_charged": 0.21,
  "error": null,
  "created_at": "2026-11-12T17:20:03Z",
  "completed_at": "2026-11-12T17:20:41Z",
  "url": "https://api.avina.io/v1/ask/9b2f6c1e-4d7a-4b0e-8f3a-2c5d1e7a9b04"
}

When the evidence is not there, the answer says so:

200 (insufficient evidence, shortened)

{
  "object": "answer",
  "status": "completed",
  "outcome": "insufficient_evidence",
  "answer": "No public source states Northwind Pay's annual revenue. The company is privately held and has not published financial results.",
  "citations": []
}

Errors

Status	Code	When
`400`	`invalid_request`	The request is invalid, for example a missing `question` or both fields set in `about`.
`401`	`invalid_api_key`	The API key is missing, invalid or revoked.
`402`	`usage_limit_reached`	The workspace has no credits left. Nothing was started or charged.
`404`	`not_found`	No answer with that `id` in this workspace.
`409`	`idempotency_key_reused`	The `Idempotency-Key` was already used with a different request.
`429`	`rate_limited`	Too many requests. Retry after `Retry-After` seconds.

Every error uses the same shape. See Errors.

The company, answer and credit figures in these examples are illustrative.

curl -X POST https://api.avina.io/v1/ask \
  -H "Authorization: Bearer $AVINA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "question": "What does this company sell, and who does it sell to?",
    "about": { "company_domain": "northwindpay.example" },
    "max_credits": 1
  }'

import os
import uuid
import requests

response = requests.post(
    "https://api.avina.io/v1/ask",
    headers={
        "Authorization": f"Bearer {os.environ['AVINA_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "question": "What does this company sell, and who does it sell to?",
        "about": {"company_domain": "northwindpay.example"},
        "max_credits": 1,
    },
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.avina.io/v1/ask", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AVINA_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    question: "What does this company sell, and who does it sell to?",
    about: { company_domain: "northwindpay.example" },
    max_credits: 1,
  }),
});
const data = await response.json();
console.log(data);

{
  "object": "answer",
  "id": "9b2f6c1e-4d7a-4b0e-8f3a-2c5d1e7a9b04",
  "status": "queued",
  "question": "What does this company sell, and who does it sell to?",
  "about": { "company_domain": "northwindpay.example" },
  "outcome": null,
  "answer": null,
  "data": null,
  "citations": [],
  "credits_charged": 0,
  "error": null,
  "created_at": "2026-11-12T17:20:03Z",
  "completed_at": null,
  "url": "https://api.avina.io/v1/ask/9b2f6c1e-4d7a-4b0e-8f3a-2c5d1e7a9b04"
}

Overview

Companies

People

Parse

Personas

Account

Coming Soon

Headers

Body

Response

Get an answer

Errors

​Headers

​Body

​Response

​Get an answer

​Errors

Headers

Body

Response

Get an answer

Errors