{"openapi":"3.1.0","info":{"title":"AI for Database API","version":"1.0.0","description":"API for AI agents to interact with databases through natural language, dashboards, workflows, and more."},"servers":[{"url":"https://app.aifordatabase.com/api/v1"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Connections","description":"Manage database connections, schemas, annotations, and execute SQL queries"},{"name":"Chat","description":"Send natural-language messages and receive AI-generated SQL and insights"},{"name":"Conversations","description":"Manage chat conversation history"},{"name":"Dashboards","description":"Create and manage dashboards and their widgets"},{"name":"Workflows","description":"Build and run scheduled or manual multi-step workflows"},{"name":"Webhooks","description":"Manage webhook endpoints, deliveries, and test events"},{"name":"Metrics","description":"Define and evaluate metric formulas against connections"},{"name":"Saved Queries","description":"Store, parameterize, and execute reusable SQL queries"},{"name":"Query Approval","description":"Submit queries for human approval before execution"},{"name":"Usage","description":"View usage records and budget information"},{"name":"Keys","description":"Manage platform API keys"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Platform API key starting with afd_"}},"schemas":{"ApiMeta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"timestamp":{"type":"string","format":"date-time"},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["requestId","timestamp"]},"Pagination":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"totalPages":{"type":"integer"}},"required":["total","page","pageSize","totalPages"]},"ApiError":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]},"SuccessEnvelope":{"type":"object","properties":{"data":{},"error":{"type":"null"},"meta":{"$ref":"#/components/schemas/ApiMeta"}},"required":["data","error","meta"]},"ErrorEnvelope":{"type":"object","properties":{"data":{"type":"null"},"error":{"$ref":"#/components/schemas/ApiError"},"meta":{"$ref":"#/components/schemas/ApiMeta"}},"required":["data","error","meta"]},"DeletedResponse":{"type":"object","properties":{"deleted":{"type":"boolean","example":true}}},"Connection":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["POSTGRES","MYSQL","MARIADB","MSSQL","MONGODB","SQLITE"]},"host":{"type":"string"},"port":{"type":"integer","nullable":true},"database":{"type":"string"},"username":{"type":"string"},"sslEnabled":{"type":"boolean"},"isActive":{"type":"boolean"},"lastTestedAt":{"type":"string","format":"date-time","nullable":true},"schemaUpdatedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"ConnectionCreate":{"type":"object","required":["name","type"],"properties":{"name":{"type":"string"},"type":{"type":"string","enum":["POSTGRES","MYSQL","MARIADB","MSSQL","MONGODB","SQLITE"]},"host":{"type":"string"},"port":{"type":"integer"},"database":{"type":"string"},"username":{"type":"string"},"encryptedPassword":{"type":"string"},"sslEnabled":{"type":"boolean","default":false}}},"ConnectionUpdate":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["POSTGRES","MYSQL","MARIADB","MSSQL","MONGODB","SQLITE"]},"host":{"type":"string"},"port":{"type":"integer"},"database":{"type":"string"},"username":{"type":"string"},"encryptedPassword":{"type":"string"},"sslEnabled":{"type":"boolean"},"isActive":{"type":"boolean"}}},"TestResult":{"type":"object","properties":{"success":{"type":"boolean"},"latency":{"type":"number"},"message":{"type":"string"}}},"SchemaResult":{"type":"object","properties":{"schema":{"type":"object","description":"Introspected database schema with tables, columns, and types"},"schemaSummary":{"type":"string","nullable":true},"schemaUpdatedAt":{"type":"string","format":"date-time"}}},"QueryRequest":{"type":"object","required":["sql"],"properties":{"sql":{"type":"string","description":"SQL query to execute"}}},"QueryResult":{"type":"object","properties":{"columns":{"type":"array","items":{"type":"string"}},"rows":{"type":"array","items":{"type":"object"}},"rowCount":{"type":"integer"},"executionTime":{"type":"number","description":"Execution time in milliseconds"}}},"Annotation":{"type":"object","properties":{"id":{"type":"string"},"connectionId":{"type":"string"},"tableName":{"type":"string"},"columnName":{"type":"string","nullable":true},"annotation":{"type":"string"},"dataType":{"type":"string","nullable":true},"examples":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"AnnotationCreate":{"type":"object","required":["tableName","annotation"],"properties":{"tableName":{"type":"string"},"columnName":{"type":"string","nullable":true},"annotation":{"type":"string"},"dataType":{"type":"string"},"examples":{"type":"string"}}},"AnnotationUpdate":{"type":"object","properties":{"annotation":{"type":"string"},"dataType":{"type":"string","nullable":true},"examples":{"type":"string","nullable":true}}},"AutoAnnotationRequest":{"type":"object","properties":{"tables":{"type":"array","items":{"type":"string"},"description":"Specific table names to annotate. Omit to annotate all tables."}}},"AutoAnnotationResult":{"type":"object","properties":{"message":{"type":"string"},"connectionId":{"type":"string"},"tables":{"type":"array","items":{"type":"string"}},"tableCount":{"type":"integer"}}},"ChatRequest":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Natural-language question or instruction"},"connectionId":{"type":"string","description":"Database connection to use for SQL execution"},"conversationId":{"type":"string","description":"Continue an existing conversation"},"stream":{"type":"boolean","default":false,"description":"Set true for Server-Sent Events streaming"}}},"ChatResponse":{"type":"object","properties":{"messageId":{"type":"string"},"conversationId":{"type":"string"},"content":{"type":"string","description":"AI-generated natural language response"},"sqlQuery":{"type":"string","nullable":true},"intent":{"type":"string","nullable":true},"queryResult":{"$ref":"#/components/schemas/QueryResult"},"steps":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string"},"detail":{"type":"string"},"sql":{"type":"string","nullable":true},"queryResult":{"type":"object","nullable":true,"properties":{"columns":{"type":"array","items":{"type":"string"}},"rowCount":{"type":"integer"},"executionTime":{"type":"number"}}},"queryError":{"type":"string","nullable":true}}}},"usage":{"type":"object","properties":{"model":{"type":"string"},"promptTokens":{"type":"integer"},"completionTokens":{"type":"integer"}}}}},"Conversation":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"userId":{"type":"string"},"connectionId":{"type":"string","nullable":true},"title":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"ConversationCreate":{"type":"object","properties":{"title":{"type":"string"},"connectionId":{"type":"string"}}},"ConversationUpdate":{"type":"object","required":["title"],"properties":{"title":{"type":"string"}}},"Message":{"type":"object","properties":{"id":{"type":"string"},"conversationId":{"type":"string"},"role":{"type":"string","enum":["USER","ASSISTANT"]},"content":{"type":"string"},"sqlQuery":{"type":"string","nullable":true},"resultSummary":{"type":"string","nullable":true},"promptTokens":{"type":"integer","nullable":true},"completionTokens":{"type":"integer","nullable":true},"model":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"Dashboard":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"isPublic":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"widgets":{"type":"array","items":{"$ref":"#/components/schemas/Widget"}}}},"DashboardCreate":{"type":"object","required":["title"],"properties":{"title":{"type":"string"},"description":{"type":"string"},"isPublic":{"type":"boolean","default":false}}},"DashboardUpdate":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"isPublic":{"type":"boolean"}}},"Widget":{"type":"object","properties":{"id":{"type":"string"},"dashboardId":{"type":"string"},"connectionId":{"type":"string","nullable":true},"type":{"type":"string"},"title":{"type":"string"},"query":{"type":"string"},"config":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"},"position":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"WidgetCreate":{"type":"object","required":["type","title"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"query":{"type":"string"},"connectionId":{"type":"string"},"config":{"type":"string"},"width":{"type":"integer","default":6},"height":{"type":"integer","default":4},"position":{"type":"integer","default":0}}},"WidgetUpdate":{"type":"object","properties":{"title":{"type":"string"},"query":{"type":"string"},"config":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"},"position":{"type":"integer"}}},"Workflow":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"connectionId":{"type":"string","nullable":true},"triggerType":{"type":"string","enum":["MANUAL","SCHEDULE"]},"triggerConfig":{"type":"string","description":"JSON configuration for schedule triggers"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"steps":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowStep"}},"actions":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowAction"}}}},"WorkflowCreate":{"type":"object","required":["name","triggerType"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"connectionId":{"type":"string"},"triggerType":{"type":"string","enum":["MANUAL","SCHEDULE"]},"triggerConfig":{"type":"string"},"steps":{"type":"array","items":{"type":"object","required":["query"],"properties":{"name":{"type":"string"},"query":{"type":"string"},"stopIfEmpty":{"type":"boolean","default":false},"order":{"type":"integer"}}}},"actions":{"type":"array","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"config":{"type":"string"},"order":{"type":"integer"}}}}}},"WorkflowUpdate":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"connectionId":{"type":"string","nullable":true},"triggerType":{"type":"string","enum":["MANUAL","SCHEDULE"]},"triggerConfig":{"type":"string"},"isActive":{"type":"boolean"}}},"WorkflowStep":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"query":{"type":"string"},"stopIfEmpty":{"type":"boolean"},"order":{"type":"integer"}}},"WorkflowAction":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"config":{"type":"string"},"order":{"type":"integer"}}},"WorkflowRun":{"type":"object","properties":{"id":{"type":"string"},"workflowId":{"type":"string"},"trigger":{"type":"string"},"status":{"type":"string","enum":["RUNNING","COMPLETED","FAILED"]},"result":{"type":"string","nullable":true},"error":{"type":"string","nullable":true},"startedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true}}},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"url":{"type":"string","format":"uri"},"secret":{"type":"string","description":"Full secret shown only on creation; masked on subsequent reads"},"events":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"WebhookEndpointCreate":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"},"description":"Event types to subscribe to, or ['*'] for all"},"isActive":{"type":"boolean","default":true}}},"WebhookEndpointUpdate":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"}}},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"endpointId":{"type":"string"},"event":{"type":"string"},"payload":{"type":"string"},"statusCode":{"type":"integer","nullable":true},"attempts":{"type":"integer"},"deliveredAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"WebhookTestResult":{"type":"object","properties":{"delivery":{"$ref":"#/components/schemas/WebhookDelivery"},"success":{"type":"boolean"},"error":{"type":"string","nullable":true}}},"MetricDefinition":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"formula":{"type":"string","description":"SQL query whose first column of first row yields the metric value"},"connectionId":{"type":"string","nullable":true},"unit":{"type":"string","nullable":true},"dimensions":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"MetricCreate":{"type":"object","required":["name","formula"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"formula":{"type":"string"},"connectionId":{"type":"string"},"unit":{"type":"string"},"dimensions":{"type":"string"}}},"MetricUpdate":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"formula":{"type":"string"},"connectionId":{"type":"string"},"unit":{"type":"string"},"dimensions":{"type":"string"}}},"MetricValue":{"type":"object","properties":{"value":{"description":"The computed metric value"},"unit":{"type":"string","nullable":true},"asOf":{"type":"string","format":"date-time"},"executionTime":{"type":"number"}}},"SavedQuery":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"connectionId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"query":{"type":"string"},"parameters":{"type":"string","description":"JSON array of parameter definitions"},"tags":{"type":"string","nullable":true},"isPublic":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"SavedQueryCreate":{"type":"object","required":["name","query","connectionId"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"connectionId":{"type":"string"},"query":{"type":"string"},"parameters":{"type":"string","description":"JSON array of { name, type, required }"},"tags":{"type":"string"},"isPublic":{"type":"boolean","default":true}}},"SavedQueryUpdate":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"connectionId":{"type":"string"},"query":{"type":"string"},"parameters":{"type":"string"},"tags":{"type":"string"},"isPublic":{"type":"boolean"}}},"SavedQueryRunRequest":{"type":"object","properties":{"params":{"type":"object","additionalProperties":true,"description":"Key-value pairs for query placeholders"}}},"ApprovalRule":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"connectionId":{"type":"string","nullable":true},"scope":{"type":"string"},"approvers":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"ApprovalRuleCreate":{"type":"object","required":["approvers"],"properties":{"connectionId":{"type":"string"},"scope":{"type":"string","default":"all"},"approvers":{"type":"array","items":{"type":"string"},"description":"User IDs of authorized approvers"}}},"ApprovalRuleUpdate":{"type":"object","properties":{"connectionId":{"type":"string","nullable":true},"scope":{"type":"string"},"approvers":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"}}},"QuerySubmitRequest":{"type":"object","required":["connectionId","query"],"properties":{"connectionId":{"type":"string"},"query":{"type":"string"},"context":{"type":"string","description":"Optional description of why this query needs to run"}}},"PendingQuery":{"type":"object","properties":{"id":{"type":"string"},"connectionId":{"type":"string"},"connectionName":{"type":"string","nullable":true},"connectionType":{"type":"string","nullable":true},"apiKeyId":{"type":"string","nullable":true},"query":{"type":"string"},"context":{"type":"string","nullable":true},"status":{"type":"string","enum":["PENDING","APPROVED","REJECTED","EXPIRED"]},"reviewNote":{"type":"string","nullable":true},"result":{"nullable":true,"description":"Query result (only present after approval)"},"expiresAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"ApproveRejectRequest":{"type":"object","properties":{"note":{"type":"string","description":"Optional reviewer note"}}},"ApprovalResult":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["APPROVED","REJECTED"]},"reviewedBy":{"type":"string"},"reviewNote":{"type":"string","nullable":true},"result":{"$ref":"#/components/schemas/QueryResult"}}},"UsageRecord":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"userId":{"type":"string"},"model":{"type":"string"},"promptTokens":{"type":"integer"},"completionTokens":{"type":"integer"},"costCents":{"type":"number"},"feature":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"Budget":{"type":"object","properties":{"included":{"type":"integer","description":"Included budget in cents"},"topUp":{"type":"integer","description":"Top-up budget in cents"},"used":{"type":"integer","description":"Used budget in cents"},"remaining":{"type":"integer","description":"Remaining budget in cents"},"periodStart":{"type":"string","format":"date-time","nullable":true},"periodEnd":{"type":"string","format":"date-time","nullable":true}}},"ApiKey":{"type":"object","properties":{"id":{"type":"string"},"keyPrefix":{"type":"string"},"name":{"type":"string"},"scopes":{"type":"string"},"lastUsedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time","nullable":true}}},"ApiKeyCreate":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"},"default":["*"],"description":"Permission scopes — use '*' for all"},"expiresAt":{"type":"string","format":"date-time"}}},"ApiKeyCreated":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"keyPrefix":{"type":"string"},"scopes":{"type":"string"},"expiresAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"key":{"type":"string","description":"Full API key — only returned at creation time"}}}},"parameters":{"PageParam":{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number (1-based)"},"PageSizeParam":{"name":"pageSize","in":"query","schema":{"type":"integer","default":20,"maximum":100},"description":"Items per page (max 100)"},"IdParam":{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID"}},"responses":{"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadRequest":{"description":"Validation error or bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Forbidden":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"paths":{"/connections":{"get":{"tags":["Connections"],"summary":"List connections","operationId":"listConnections","description":"Returns paginated list of database connections. Admins see all org connections; regular users see only assigned connections.","parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/PageSizeParam"}],"responses":{"200":{"description":"Paginated list of connections","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Connection"}}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["Connections"],"summary":"Create connection","operationId":"createConnection","description":"Create a new database connection. Admin only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionCreate"}}}},"responses":{"201":{"description":"Connection created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Connection"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/connections/{id}":{"get":{"tags":["Connections"],"summary":"Get connection","operationId":"getConnection","description":"Get a single database connection by ID.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"responses":{"200":{"description":"Connection details","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Connection"}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Connections"],"summary":"Update connection","operationId":"updateConnection","description":"Update a database connection. Admin only.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionUpdate"}}}},"responses":{"200":{"description":"Connection updated","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Connection"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"tags":["Connections"],"summary":"Delete connection","operationId":"deleteConnection","description":"Delete a database connection. Admin only.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"responses":{"200":{"description":"Connection deleted","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeletedResponse"}}}]}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/connections/{id}/test":{"post":{"tags":["Connections"],"summary":"Test connection","operationId":"testConnection","description":"Test connectivity to the database and report latency.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"responses":{"200":{"description":"Test result","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TestResult"}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Connection test failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/connections/{id}/schema":{"get":{"tags":["Connections"],"summary":"Get schema","operationId":"getConnectionSchema","description":"Return the cached introspected database schema.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"responses":{"200":{"description":"Schema data","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SchemaResult"}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"tags":["Connections"],"summary":"Introspect schema","operationId":"introspectConnectionSchema","description":"Re-introspect the database schema from the live connection and cache the result.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"responses":{"200":{"description":"Freshly introspected schema","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SchemaResult"}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Introspection failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/connections/{id}/query":{"post":{"tags":["Connections"],"summary":"Execute SQL","operationId":"executeQuery","description":"Execute a raw SQL query against the connection and return results.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryRequest"}}}},"responses":{"200":{"description":"Query result","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/QueryResult"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Query execution failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/connections/{id}/annotations":{"get":{"tags":["Connections"],"summary":"List annotations","operationId":"listAnnotations","description":"List schema annotations for a connection, optionally filtered by table.","parameters":[{"$ref":"#/components/parameters/IdParam"},{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/PageSizeParam"},{"name":"table","in":"query","schema":{"type":"string"},"description":"Filter by table name"}],"responses":{"200":{"description":"Paginated list of annotations","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Annotation"}}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"tags":["Connections"],"summary":"Create or upsert annotation","operationId":"createAnnotation","description":"Create a new schema annotation or update an existing one (upserts on tableName + columnName).","parameters":[{"$ref":"#/components/parameters/IdParam"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnnotationCreate"}}}},"responses":{"201":{"description":"Annotation created or upserted","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Annotation"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/connections/{id}/annotations/{annotationId}":{"get":{"tags":["Connections"],"summary":"Get annotation","operationId":"getAnnotation","description":"Get a single schema annotation by ID.","parameters":[{"$ref":"#/components/parameters/IdParam"},{"name":"annotationId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Annotation details","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Annotation"}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Connections"],"summary":"Update annotation","operationId":"updateAnnotation","description":"Update an existing schema annotation.","parameters":[{"$ref":"#/components/parameters/IdParam"},{"name":"annotationId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnnotationUpdate"}}}},"responses":{"200":{"description":"Annotation updated","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Annotation"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"tags":["Connections"],"summary":"Delete annotation","operationId":"deleteAnnotation","description":"Delete a schema annotation.","parameters":[{"$ref":"#/components/parameters/IdParam"},{"name":"annotationId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Annotation deleted","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeletedResponse"}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/connections/{id}/annotations/auto":{"post":{"tags":["Connections"],"summary":"Auto-generate annotations","operationId":"autoGenerateAnnotations","description":"Use AI to automatically generate schema annotations for all or specified tables. Requires a prior schema introspection.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutoAnnotationRequest"}}}},"responses":{"202":{"description":"Auto-annotation queued","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AutoAnnotationResult"}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"},"412":{"description":"Schema not yet introspected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/chat":{"post":{"tags":["Chat"],"summary":"Send message","operationId":"sendChatMessage","description":"Send a natural-language message. Returns AI response with optional SQL generation and execution. Set `stream: true` for Server-Sent Events streaming.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRequest"}}}},"responses":{"200":{"description":"Chat response (sync mode)","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChatResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"description":"Credits exhausted or upgrade required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"200 (stream)":{"description":"Server-Sent Events stream (when stream=true). Each event is a JSON object with `type` field."}}}},"/conversations":{"get":{"tags":["Conversations"],"summary":"List conversations","operationId":"listConversations","description":"List chat conversations for the organization, optionally filtered by connectionId.","parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/PageSizeParam"},{"name":"connectionId","in":"query","schema":{"type":"string"},"description":"Filter by connection"}],"responses":{"200":{"description":"Paginated list of conversations","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"}}}}]}}}}}},"post":{"tags":["Conversations"],"summary":"Create conversation","operationId":"createConversation","description":"Create a new empty conversation.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationCreate"}}}},"responses":{"201":{"description":"Conversation created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Conversation"}}}]}}}}}}},"/conversations/{id}":{"get":{"tags":["Conversations"],"summary":"Get conversation","operationId":"getConversation","description":"Get a conversation with all its messages.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"responses":{"200":{"description":"Conversation with messages","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Conversation"}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Conversations"],"summary":"Update conversation","operationId":"updateConversation","description":"Update the conversation title.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationUpdate"}}}},"responses":{"200":{"description":"Conversation updated","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Conversation"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"tags":["Conversations"],"summary":"Delete conversation","operationId":"deleteConversation","description":"Delete a conversation and all its messages.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"responses":{"200":{"description":"Conversation deleted","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeletedResponse"}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/conversations/{id}/messages":{"get":{"tags":["Conversations"],"summary":"Get messages","operationId":"listConversationMessages","description":"List messages in a conversation, ordered chronologically.","parameters":[{"$ref":"#/components/parameters/IdParam"},{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/PageSizeParam"}],"responses":{"200":{"description":"Paginated messages","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Message"}}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/dashboards":{"get":{"tags":["Dashboards"],"summary":"List dashboards","operationId":"listDashboards","description":"List all dashboards for the organization.","parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/PageSizeParam"}],"responses":{"200":{"description":"Paginated dashboards","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Dashboard"}}}}]}}}}}},"post":{"tags":["Dashboards"],"summary":"Create dashboard","operationId":"createDashboard","description":"Create a new dashboard.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DashboardCreate"}}}},"responses":{"201":{"description":"Dashboard created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Dashboard"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/dashboards/{id}":{"get":{"tags":["Dashboards"],"summary":"Get dashboard","operationId":"getDashboard","description":"Get a dashboard with all its widgets.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"responses":{"200":{"description":"Dashboard with widgets","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Dashboard"}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Dashboards"],"summary":"Update dashboard","operationId":"updateDashboard","description":"Update dashboard properties.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DashboardUpdate"}}}},"responses":{"200":{"description":"Dashboard updated","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Dashboard"}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"tags":["Dashboards"],"summary":"Delete dashboard","operationId":"deleteDashboard","description":"Delete a dashboard and all its widgets.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"responses":{"200":{"description":"Dashboard deleted","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeletedResponse"}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/dashboards/{id}/widgets":{"get":{"tags":["Dashboards"],"summary":"List widgets","operationId":"listWidgets","description":"List all widgets for a dashboard, ordered by position.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"responses":{"200":{"description":"List of widgets","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Widget"}}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"tags":["Dashboards"],"summary":"Create widget","operationId":"createWidget","description":"Add a new widget to a dashboard.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WidgetCreate"}}}},"responses":{"201":{"description":"Widget created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Widget"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/dashboards/{id}/widgets/{widgetId}":{"patch":{"tags":["Dashboards"],"summary":"Update widget","operationId":"updateWidget","description":"Update widget properties.","parameters":[{"$ref":"#/components/parameters/IdParam"},{"name":"widgetId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WidgetUpdate"}}}},"responses":{"200":{"description":"Widget updated","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Widget"}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"tags":["Dashboards"],"summary":"Delete widget","operationId":"deleteWidget","description":"Remove a widget from a dashboard.","parameters":[{"$ref":"#/components/parameters/IdParam"},{"name":"widgetId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Widget deleted","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeletedResponse"}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/dashboards/{id}/widgets/{widgetId}/data":{"get":{"tags":["Dashboards"],"summary":"Get widget data","operationId":"getWidgetData","description":"Execute the widget's SQL query against its connection and return the result set.","parameters":[{"$ref":"#/components/parameters/IdParam"},{"name":"widgetId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Query result for the widget","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/QueryResult"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/workflows":{"get":{"tags":["Workflows"],"summary":"List workflows","operationId":"listWorkflows","description":"List all workflows for the organization.","parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/PageSizeParam"}],"responses":{"200":{"description":"Paginated workflows","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Workflow"}}}}]}}}}}},"post":{"tags":["Workflows"],"summary":"Create workflow","operationId":"createWorkflow","description":"Create a new workflow with optional steps and actions.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowCreate"}}}},"responses":{"201":{"description":"Workflow created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Workflow"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/workflows/{id}":{"get":{"tags":["Workflows"],"summary":"Get workflow","operationId":"getWorkflow","description":"Get a workflow with its steps and actions.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"responses":{"200":{"description":"Workflow details","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Workflow"}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Workflows"],"summary":"Update workflow","operationId":"updateWorkflow","description":"Update workflow properties.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowUpdate"}}}},"responses":{"200":{"description":"Workflow updated","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Workflow"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"tags":["Workflows"],"summary":"Delete workflow","operationId":"deleteWorkflow","description":"Delete a workflow and its steps, actions, and run history.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"responses":{"200":{"description":"Workflow deleted","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeletedResponse"}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/workflows/{id}/run":{"post":{"tags":["Workflows"],"summary":"Trigger workflow","operationId":"triggerWorkflow","description":"Manually trigger a workflow execution.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"responses":{"201":{"description":"Workflow run started","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkflowRun"}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/workflows/{id}/runs":{"get":{"tags":["Workflows"],"summary":"Get run history","operationId":"listWorkflowRuns","description":"List execution history for a workflow.","parameters":[{"$ref":"#/components/parameters/IdParam"},{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/PageSizeParam"}],"responses":{"200":{"description":"Paginated workflow runs","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowRun"}}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/webhooks":{"get":{"tags":["Webhooks"],"summary":"List endpoints","operationId":"listWebhookEndpoints","description":"List all webhook endpoints for the organization.","parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/PageSizeParam"}],"responses":{"200":{"description":"Paginated webhook endpoints","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}]}}}}}},"post":{"tags":["Webhooks"],"summary":"Create endpoint","operationId":"createWebhookEndpoint","description":"Create a new webhook endpoint. The signing secret is returned only in the creation response.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointCreate"}}}},"responses":{"201":{"description":"Webhook endpoint created (includes full secret)","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookEndpoint"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/webhooks/{id}":{"get":{"tags":["Webhooks"],"summary":"Get endpoint","operationId":"getWebhookEndpoint","description":"Get a webhook endpoint by ID. The secret is masked.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"responses":{"200":{"description":"Webhook endpoint (secret masked)","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookEndpoint"}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Webhooks"],"summary":"Update endpoint","operationId":"updateWebhookEndpoint","description":"Update webhook endpoint URL, events, or active status.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointUpdate"}}}},"responses":{"200":{"description":"Webhook endpoint updated","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookEndpoint"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"tags":["Webhooks"],"summary":"Delete endpoint","operationId":"deleteWebhookEndpoint","description":"Delete a webhook endpoint and all its delivery history.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"responses":{"200":{"description":"Webhook endpoint deleted","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeletedResponse"}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/webhooks/{id}/deliveries":{"get":{"tags":["Webhooks"],"summary":"Get deliveries","operationId":"listWebhookDeliveries","description":"List delivery attempts for a webhook endpoint.","parameters":[{"$ref":"#/components/parameters/IdParam"},{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/PageSizeParam"}],"responses":{"200":{"description":"Paginated deliveries","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/webhooks/{id}/test":{"post":{"tags":["Webhooks"],"summary":"Send test event","operationId":"testWebhookEndpoint","description":"Send a test webhook event to the endpoint and return the delivery result.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"responses":{"200":{"description":"Test delivery result","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookTestResult"}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/metrics":{"get":{"tags":["Metrics"],"summary":"List metrics","operationId":"listMetrics","description":"List metric definitions for the organization, optionally filtered by connectionId.","parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/PageSizeParam"},{"name":"connectionId","in":"query","schema":{"type":"string"},"description":"Filter by connection"}],"responses":{"200":{"description":"Paginated metrics","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MetricDefinition"}}}}]}}}}}},"post":{"tags":["Metrics"],"summary":"Create metric","operationId":"createMetric","description":"Create a new metric definition with an SQL formula.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricCreate"}}}},"responses":{"201":{"description":"Metric created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MetricDefinition"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"409":{"description":"A metric with this name already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/metrics/{id}":{"get":{"tags":["Metrics"],"summary":"Get metric","operationId":"getMetric","description":"Get a single metric definition by ID.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"responses":{"200":{"description":"Metric details","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MetricDefinition"}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Metrics"],"summary":"Update metric","operationId":"updateMetric","description":"Update metric definition properties.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricUpdate"}}}},"responses":{"200":{"description":"Metric updated","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MetricDefinition"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Duplicate metric name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"tags":["Metrics"],"summary":"Delete metric","operationId":"deleteMetric","description":"Delete a metric definition.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"responses":{"200":{"description":"Metric deleted","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeletedResponse"}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/metrics/{id}/value":{"get":{"tags":["Metrics"],"summary":"Get metric value","operationId":"getMetricValue","description":"Execute the metric formula and return the current computed value.","parameters":[{"$ref":"#/components/parameters/IdParam"},{"name":"connectionId","in":"query","schema":{"type":"string"},"description":"Override the metric's default connection"}],"responses":{"200":{"description":"Metric value","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MetricValue"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Formula execution failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/saved-queries":{"get":{"tags":["Saved Queries"],"summary":"List saved queries","operationId":"listSavedQueries","description":"List saved queries, optionally filtered by connectionId or tags.","parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/PageSizeParam"},{"name":"connectionId","in":"query","schema":{"type":"string"},"description":"Filter by connection"},{"name":"tags","in":"query","schema":{"type":"string"},"description":"Filter by tag substring"}],"responses":{"200":{"description":"Paginated saved queries","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SavedQuery"}}}}]}}}}}},"post":{"tags":["Saved Queries"],"summary":"Create saved query","operationId":"createSavedQuery","description":"Create a new reusable saved query with optional parameterized placeholders.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedQueryCreate"}}}},"responses":{"201":{"description":"Saved query created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SavedQuery"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"409":{"description":"Duplicate name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/saved-queries/{id}":{"get":{"tags":["Saved Queries"],"summary":"Get saved query","operationId":"getSavedQuery","description":"Get a single saved query by ID.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"responses":{"200":{"description":"Saved query details","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SavedQuery"}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Saved Queries"],"summary":"Update saved query","operationId":"updateSavedQuery","description":"Update saved query properties.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedQueryUpdate"}}}},"responses":{"200":{"description":"Saved query updated","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SavedQuery"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Duplicate name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"tags":["Saved Queries"],"summary":"Delete saved query","operationId":"deleteSavedQuery","description":"Delete a saved query.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"responses":{"200":{"description":"Saved query deleted","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeletedResponse"}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/saved-queries/{id}/run":{"post":{"tags":["Saved Queries"],"summary":"Execute saved query","operationId":"executeSavedQuery","description":"Execute a saved query with optional parameter substitution. Parameters replace {{paramName}} placeholders in the query.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedQueryRunRequest"}}}},"responses":{"200":{"description":"Query execution result","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/QueryResult"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Query execution failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/approval-rules":{"get":{"tags":["Query Approval"],"summary":"List rules","operationId":"listApprovalRules","description":"List query approval rules for the organization. Admin only.","parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/PageSizeParam"}],"responses":{"200":{"description":"Paginated approval rules","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApprovalRule"}}}}]}}}},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"tags":["Query Approval"],"summary":"Create rule","operationId":"createApprovalRule","description":"Create a new query approval rule. Admin only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalRuleCreate"}}}},"responses":{"201":{"description":"Approval rule created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApprovalRule"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/approval-rules/{id}":{"get":{"tags":["Query Approval"],"summary":"Get rule","operationId":"getApprovalRule","description":"Get a single approval rule by ID. Admin only.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"responses":{"200":{"description":"Approval rule details","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApprovalRule"}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Query Approval"],"summary":"Update rule","operationId":"updateApprovalRule","description":"Update an approval rule. Admin only.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalRuleUpdate"}}}},"responses":{"200":{"description":"Approval rule updated","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApprovalRule"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"tags":["Query Approval"],"summary":"Delete rule","operationId":"deleteApprovalRule","description":"Delete an approval rule. Admin only.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"responses":{"200":{"description":"Approval rule deleted","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeletedResponse"}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/queries/submit":{"post":{"tags":["Query Approval"],"summary":"Submit query for approval","operationId":"submitQueryForApproval","description":"Submit a SQL query for human approval before execution. Returns a pending query ID for status polling.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuerySubmitRequest"}}}},"responses":{"202":{"description":"Query submitted for approval","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"pendingQueryId":{"type":"string"},"status":{"type":"string","enum":["PENDING"]},"expiresAt":{"type":"string","format":"date-time"}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/queries/{id}/status":{"get":{"tags":["Query Approval"],"summary":"Get query status","operationId":"getQueryApprovalStatus","description":"Get the current status of a pending query. Automatically marks expired queries.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"responses":{"200":{"description":"Pending query status","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PendingQuery"}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/queries/pending":{"get":{"tags":["Query Approval"],"summary":"List pending queries","operationId":"listPendingQueries","description":"List all queries awaiting approval. Admin only.","parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/PageSizeParam"}],"responses":{"200":{"description":"Paginated pending queries","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PendingQuery"}}}}]}}}},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/queries/{id}/approve":{"post":{"tags":["Query Approval"],"summary":"Approve query","operationId":"approveQuery","description":"Approve a pending query and execute it. The query result is returned in the response. Only authorized approvers can approve.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApproveRejectRequest"}}}},"responses":{"200":{"description":"Query approved and executed","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApprovalResult"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Query execution failed after approval","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/queries/{id}/reject":{"post":{"tags":["Query Approval"],"summary":"Reject query","operationId":"rejectQuery","description":"Reject a pending query with an optional note.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApproveRejectRequest"}}}},"responses":{"200":{"description":"Query rejected","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["REJECTED"]},"reviewedBy":{"type":"string"},"reviewNote":{"type":"string","nullable":true}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/usage":{"get":{"tags":["Usage"],"summary":"Usage records","operationId":"listUsageRecords","description":"List AI usage records for the organization.","parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/PageSizeParam"}],"responses":{"200":{"description":"Paginated usage records","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/UsageRecord"}}}}]}}}}}}},"/usage/budget":{"get":{"tags":["Usage"],"summary":"Budget info","operationId":"getUsageBudget","description":"Get the current billing period budget including included credits, top-ups, usage, and remaining balance.","responses":{"200":{"description":"Budget summary","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Budget"}}}]}}}}}}},"/keys":{"get":{"tags":["Keys"],"summary":"List API keys","operationId":"listApiKeys","description":"List all active (non-revoked) API keys for the organization. Admin only.","responses":{"200":{"description":"List of API keys","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}}}}]}}}},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"tags":["Keys"],"summary":"Create API key","operationId":"createApiKey","description":"Create a new platform API key. The full key is returned only once in the response. Admin only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreate"}}}},"responses":{"201":{"description":"API key created (includes full key)","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApiKeyCreated"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/keys/{id}":{"delete":{"tags":["Keys"],"summary":"Revoke API key","operationId":"revokeApiKey","description":"Revoke an API key. The key will no longer be usable for authentication. Admin only.","parameters":[{"$ref":"#/components/parameters/IdParam"}],"responses":{"200":{"description":"API key revoked","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"revoked":{"type":"boolean","example":true}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}