Ask an oracle

curl -X POST https://api.formalogic.io/v1/oracles/chart/ask \
  -H "Authorization: Bearer $FORMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"intent":"grouped bar chart of quarterly sales, Q1-Q4: North 120, 135, 150, 160; South 90, 110, 105, 130"}'

import os

import httpx

response = httpx.post(
    "https://api.formalogic.io/v1/oracles/chart/ask",
    headers={"Authorization": f"Bearer {os.environ['FORMA_API_KEY']}"},
    json={
        "intent": "grouped bar chart of quarterly sales, Q1-Q4: North 120, 135, 150, 160; South 90, 110, 105, 130",
    },
    timeout=120,
)
print(response.json())

const response = await fetch('https://api.formalogic.io/v1/oracles/chart/ask', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FORMA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "intent": "grouped bar chart of quarterly sales, Q1-Q4: North 120, 135, 150, 160; South 90, 110, 105, 130"
  }),
})
console.log(await response.json())

Example response

{
  "oracle": "chart",
  "format": "vega-lite",
  "status": "valid",
  "credits": 1,
  "request_id": "req_01K…",
  "result": { "$schema": "https://vega.github.io/schema/vega-lite/v6.json", "mark": "bar" },
  "verified_by": "chart@6baf09f0",
  "figure": { "drawable": true, "target": "vega-lite", "token": "v2.dmVnYS1saXRl…" },
  "data": "supplied"
}

status is a verdict, not a health check — all three arrive with HTTP 200. See Verdicts for which are billed and which are worth retrying.

Notes

A chart is drawn from the values you give. Forma does not fetch or look up data. A chart request with no values in it is refused with 422 DATA_REQUIRED before anything runs; one whose chart would need values the request does not contain is refused the same way. Neither is billed. Send "allow_generated_data": true to accept illustrative values instead. Every valid chart says which it is in data: supplied or generated. A chart with no values at all is refused even with the flag. vector-graphics and coverage-policy ignore the flag.

Ask for a view to get the answer as text as well. Send "views": ["summary"] to an oracle format that lists summary under views in List oracles, and a valid answer carries views.summary: the answer written out as plain text, built from result and nothing else. result is the same with or without it, and it costs nothing more. A view the format does not offer is refused with 422 before anything runs, naming the ones it does; nothing is billed.

valid is about the answer, not the world. It means the output passed its format's checks. It does not mean the numbers are true; data says where they came from.

A chart of a different kind is not an answer. Ask for a candlestick and get a line, and the verdict is invalid with reason: "chart_type_mismatch". Billed like any invalid. Try another format: not every format can draw every kind.

format is read from the body and from nowhere else. The API never consults an environment variable, so a request sent by curl and the same request sent by the MCP tools mean the same thing.

Allow 120 seconds. Reaching a verdict can take that long. No streaming, no polling endpoint.

One ask is one billable unit, however long it took.

There is no idempotency key. Two identical requests are two asks and two charges, and because the same intent can return a different artifact they may differ — see Determinism. If a retry must not double-charge, store the first verdict and check for it before asking again.