Ask Endpoint

POST /ask

Plan tool calls over the governed read surface, execute them under the as-of/trust gate, and synthesize a cited answer through the shared Corpus API runtime.

Category: Search

Authentication

Send the provisioned API key in the X-API-KEY header.

Required scopes: rag:search.

Also requires at least one of: us:read, india:read.

Cross-jurisdiction requests require both jurisdiction scopes.

Request

This operation has no path, query, header, or cookie parameters.

Request body

Content type: application/json. Required: yes. Schema: AskRequest.

{
  "q": "string",
  "as_of": "2025-12-31T23:59:59Z",
  "market": "US"
}

Example request

curl --request POST \
  --url 'https://corpus-api.onera.app/ask' \
  --header "X-API-KEY: ${CORPUS_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
  "q": "string",
  "as_of": "2025-12-31T23:59:59Z",
  "market": "US"
}'

Responses

Status	Description	Content type	Schema
200	Successful Response	application/json	AskResponse
400	Invalid parameter combination	application/json	ErrorResponse
401	Missing or invalid API key	application/json	ErrorResponse
403	Insufficient jurisdiction or scope	application/json	ErrorResponse
404	Unknown resource	application/json	ErrorResponse
422	Request schema validation failed	application/json	ErrorResponse
429	Rate limit exceeded	application/json	ErrorResponse
503	Source content is unavailable or still processing	application/json	ErrorResponse

Representative 200 response

{
  "answer": "string",
  "planner": "llm",
  "as_of": "2025-12-31T23:59:59Z",
  "steps": [
    {}
  ],
  "data": [
    {}
  ],
  "citations": [
    {}
  ],
  "model": "string",
  "note": "string"
}