# AI for Database complete agent reference

AI for Database is a data layer for AI agents and business users. It connects to operational databases, answers natural-language questions, returns raw query results, creates dashboards, and runs scheduled database workflows.

## Canonical contract

- API base: https://app.aifordatabase.com/api/v1
- OpenAPI 3.1: https://app.aifordatabase.com/api/v1/openapi.json
- Interactive reference: https://app.aifordatabase.com/api/v1/docs
- JSON agent manifest: https://aifordatabase.com/api/agents
- Machine-readable HTML: https://aifordatabase.com/for-agents/

When any prose conflicts with OpenAPI, OpenAPI wins.

## Authentication

Send `Authorization: Bearer afd_...`. API keys are organization-scoped and permission-scoped. There are no `afdb_live_` or `afdb_test_` key variants.

- `query`: Direct SQL, saved-query runs, and query approval
- `chat`: Natural-language questions and generated SQL
- `connections`: Sanitized connections, schemas, health, and annotations
- `dashboards`: Dashboards, widgets, and widget data
- `workflows`: Workflow drafts, previews, tests, publishing, and runs
- `workflow_credentials`: Encrypted outbound credentials; admin role also required
- `usage`: Usage records and budget status
- `webhooks`: Signed event endpoints, tests, and deliveries
- `admin`: API-key management and administrative operations

## Standard response envelope

Every v1 response contains `data`, `error`, and `meta`. Metadata includes a request ID and timestamp; list endpoints can add page-based pagination with `total`, `page`, `pageSize`, and `totalPages`.

## Recommended agent lifecycle

01. Discover: List sanitized connections, health state, and cached schemas.
02. Validate: Run read-only SQL and inspect raw columns, rows, count, and timing.
03. Draft: Create a paused workflow and reference a write-only outbound credential.
04. Preview: Execute draft queries without contacting external systems.
05. Test: Explicitly confirm one live action and inspect its sanitized attempts.
06. Publish: Activate an immutable version, then inspect scheduled run history.

## Safety boundaries

- Connection reads never return database passwords or stored platform secrets.
- Workflow credentials are encrypted, write-only, and restricted to allowed destination hosts.
- New workflows are paused drafts; creation alone never schedules delivery.
- Preview executes queries only and never creates a delivery or workflow run.
- Action tests require confirmDelivery=true because they contact the destination.
- Manual workflow runs have real side effects; published schedules use an immutable version.

## Endpoint catalog

### Connections and queries

Required area: `connections / query`

- GET / POST `/api/v1/connections`: List sanitized connections or create one
- GET / PATCH / DELETE `/api/v1/connections/{id}`: Read, update, or remove a connection
- POST `/api/v1/connections/{id}/test`: Test connectivity and introspect on first success
- GET / POST `/api/v1/connections/{id}/schema`: Read cached schema or introspect now
- POST `/api/v1/connections/{id}/query`: Execute SQL and return raw columns and rows
- GET / POST `/api/v1/connections/{id}/annotations`: List or add schema context
- PATCH / DELETE `/api/v1/connections/{id}/annotations/{annotationId}`: Update or remove an annotation
- POST `/api/v1/connections/{id}/annotations/auto`: Generate schema annotations

### Chat and conversations

Required area: `chat`

- POST `/api/v1/chat`: Ask in natural language and receive generated SQL and results
- GET / POST `/api/v1/conversations`: List or create conversations
- GET / PATCH / DELETE `/api/v1/conversations/{id}`: Manage one conversation
- GET `/api/v1/conversations/{id}/messages`: Read conversation messages

### Dashboards

Required area: `dashboards`

- GET / POST `/api/v1/dashboards`: List or create dashboards
- GET / PATCH / DELETE `/api/v1/dashboards/{id}`: Manage one dashboard
- GET / POST `/api/v1/dashboards/{id}/widgets`: List or add widgets
- PATCH / DELETE `/api/v1/dashboards/{id}/widgets/{widgetId}`: Update or remove a widget
- GET `/api/v1/dashboards/{id}/widgets/{widgetId}/data`: Read current widget data

### Workflows

Required area: `workflows / workflow_credentials`

- GET / POST `/api/v1/workflows`: List workflows or create a paused draft Side effect: POST creates state but does not schedule it.
- GET / PATCH / DELETE `/api/v1/workflows/{id}`: Read, revise, publish, pause, or delete Side effect: PATCH with isActive=true publishes.
- POST `/api/v1/workflows/{id}/preview`: Run draft queries only; no delivery or persisted run
- POST `/api/v1/workflows/{id}/actions/{order}/test`: Send one explicitly confirmed live action test Side effect: Real external delivery.
- POST `/api/v1/workflows/{id}/run`: Run the current draft including actions Side effect: Real external delivery.
- GET `/api/v1/workflows/{id}/runs`: Inspect paginated execution history
- GET / POST `/api/v1/workflow-credentials`: List safe metadata or create an encrypted credential
- GET / PATCH / DELETE `/api/v1/workflow-credentials/{id}`: Read metadata, rotate, or safely delete a credential

### Saved queries, metrics, and approval

Required area: `query`

- GET / POST `/api/v1/saved-queries`: List or create saved queries
- GET / PATCH / DELETE `/api/v1/saved-queries/{id}`: Manage a saved query
- POST `/api/v1/saved-queries/{id}/run`: Run a saved query with parameters
- GET / POST `/api/v1/metrics`: List or define metrics
- GET / PATCH / DELETE `/api/v1/metrics/{id}`: Manage a metric definition
- GET `/api/v1/metrics/{id}/value`: Evaluate a metric now
- GET / POST `/api/v1/approval-rules`: List or create approval rules
- GET / PATCH / DELETE `/api/v1/approval-rules/{id}`: Manage an approval rule
- POST `/api/v1/queries/submit`: Submit a query for approval
- GET `/api/v1/queries/pending`: List pending queries
- GET `/api/v1/queries/{id}/status`: Read approval status
- POST `/api/v1/queries/{id}/approve`: Approve a pending query
- POST `/api/v1/queries/{id}/reject`: Reject a pending query

### Webhooks, usage, and keys

Required area: `webhooks / usage / admin`

- GET / POST `/api/v1/webhooks`: List or create signed event endpoints
- GET / PATCH / DELETE `/api/v1/webhooks/{id}`: Manage one event endpoint
- GET `/api/v1/webhooks/{id}/deliveries`: Inspect delivery history
- POST `/api/v1/webhooks/{id}/test`: Send a test event Side effect: Real external delivery.
- GET `/api/v1/usage`: Read usage records
- GET `/api/v1/usage/budget`: Read budget status
- GET / POST `/api/v1/keys`: List or create API keys
- DELETE `/api/v1/keys/{id}`: Revoke an API key

## Connection behavior

Connection reads are sanitized. They expose metadata, health, schema state, and structured failure diagnosis, but never database passwords or stored platform secrets. Create a connection, then call `POST /api/v1/connections/{id}/test`; the first successful test also introspects and caches the schema. The cloud service runs on dynamic serverless egress IPs, so integrations must not assume one stable allowlist IP.

Supported public connection types are `POSTGRES`, `MYSQL`, `MARIADB`, `MSSQL`, `MONGODB`, and `SQLITE`.

## Workflow behavior

Creating a workflow produces a paused draft. Draft edits use `expectedDraftRevision` for optimistic concurrency. Preview runs only source queries and never contacts the action destination. A live action test requires `{"confirmDelivery":true}`. Manual runs execute actions and therefore have real side effects. Publishing with `isActive:true` validates and activates an immutable production version.

Outbound authentication belongs in a workflow credential, not inline headers. Workflow credentials are encrypted, write-only, bound to allowed hosts, and require both admin role and the `workflow_credentials` API scope.

## Errors and retries

- 400: malformed input or validation failure.
- 401: missing, invalid, or expired key.
- 403: insufficient scope or admin role.
- 404: resource not found in the authenticated organization.
- 422: connection, preview, or live action execution failed.
- 428: draft revision or explicit delivery confirmation required.
- 429: rate limited.
- 5xx: unexpected or transient service error.

Retry reads with exponential backoff after 429 or transient 5xx responses. Do not blindly retry action tests, manual workflow runs, credential rotations, or other operations with delivery side effects.

## Implementation guides

- API overview: https://aifordatabase.com/docs/api-overview/
- Authentication: https://aifordatabase.com/docs/authentication/
- Endpoint reference: https://aifordatabase.com/docs/endpoints/
- Querying: https://aifordatabase.com/docs/agent-querying-databases/
- Workflow lifecycle: https://aifordatabase.com/docs/agent-workflow-lifecycle/
- Outbound credentials: https://aifordatabase.com/docs/outbound-credentials/
- Errors and retries: https://aifordatabase.com/docs/api-errors-and-retries/
- Scheduled alert tutorial: https://aifordatabase.com/docs/agent-created-alerts/

## Product positioning

AI for Database supports three product workflows: Ask questions against live data, Build dashboards and metrics, and Act through scheduled queries and authenticated webhook actions. It can be used in the browser by non-technical teams or through REST/OpenAPI by applications and agents.

Official site: https://aifordatabase.com/
Contact: hello@aifordatabase.com
Last verified: 2026-08-04