Skip to content

Use it

HTTP API

Every endpoint of aa serve, generated from the server's OpenAPI spec.

Start it with aa serve (default http://127.0.0.1:8080). The spec below is generated from the same Zod schemas that validate requests; fetch it live at /openapi.json.

MethodPathDoesResponses
POST/v1/jobsStart a job on uploaded files202, 400, 404, 409
GET/v1/jobsList jobs200
GET/v1/jobs/{id}Job status, current stage, progress, timings and errors200, 400, 404, 409
DELETE/v1/jobs/{id}Delete a job and its data204, 400, 404, 409
GET/v1/jobs/{id}/eventsServer-Sent Events: stage_started, stage_completed, progress, awaiting_confirmation, warning, done, failed200, 400, 404, 409
GET/v1/jobs/{id}/metricsDrafted metric definitions as YAML, and each in plain words200, 400, 404, 409
POST/v1/jobs/{id}/metricsConfirm or edit the metric definitions (YAML body); the job resumes202, 400, 404, 409
GET/v1/jobs/{id}/reportreport.json (Accept: application/json) or report.html (Accept: text/html, or ?format=html)200, 400, 404, 409
POST/v1/jobs/{id}/askAsk a follow-up question; the answer is verified claims with facts and citations200, 400, 404, 409
GET/v1/jobs/{id}/facts/{factId}Explain a number: SQL, parameters, definition and input rows200, 400, 404, 409
POST/v1/jobs/{id}/resumeContinue a failed or interrupted job from its last completed stage202, 400, 404, 409
GET/v1/healthEngine, DuckDB, model, search and Docling availability200

Example

Section titled “Example”
Terminal window
curl -F 'files[]=@examples/coffee-roaster/sales-2026.xlsx' -F 'files[]=@examples/coffee-roaster/email-0412.eml' \
  -F 'options={"currency":"USD"}' http://127.0.0.1:8080/v1/jobs
curl -N http://127.0.0.1:8080/v1/jobs/<job_id>/events      # live progress (SSE)
curl http://127.0.0.1:8080/v1/jobs/<job_id>/report?format=html > report.html

Security

Section titled “Security”
  • The API listens on 127.0.0.1 and answers only localhost host names (plus --host and AA_ALLOWED_HOSTS): a request whose Host or Origin names another host gets 403, so a web page can’t reach it through DNS rebinding.
  • API_TOKEN turns on bearer auth for /v1/jobs* and /mcp; without the token, /v1/health reports only the engine and DuckDB. aa serve refuses a non-loopback address without API_TOKEN (opt out with --allow-no-auth / AA_ALLOW_NO_AUTH=1 behind a proxy or a localhost-only port mapping). CORS is off.
  • An unexpected error is a 500 with a generic message; the details go to the server log.

The full OpenAPI document, regenerated on every docs build: openapi.json.