API reference

AI query

Ask a financial question in natural language and get an answer with any structured data the engine retrieved.

Ask a question

POST/api/v1/ai/query

API keyscope ai:query

Send a question in plain English. The query engine decides which data sources to call, retrieves the data and writes an answer. Integrations you have connected to your ENTON account (API keys and OAuth brokers) are passed to the engine as context.

Request

JSON body

Field	Description
`query`stringrequired	The question, up to 2,000 characters.up to 2000 characters
`stream`boolean	Leave false. Streaming is not implemented; see the notes below.default false
`mode`string	Accepted and echoed back in metadata.mode. It does not currently change how the query is answered.default "vector-db"

Response

200 The answer, with any structured data the engine retrieved.

Field	Description
`answer`object	The engine result. Read answer.summary for the text.
`answer.summary`string	The answer as text.
`answer.__textResponse`string	The answer text as the engine produced it. Usually equal to summary.
`answer.conversationOnly`boolean	True when the engine answered without retrieving data, for example when it needs a clarification.
`answer.displayData`object	Structured data behind the answer (quotes, bars, news). Absent when none was retrieved.
`metadata`object	Request metadata.
`metadata.responseTime`integer	Milliseconds this request took, measured by the API.
`metadata.cacheHit`boolean	Reserved. Currently always false.
`metadata.providersUsed`array of string	Reserved. Currently always empty.
`metadata.mode`string	The mode you sent, or "vector-db".
`metadata.tokensUsed`integer	Reserved. Currently always 0.
`query`string	Your question, echoed.

Example response

{
  "answer": {
    "summary": "Apple (AAPL) last traded at ...",
    "__textResponse": "Apple (AAPL) last traded at ...",
    "conversationOnly": false,
    "displayData": {
      "type": "quote",
      "symbol": "AAPL"
    }
  },
  "metadata": {
    "responseTime": 2140,
    "cacheHit": false,
    "providersUsed": [],
    "mode": "vector-db",
    "tokensUsed": 0
  },
  "query": "What is the AAPL price?"
}

Errors

Status	When	error
403	The key has neither "ai:query" nor "*".	`Insufficient permissions. Required scope: ai:query`
400	query is missing or empty.	`Missing required field: query`
400	query is over 2,000 characters.	`Query too long. Maximum length is 2000 characters`
500	The engine failed, or the body was not valid JSON. An engine error can also arrive with its own message.	`Failed to process query. Please try again.`

Errors use the standard error body. Any request can also get the authentication errors (401) and the rate-limit error (429).

Examples

curl -X POST "https://enton.ai/api/v1/ai/query" \
  -H "Authorization: Bearer $ENTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is Tesla doing today? Show news and price."
  }'

Notes

answer is an object, not a string. The text is in answer.summary.
With "stream": true the API returns the same JSON document with Content-Type: text/event-stream and status 200, even when the query failed. Leave stream false.
Answers can take several seconds. Set a client timeout of at least 60 seconds.