AI Agents API

Base path /api/ai. Every route needs a signed-in user and an active license. Agent runs also follow the administrator's AI settings: with AI agents switched off they answer 403 AGENTS_DISABLED, and with rate limiting on, too many runs answer 429 RATE_LIMITED. Errors are JSON with error (a sentence you can show) and code.

Routes

Run an agent

POST /api/ai/agents/script-review
{ "input": { "script": "DELETE FROM orders;", "connectionId": "6f1c…" } }

The ids are script-review, nl-to-sql, schema-explorer, error-diagnosis, query-optimization, auto-rollback, change-impact, release-summary, compliance and anomaly-detection. With a connectionId the agent uses that connection's engine; without one, agents that allow it need dialect, one of the engines the server supports.

Text fields are limited to 200,000 characters. A missing or invalid field is refused before anything runs:

400 { "ok": false, "error": "dialect is required when no connection is chosen: one of postgresql, mysql, …", "code": "INVALID_AGENT_INPUT" }

A finished run answers 200:

{ "ok": true,
  "result": { "riskScore": "high", "summary": "…", "findings": [ … ], "suggestedRollback": null },
  "runId": "…", "ms": 2380, "model": "…",
  "usage": { "promptTokens": 1240, "completionTokens": 380, "totalTokens": 1620 },
  "warnings": [ "1 table is left out of the AI context by an administrator's exclusion list." ],
  "cached": false }

model and usage are absent when the agent answered without the AI model. A failed run answers with ok: false, error, code and the status of the cause (see Error codes). Each agent's output is described on its page in the AI Agents guide.

Queued runs

When the administrator's async mode is Always, or it is Opt-in and you add ?async=true, the run is queued:

202 Location: /api/ai/agents/jobs/8c2e…
{ "jobId": "8c2e…", "status": "pending" }

Poll GET /api/ai/agents/jobs/:id until status is success, error or cancelled. The job carries agent, status, input, result, warnings, error_message, run_id, enqueued_at, started_at, finished_at, ms, model and cost_total_tok. GET /api/ai/agents/jobs?limit=50 lists jobs without their input and result. DELETE cancels a job that is pending or running; a job that has finished answers 404 JOB_NOT_FOUND. A job left running for 10 minutes, for example after a restart, is queued again.

Users see and cancel only their own jobs; administrators see all. Someone else's job, or an id that is not a UUID, answers 404 JOB_NOT_FOUND.

Run history

GET /api/ai/agents/script-review/runs?limit=50
{ "runs": [ { "id": "…", "agent": "script-review", "status": "success", "user_email": "dba@example.com",
              "model": "…", "input_summary": "dialect=postgresql, 412c, schema=yes", "output_summary": "risk=high, findings=4",
              "cost_total_tok": 1820, "ms": 2380, "error_message": null, "created_at": "…" } ] }

limit is 1 to 500, default 50. Besides the ten agents, ide-chat, review-script and blast-radius-narrative have run history. Users see their own runs; administrators see everyone's. Prompts and answers are not stored.

Status and providers

GET /api/ai/status
{ "configured": true, "provider": "anthropic", "model": "…" }

Administrators also get endpoint. GET /api/ai/providers lists each provider's id, label, defaultModel, requiresApiKey and requiresEndpoint.

Settings

GET /api/ai/settings gives other users provider, model, apiKeySet and scriptReviewMode. Administrators also get endpoint, apiVersion, deployment, region, projectId, awsRoleArn, awsAccessKeyIdSet, awsSecretAccessKeySet, awsSessionTokenSet, extraHeaders (names with the value [stored]), maxTokens, temperature, timeoutMs and agents. Keys are never returned.

PUT /api/ai/settings
{ "provider": "anthropic", "apiKey": "…", "model": "…", "temperature": 0.2,
  "extraHeaders": { "X-Team": "[stored]", "X-Gateway": "eu-1" },
  "agents": { "globalEnabled": true, "schemaDetailLevel": "types", "excludedTables": "hr.salaries, payroll",
              "sendRowData": false, "schemaTableCap": 0, "rateLimitEnabled": true, "rateLimitPerMinute": 30,
              "cacheEnabled": false, "cacheTtlSeconds": 300, "asyncMode": "opt-in" } }

Send only the fields you change. An empty or missing apiKey, awsAccessKeyId, awsSecretAccessKey or awsSessionToken keeps the stored value; a header sent as [stored] keeps its value and a header left out is removed. Secrets are encrypted before they are stored. This is the only way to change AI settings: the general settings API refuses ai_ and agents_ keys with 400 USE_AI_SETTINGS. Invalid values are refused, naming every problem:

400 { "error": "temperature must be a number from 0 to 2; agents.asyncMode must be off, opt-in, always", "code": "INVALID_AI_SETTINGS" }

IDE and approval requests

They follow the same settings as the agents, are recorded in the run history, and answer failures with success: false, error, code and the status below.

Error codes