AI for Database API reference for agents
A REST and OpenAPI data layer for discovering database structure, returning raw query results, and creating guarded database workflows.
- API base
https://app.aifordatabase.com/api/v1- Authentication
Authorization: Bearer afd_...- Canonical contract
- https://app.aifordatabase.com/api/v1/openapi.json
- Last verified
If this page disagrees with the OpenAPI document, the OpenAPI document is authoritative.
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.
Authentication and scopes
Generate an API key in the application settings. Keys use one afd_ prefix; there are no live or test key variants. Use the narrowest scopes necessary.
| Scope | Purpose |
|---|---|
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 |
Workflow credential operations require both the workflow_credentials scope and an organization admin role.
Endpoint catalog
Connections and queries
Relevant scope: connections / query
| Method | Path | Behavior | External side effect |
|---|---|---|---|
| GET / POST | /api/v1/connections | List sanitized connections or create one | None beyond stated resource mutation |
| GET / PATCH / DELETE | /api/v1/connections/{id} | Read, update, or remove a connection | None beyond stated resource mutation |
| POST | /api/v1/connections/{id}/test | Test connectivity and introspect on first success | None beyond stated resource mutation |
| GET / POST | /api/v1/connections/{id}/schema | Read cached schema or introspect now | None beyond stated resource mutation |
| POST | /api/v1/connections/{id}/query | Execute SQL and return raw columns and rows | None beyond stated resource mutation |
| GET / POST | /api/v1/connections/{id}/annotations | List or add schema context | None beyond stated resource mutation |
| PATCH / DELETE | /api/v1/connections/{id}/annotations/{annotationId} | Update or remove an annotation | None beyond stated resource mutation |
| POST | /api/v1/connections/{id}/annotations/auto | Generate schema annotations | None beyond stated resource mutation |
Chat and conversations
Relevant scope: chat
| Method | Path | Behavior | External side effect |
|---|---|---|---|
| POST | /api/v1/chat | Ask in natural language and receive generated SQL and results | None beyond stated resource mutation |
| GET / POST | /api/v1/conversations | List or create conversations | None beyond stated resource mutation |
| GET / PATCH / DELETE | /api/v1/conversations/{id} | Manage one conversation | None beyond stated resource mutation |
| GET | /api/v1/conversations/{id}/messages | Read conversation messages | None beyond stated resource mutation |
Dashboards
Relevant scope: dashboards
| Method | Path | Behavior | External side effect |
|---|---|---|---|
| GET / POST | /api/v1/dashboards | List or create dashboards | None beyond stated resource mutation |
| GET / PATCH / DELETE | /api/v1/dashboards/{id} | Manage one dashboard | None beyond stated resource mutation |
| GET / POST | /api/v1/dashboards/{id}/widgets | List or add widgets | None beyond stated resource mutation |
| PATCH / DELETE | /api/v1/dashboards/{id}/widgets/{widgetId} | Update or remove a widget | None beyond stated resource mutation |
| GET | /api/v1/dashboards/{id}/widgets/{widgetId}/data | Read current widget data | None beyond stated resource mutation |
Workflows
Relevant scope: workflows / workflow_credentials
| Method | Path | Behavior | External side effect |
|---|---|---|---|
| GET / POST | /api/v1/workflows | List workflows or create a paused draft | POST creates state but does not schedule it |
| GET / PATCH / DELETE | /api/v1/workflows/{id} | Read, revise, publish, pause, or delete | PATCH with isActive=true publishes |
| POST | /api/v1/workflows/{id}/preview | Run draft queries only; no delivery or persisted run | None beyond stated resource mutation |
| POST | /api/v1/workflows/{id}/actions/{order}/test | Send one explicitly confirmed live action test | Real external delivery |
| POST | /api/v1/workflows/{id}/run | Run the current draft including actions | Real external delivery |
| GET | /api/v1/workflows/{id}/runs | Inspect paginated execution history | None beyond stated resource mutation |
| GET / POST | /api/v1/workflow-credentials | List safe metadata or create an encrypted credential | None beyond stated resource mutation |
| GET / PATCH / DELETE | /api/v1/workflow-credentials/{id} | Read metadata, rotate, or safely delete a credential | None beyond stated resource mutation |
Saved queries, metrics, and approval
Relevant scope: query
| Method | Path | Behavior | External side effect |
|---|---|---|---|
| GET / POST | /api/v1/saved-queries | List or create saved queries | None beyond stated resource mutation |
| GET / PATCH / DELETE | /api/v1/saved-queries/{id} | Manage a saved query | None beyond stated resource mutation |
| POST | /api/v1/saved-queries/{id}/run | Run a saved query with parameters | None beyond stated resource mutation |
| GET / POST | /api/v1/metrics | List or define metrics | None beyond stated resource mutation |
| GET / PATCH / DELETE | /api/v1/metrics/{id} | Manage a metric definition | None beyond stated resource mutation |
| GET | /api/v1/metrics/{id}/value | Evaluate a metric now | None beyond stated resource mutation |
| GET / POST | /api/v1/approval-rules | List or create approval rules | None beyond stated resource mutation |
| GET / PATCH / DELETE | /api/v1/approval-rules/{id} | Manage an approval rule | None beyond stated resource mutation |
| POST | /api/v1/queries/submit | Submit a query for approval | None beyond stated resource mutation |
| GET | /api/v1/queries/pending | List pending queries | None beyond stated resource mutation |
| GET | /api/v1/queries/{id}/status | Read approval status | None beyond stated resource mutation |
| POST | /api/v1/queries/{id}/approve | Approve a pending query | None beyond stated resource mutation |
| POST | /api/v1/queries/{id}/reject | Reject a pending query | None beyond stated resource mutation |
Webhooks, usage, and keys
Relevant scope: webhooks / usage / admin
| Method | Path | Behavior | External side effect |
|---|---|---|---|
| GET / POST | /api/v1/webhooks | List or create signed event endpoints | None beyond stated resource mutation |
| GET / PATCH / DELETE | /api/v1/webhooks/{id} | Manage one event endpoint | None beyond stated resource mutation |
| GET | /api/v1/webhooks/{id}/deliveries | Inspect delivery history | None beyond stated resource mutation |
| POST | /api/v1/webhooks/{id}/test | Send a test event | Real external delivery |
| GET | /api/v1/usage | Read usage records | None beyond stated resource mutation |
| GET | /api/v1/usage/budget | Read budget status | None beyond stated resource mutation |
| GET / POST | /api/v1/keys | List or create API keys | None beyond stated resource mutation |
| DELETE | /api/v1/keys/{id} | Revoke an API key | None beyond stated resource mutation |
Response envelope and pagination
{
"data": {},
"error": null,
"meta": {
"requestId": "uuid",
"timestamp": "ISO-8601",
"pagination": {
"total": 0,
"page": 1,
"pageSize": 20,
"totalPages": 0
}
}
}Pagination is page-based with page and pageSize. On errors, data is null and error contains a stable code, message, and optional details.
Safety and delivery 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.
Webhook actions accept explicit successStatusCodes. Use this when a destination distinguishes full acceptance from partial acceptance, such as HTTP 202 versus 207.
Minimal raw-query example
curl -X POST https://app.aifordatabase.com/api/v1/connections/CONNECTION_ID/query -H "Authorization: Bearer afd_your_key" -H "Content-Type: application/json" -d '{"sql":"SELECT id, email FROM users LIMIT 5"}'Errors and retries
400: malformed body or validation failure.401: missing, invalid, or expired API key.403: missing scope or required admin role.422: connection, preview, or action-test execution failed.428: draft revision or explicit delivery confirmation required.429: rate limited; retry with backoff.5xx: transient service error; retry idempotent reads with backoff.
Do not automatically retry live action tests, manual workflow runs, or other delivery operations unless your integration can prove the first attempt did not reach the destination.