API Endpoints

API Endpoints

Reference for the AI for Database API. All paths are relative to https://app.aifordatabase.com/api/v1.

For exact request/response schemas, use the live OpenAPI spec or the interactive reference. The spec is maintained alongside the route handlers and is the contract for public v1 integrations.

Connections

Create a connection — type must be one of POSTGRES, MYSQL, MARIADB, MSSQL, MONGODB, SQLITE:

{
  "name": "Production DB",
  "type": "POSTGRES",
  "host": "db.example.com",
  "port": 5432,
  "database": "production",
  "username": "aifordb_reader",
  "password": "your-db-password",
  "sslEnabled": true
}

The password is write-only — it is never returned by any endpoint. (encryptedPassword and ssl are accepted as aliases for password / sslEnabled.)

Setup flow: creating a connection stores it; then call POST /connections/:id/test. On its first success, the test also introspects your tables and generates the AI schema overview automatically — create → test is the complete setup. Use POST /connections/:id/schema to re-introspect after your schema changes.

Failed tests return a structured diagnosis in the error details — what stage failed (DNS, connect, TLS, auth, schema read), whose fault it is, and concrete fix steps with your actual host/database/username filled in.

Connection health: connections are tested automatically in the background. If a connection fails 3 checks in a row, it's deactivated and the reason is saved — check lastError and lastErrorDiagnosis on GET /connections/:id any time to see why, without having to re-run a test yourself. Subscribe a webhook to connection.health.degraded to be notified the moment it happens instead of finding out from a failed query.

Chat & Conversations

Query Approval

Saved Queries & Metrics

Dashboards

Workflows

Workflow creation never schedules an incomplete draft. PATCH /workflows/:id can replace the draft's query steps and actions; include the current draftRevision as expectedDraftRevision so concurrent edits cannot be overwritten. Set isActive: true to validate and publish an immutable production version; set it to false to stop future scheduled runs. Manual runs use the current draft and have real external side effects.

Webhook action authentication is referenced by an encrypted, exact-host-bound credentialId. Create one through POST /workflow-credentials using the dedicated workflow_credentials scope and an admin-owned API key; the response contains metadata but never the secret. Inline authentication secrets are rejected. Preview the draft first to inspect raw eligible rows without delivery. Then call the action-test endpoint with {"confirmDelivery":true}; it sends a real request and returns the run with sanitized HTTP attempts. Run history includes the same attempt status, status code, retry timing, and bounded credential-redacted response data.

By default, every HTTP 2xx response is successful. Set successStatusCodes on a webhook action when the destination distinguishes full and partial acceptance. For example, Brevo's batch Events API uses [202]: HTTP 207 then becomes a visible failed delivery with the bounded response body instead of a false success.

Webhooks, Usage & Keys

Event webhook destinations must use public HTTPS on port 443. Private/reserved networks and unsafe redirects are blocked. Deliveries are HMAC-signed and non-2xx responses are failures; retryable responses are retried.

Error Codes