{"schema_version":"1.0","name":"AI for Database","description":"REST and OpenAPI data layer for agents to inspect database structure, return raw results, and safely automate data-driven actions.","last_verified":"2026-08-04","canonical_contract":"https://app.aifordatabase.com/api/v1/openapi.json","api":{"base_url":"https://app.aifordatabase.com/api/v1","interactive_docs_url":"https://app.aifordatabase.com/api/v1/docs","response_envelope":{"data":"object | array | null","error":"null | { code, message, details? }","meta":"{ requestId, timestamp, pagination? }"},"pagination":{"type":"page","parameters":["page","pageSize"]}},"authentication":{"type":"http_bearer","header":"Authorization","format":"Bearer afd_...","scopes":[{"name":"query","purpose":"Direct SQL, saved-query runs, and query approval"},{"name":"chat","purpose":"Natural-language questions and generated SQL"},{"name":"connections","purpose":"Sanitized connections, schemas, health, and annotations"},{"name":"dashboards","purpose":"Dashboards, widgets, and widget data"},{"name":"workflows","purpose":"Workflow drafts, previews, tests, publishing, and runs"},{"name":"workflow_credentials","purpose":"Encrypted outbound credentials; admin role also required"},{"name":"usage","purpose":"Usage records and budget status"},{"name":"webhooks","purpose":"Signed event endpoints, tests, and deliveries"},{"name":"admin","purpose":"API-key management and administrative operations"}],"notes":["Use the narrowest scopes needed.","workflow_credentials operations also require an organization admin role.","API keys and outbound workflow credentials are separate secrets."]},"capabilities":["sanitized_connection_discovery","schema_introspection","natural_language_query","raw_sql_results","dashboards_and_widgets","saved_queries_and_metrics","query_approval","paused_workflow_drafts","query_only_workflow_preview","encrypted_destination_bound_credentials","explicit_live_action_testing","immutable_workflow_publishing","workflow_run_inspection","signed_event_webhooks"],"recommended_lifecycle":[{"step":"01","title":"Discover","description":"List sanitized connections, health state, and cached schemas."},{"step":"02","title":"Validate","description":"Run read-only SQL and inspect raw columns, rows, count, and timing."},{"step":"03","title":"Draft","description":"Create a paused workflow and reference a write-only outbound credential."},{"step":"04","title":"Preview","description":"Execute draft queries without contacting external systems."},{"step":"05","title":"Test","description":"Explicitly confirm one live action and inspect its sanitized attempts."},{"step":"06","title":"Publish","description":"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_groups":[{"name":"Connections and queries","relevant_scope":"connections / query","endpoints":[{"method":"GET / POST","path":"/api/v1/connections","description":"List sanitized connections or create one"},{"method":"GET / PATCH / DELETE","path":"/api/v1/connections/{id}","description":"Read, update, or remove a connection"},{"method":"POST","path":"/api/v1/connections/{id}/test","description":"Test connectivity and introspect on first success"},{"method":"GET / POST","path":"/api/v1/connections/{id}/schema","description":"Read cached schema or introspect now"},{"method":"POST","path":"/api/v1/connections/{id}/query","description":"Execute SQL and return raw columns and rows"},{"method":"GET / POST","path":"/api/v1/connections/{id}/annotations","description":"List or add schema context"},{"method":"PATCH / DELETE","path":"/api/v1/connections/{id}/annotations/{annotationId}","description":"Update or remove an annotation"},{"method":"POST","path":"/api/v1/connections/{id}/annotations/auto","description":"Generate schema annotations"}]},{"name":"Chat and conversations","relevant_scope":"chat","endpoints":[{"method":"POST","path":"/api/v1/chat","description":"Ask in natural language and receive generated SQL and results"},{"method":"GET / POST","path":"/api/v1/conversations","description":"List or create conversations"},{"method":"GET / PATCH / DELETE","path":"/api/v1/conversations/{id}","description":"Manage one conversation"},{"method":"GET","path":"/api/v1/conversations/{id}/messages","description":"Read conversation messages"}]},{"name":"Dashboards","relevant_scope":"dashboards","endpoints":[{"method":"GET / POST","path":"/api/v1/dashboards","description":"List or create dashboards"},{"method":"GET / PATCH / DELETE","path":"/api/v1/dashboards/{id}","description":"Manage one dashboard"},{"method":"GET / POST","path":"/api/v1/dashboards/{id}/widgets","description":"List or add widgets"},{"method":"PATCH / DELETE","path":"/api/v1/dashboards/{id}/widgets/{widgetId}","description":"Update or remove a widget"},{"method":"GET","path":"/api/v1/dashboards/{id}/widgets/{widgetId}/data","description":"Read current widget data"}]},{"name":"Workflows","relevant_scope":"workflows / workflow_credentials","endpoints":[{"method":"GET / POST","path":"/api/v1/workflows","description":"List workflows or create a paused draft","sideEffect":"POST creates state but does not schedule it"},{"method":"GET / PATCH / DELETE","path":"/api/v1/workflows/{id}","description":"Read, revise, publish, pause, or delete","sideEffect":"PATCH with isActive=true publishes"},{"method":"POST","path":"/api/v1/workflows/{id}/preview","description":"Run draft queries only; no delivery or persisted run"},{"method":"POST","path":"/api/v1/workflows/{id}/actions/{order}/test","description":"Send one explicitly confirmed live action test","sideEffect":"Real external delivery"},{"method":"POST","path":"/api/v1/workflows/{id}/run","description":"Run the current draft including actions","sideEffect":"Real external delivery"},{"method":"GET","path":"/api/v1/workflows/{id}/runs","description":"Inspect paginated execution history"},{"method":"GET / POST","path":"/api/v1/workflow-credentials","description":"List safe metadata or create an encrypted credential"},{"method":"GET / PATCH / DELETE","path":"/api/v1/workflow-credentials/{id}","description":"Read metadata, rotate, or safely delete a credential"}]},{"name":"Saved queries, metrics, and approval","relevant_scope":"query","endpoints":[{"method":"GET / POST","path":"/api/v1/saved-queries","description":"List or create saved queries"},{"method":"GET / PATCH / DELETE","path":"/api/v1/saved-queries/{id}","description":"Manage a saved query"},{"method":"POST","path":"/api/v1/saved-queries/{id}/run","description":"Run a saved query with parameters"},{"method":"GET / POST","path":"/api/v1/metrics","description":"List or define metrics"},{"method":"GET / PATCH / DELETE","path":"/api/v1/metrics/{id}","description":"Manage a metric definition"},{"method":"GET","path":"/api/v1/metrics/{id}/value","description":"Evaluate a metric now"},{"method":"GET / POST","path":"/api/v1/approval-rules","description":"List or create approval rules"},{"method":"GET / PATCH / DELETE","path":"/api/v1/approval-rules/{id}","description":"Manage an approval rule"},{"method":"POST","path":"/api/v1/queries/submit","description":"Submit a query for approval"},{"method":"GET","path":"/api/v1/queries/pending","description":"List pending queries"},{"method":"GET","path":"/api/v1/queries/{id}/status","description":"Read approval status"},{"method":"POST","path":"/api/v1/queries/{id}/approve","description":"Approve a pending query"},{"method":"POST","path":"/api/v1/queries/{id}/reject","description":"Reject a pending query"}]},{"name":"Webhooks, usage, and keys","relevant_scope":"webhooks / usage / admin","endpoints":[{"method":"GET / POST","path":"/api/v1/webhooks","description":"List or create signed event endpoints"},{"method":"GET / PATCH / DELETE","path":"/api/v1/webhooks/{id}","description":"Manage one event endpoint"},{"method":"GET","path":"/api/v1/webhooks/{id}/deliveries","description":"Inspect delivery history"},{"method":"POST","path":"/api/v1/webhooks/{id}/test","description":"Send a test event","sideEffect":"Real external delivery"},{"method":"GET","path":"/api/v1/usage","description":"Read usage records"},{"method":"GET","path":"/api/v1/usage/budget","description":"Read budget status"},{"method":"GET / POST","path":"/api/v1/keys","description":"List or create API keys"},{"method":"DELETE","path":"/api/v1/keys/{id}","description":"Revoke an API key"}]}],"supported_database_types":["POSTGRES","MYSQL","MARIADB","MSSQL","MONGODB","SQLITE"],"retry_guidance":{"safe_to_retry_with_backoff":["GET requests","read-only query requests when the caller can tolerate duplicate execution","HTTP 429 and transient 5xx responses"],"do_not_blindly_retry":["confirmed live action tests","manual workflow runs","credential rotation","other calls with external delivery side effects"]},"links":{"humanOverview":"https://aifordatabase.com/docs/api-overview/","authentication":"https://aifordatabase.com/docs/authentication/","endpointReference":"https://aifordatabase.com/docs/endpoints/","queryingGuide":"https://aifordatabase.com/docs/agent-querying-databases/","workflowGuide":"https://aifordatabase.com/docs/agent-workflow-lifecycle/","credentialGuide":"https://aifordatabase.com/docs/outbound-credentials/","errorsGuide":"https://aifordatabase.com/docs/api-errors-and-retries/","alertGuide":"https://aifordatabase.com/docs/agent-created-alerts/","humanAgentPage":"https://aifordatabase.com/agents/","machineAgentPage":"https://aifordatabase.com/for-agents/","jsonManifest":"https://aifordatabase.com/api/agents","llms":"https://aifordatabase.com/llms.txt","llmsFull":"https://aifordatabase.com/llms-full.txt"}}