{"openapi":"3.1.0","info":{"title":"Basedash Public API","version":"0.0.0","description":"API for programmatic access to Basedash features. Use API keys for authentication.","contact":{"name":"Basedash Support","url":"https://basedash.com","email":"support@basedash.com"}},"servers":[{"url":"https://charts.basedash.com","description":"Production"}],"tags":[{"name":"Organizations","description":"Manage organizations"},{"name":"Groups","description":"Manage organization groups and memberships"},{"name":"Data Sources","description":"Manage database connections and data sources"},{"name":"MCP servers","description":"Manage MCP server data sources"},{"name":"Insights","description":"Manage generated insights"},{"name":"Automations","description":"Manage automations and automation runs"},{"name":"Skills","description":"Manage organization skills"},{"name":"Definitions","description":"Manage reusable SQL definitions"},{"name":"Dashboards","description":"Manage dashboards and their tabs"},{"name":"Charts","description":"Manage charts and their SQL queries"},{"name":"Chats","description":"Chat with the Basedash AI agent about your data. Start a chat by sending a message, then continue the conversation with follow-up messages. The assistant responds asynchronously: pass the `wait` query parameter to receive the finished response in the same request, or poll the assistant message (or stream its events) after an HTTP 202. Chats created through the API are not shown in the Basedash app."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication using Bearer token format: `Bearer <basedash_api_key>`"}},"schemas":{"SsoJwtClaims":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"User's email address"},"orgId":{"type":"string","description":"Basedash organization ID"},"firstName":{"type":"string","description":"User's first name"},"lastName":{"type":"string","description":"User's last name"},"role":{"type":"string","enum":["ADMIN","MEMBER"],"description":"Role for new members (defaults to MEMBER)"},"groups":{"type":"array","items":{"type":"string"},"description":"Group names for Basedash groups (future use)"},"exp":{"type":"number","description":"JWT expiration timestamp (Unix seconds)"},"iat":{"type":"number","description":"JWT issued-at timestamp (Unix seconds)"}},"required":["email","orgId","exp","iat"]},"PaginationMeta":{"type":"object","properties":{"nextCursor":{"type":["string","null"],"description":"Cursor for the next page (null if no more pages)"},"hasMore":{"type":"boolean","description":"Whether there are more items after this page"}},"required":["nextCursor","hasMore"]},"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ApiError"}},"required":["error"]},"ApiError":{"type":"object","properties":{"title":{"type":"string","description":"Error type identifier"},"detail":{"type":"string","description":"Human-readable error description"}},"required":["title","detail"]},"RateLimitErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/RateLimitError"}},"required":["error"]},"RateLimitError":{"allOf":[{"$ref":"#/components/schemas/ApiError"},{"type":"object","properties":{"title":{"type":"string","enum":["RateLimitExceeded"]},"retryAfterMs":{"type":"number","description":"Milliseconds until the rate limit window resets"}},"required":["retryAfterMs"]}]},"DatabaseDialect":{"anyOf":[{"type":"string","enum":["POSTGRES"]},{"type":"string","enum":["SUPABASE"]},{"type":"string","enum":["MYSQL"]},{"type":"string","enum":["PLANETSCALE"]},{"type":"string","enum":["ATHENA"]},{"type":"string","enum":["BIGQUERY"]},{"type":"string","enum":["CLICKHOUSE"]},{"type":"string","enum":["SPANNER"]},{"type":"string","enum":["SNOWFLAKE"]},{"type":"string","enum":["REDSHIFT"]},{"type":"string","enum":["SQL_SERVER"]},{"type":"string","enum":["ORACLE"]},{"type":"string","enum":["DATABRICKS"]},{"type":"string","enum":["POSTHOG"]},{"type":"string","enum":["DUCKDB"]}],"description":"Database dialect/type"},"SyncStatus":{"anyOf":[{"type":"string","enum":["PENDING"]},{"type":"string","enum":["SUCCESS"]},{"type":"string","enum":["FAILED"]},{"type":"string","enum":["NEVER_SYNCED"]}],"description":"Status of the last schema sync"},"ConnectionHealthStatus":{"anyOf":[{"type":"string","enum":["HEALTHY"]},{"type":"string","enum":["UNHEALTHY"]}],"description":"Connection health status"},"DataSourceAccessResponse":{"type":"object","properties":{"dataSourceId":{"type":"string","description":"Data source ID"},"mode":{"type":"string","enum":["everyone","restricted"],"description":"Whether everyone or only listed principals can query"},"accessLevel":{"type":["string","null"],"enum":["VIEW","EDIT",null],"description":"Everyone access level when mode is everyone"},"groupIds":{"type":"array","items":{"type":"string"},"description":"Deprecated. Organization group IDs with view or edit access when mode is restricted. Use groupAccess for access levels."},"memberIds":{"type":"array","items":{"type":"string"},"description":"Deprecated. Organization member IDs with view or edit access when mode is restricted. Use memberAccess for access levels."},"groupAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["VIEW","EDIT"],"default":"VIEW","description":"Whether the principal can view or edit the data source"}},"required":["id"]},"description":"Organization groups with view or edit access"},"memberAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["VIEW","EDIT"],"default":"VIEW","description":"Whether the principal can view or edit the data source"}},"required":["id"]},"description":"Organization members with view or edit access"}},"required":["dataSourceId","mode","accessLevel","groupIds","memberIds","groupAccess","memberAccess"]},"UpdateDataSourceAccessInput":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["everyone"]},"accessLevel":{"type":"string","enum":["VIEW","EDIT"],"default":"VIEW","description":"Whether the principal can view or edit the data source"},"groupIds":{"type":"array","items":{"type":"string"},"default":[],"description":"Deprecated. Organization group IDs granted view access. Use groupAccess to set view or edit access."},"memberIds":{"type":"array","items":{"type":"string"},"default":[],"description":"Deprecated. Organization member IDs granted view access. Use memberAccess to set view or edit access."},"groupAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["VIEW","EDIT"],"default":"VIEW","description":"Whether the principal can view or edit the data source"}},"required":["id"]},"default":[],"description":"Organization groups with view or edit access"},"memberAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["VIEW","EDIT"],"default":"VIEW","description":"Whether the principal can view or edit the data source"}},"required":["id"]},"default":[],"description":"Organization members with view or edit access"}},"required":["mode"]},{"type":"object","properties":{"mode":{"type":"string","enum":["restricted"]},"groupIds":{"type":"array","items":{"type":"string"},"default":[],"description":"Deprecated. Organization group IDs granted view access. Use groupAccess to set view or edit access."},"memberIds":{"type":"array","items":{"type":"string"},"default":[],"description":"Deprecated. Organization member IDs granted view access. Use memberAccess to set view or edit access."},"groupAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["VIEW","EDIT"],"default":"VIEW","description":"Whether the principal can view or edit the data source"}},"required":["id"]},"default":[],"description":"Organization groups with view or edit access"},"memberAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["VIEW","EDIT"],"default":"VIEW","description":"Whether the principal can view or edit the data source"}},"required":["id"]},"default":[],"description":"Organization members with view or edit access"}},"required":["mode"]}]},"PublicAutomationListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicAutomation"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]},"PublicAutomation":{"type":"object","properties":{"id":{"type":"string","description":"Automation ID"},"organizationId":{"type":"string","description":"Organization ID"},"name":{"type":"string","description":"Automation name"},"icon":{"type":"string","description":"Automation icon name"},"color":{"type":"string","description":"Automation icon color"},"instructions":{"type":"string","description":"Automation instructions"},"active":{"type":"boolean","description":"Whether the automation is enabled"},"archivedAt":{"type":["string","null"],"format":"date-time","description":"Archive timestamp, if archived"},"trigger":{"$ref":"#/components/schemas/PublicAutomationTrigger"},"notifications":{"$ref":"#/components/schemas/PublicAutomationNotifications"},"createdByMemberId":{"type":"string","description":"Member ID that created the automation"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}},"required":["id","organizationId","name","icon","color","instructions","active","archivedAt","trigger","notifications","createdByMemberId","createdAt","updatedAt"]},"PublicAutomationTrigger":{"type":"object","properties":{"type":{"type":"string","enum":["MANUAL","SCHEDULE","DATA_CHANGE"],"description":"Automation trigger type"},"frequency":{"type":"string","enum":["DAILY","WEEKDAYS","WEEKLY","MONTHLY","QUARTERLY"],"description":"Schedule frequency for scheduled automations"},"preferredHour":{"type":"integer","minimum":0,"maximum":23,"description":"Preferred UTC hour for scheduled runs"},"preferredDayOfWeek":{"type":["integer","null"],"minimum":0,"maximum":6,"description":"Preferred day of week for weekly schedules, where 0 is Sunday"},"preferredDayOfMonth":{"type":["integer","null"],"minimum":1,"maximum":31,"description":"Preferred day of month for monthly schedules"},"databaseConnectionId":{"type":["string","null"],"description":"Data source ID for data change triggers"},"sqlQuery":{"type":"string","description":"SQL query for data change triggers"}},"required":["type","frequency","preferredHour","preferredDayOfWeek","preferredDayOfMonth","databaseConnectionId","sqlQuery"]},"PublicAutomationNotifications":{"type":"object","properties":{"slackChannel":{"type":["string","null"],"description":"Slack channel for automation notifications"},"emailRecipients":{"type":"string","description":"Comma-separated email recipients for automation notifications"}},"required":["slackChannel","emailRecipients"]},"PublicAutomationResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PublicAutomation"}},"required":["data"]},"CreateAutomationInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Automation name"},"icon":{"type":"string","default":"stopwatch","description":"Icon name"},"color":{"type":"string","default":"1","description":"Icon color"},"instructions":{"type":"string","description":"Automation instructions"},"active":{"type":"boolean","default":true},"triggerType":{"type":"string","enum":["MANUAL","SCHEDULE","DATA_CHANGE"],"default":"SCHEDULE","description":"Automation trigger type"},"frequency":{"type":"string","enum":["DAILY","WEEKDAYS","WEEKLY","MONTHLY","QUARTERLY"],"default":"DAILY","description":"Schedule frequency"},"preferredHour":{"type":"integer","minimum":0,"maximum":23,"default":9,"description":"Preferred UTC hour"},"preferredDayOfWeek":{"type":["integer","null"],"minimum":0,"maximum":6},"preferredDayOfMonth":{"type":["integer","null"],"minimum":1,"maximum":31},"triggerDatabaseConnectionId":{"type":["string","null"],"default":null},"triggerSqlQuery":{"type":"string","default":""},"slackChannel":{"type":["string","null"],"default":null},"emailRecipients":{"type":"string","default":""}},"required":["name","instructions"]},"UpdateAutomationInput":{"type":"object","properties":{"name":{"type":"string","minLength":1},"icon":{"type":"string"},"color":{"type":"string"},"instructions":{"type":"string"},"active":{"type":"boolean"},"triggerType":{"type":"string","enum":["MANUAL","SCHEDULE","DATA_CHANGE"]},"frequency":{"type":"string","enum":["DAILY","WEEKDAYS","WEEKLY","MONTHLY","QUARTERLY"]},"preferredHour":{"type":"integer","minimum":0,"maximum":23},"preferredDayOfWeek":{"type":["integer","null"],"minimum":0,"maximum":6},"preferredDayOfMonth":{"type":["integer","null"],"minimum":1,"maximum":31},"triggerDatabaseConnectionId":{"type":["string","null"]},"triggerSqlQuery":{"type":"string"},"slackChannel":{"type":["string","null"]},"emailRecipients":{"type":"string"}}},"PublicAutomationRunListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicAutomationRun"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]},"PublicAutomationRun":{"type":"object","properties":{"id":{"type":"string","description":"Automation run ID"},"automationId":{"type":"string","description":"Automation ID"},"organizationId":{"type":"string","description":"Organization ID"},"name":{"type":"string","description":"Run name"},"status":{"type":["string","null"],"enum":["GENERATING","FINISHED",null],"description":"Run status"},"isManualRun":{"type":"boolean","description":"Whether the run was manually triggered"},"memberId":{"type":["string","null"],"description":"Member ID associated with the run"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}},"required":["id","automationId","organizationId","name","status","isManualRun","memberId","createdAt","updatedAt"]},"CreateAutomationRunResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PublicAutomationRun"}},"required":["data"]},"PublicAutomationRunResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PublicAutomationRunDetail"}},"required":["data"]},"PublicAutomationRunDetail":{"allOf":[{"$ref":"#/components/schemas/PublicAutomationRun"},{"type":"object","properties":{"finalMessageContent":{"type":["string","null"],"description":"Final assistant response content for the automation run"}},"required":["finalMessageContent"]}]},"DefinitionResponse":{"type":"object","properties":{"id":{"type":"string","description":"Definition ID"},"createdAt":{"type":"string","format":"date-time","description":"Definition creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Definition last update timestamp"},"name":{"type":"string","description":"Human-readable definition name"},"referenceName":{"type":"string","description":"Stable SQL reference name for the definition"},"description":{"type":"string","description":"Definition description"},"sqlQuery":{"type":"string","description":"SQL query for the latest definition version"},"organizationId":{"type":"string","description":"Organization ID"},"databaseConnectionId":{"type":"string","description":"Data source ID"}},"required":["id","createdAt","updatedAt","name","referenceName","description","sqlQuery","organizationId","databaseConnectionId"]},"CreateDefinitionInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Human-readable definition name"},"referenceName":{"type":"string","minLength":1,"maxLength":100,"description":"Stable SQL reference name for the definition"},"description":{"type":"string","maxLength":10000,"description":"Definition description"},"databaseConnectionId":{"type":"string","description":"Data source ID"},"sqlQuery":{"type":"string","minLength":1,"maxLength":100000,"description":"SQL query that defines the reusable dataset"}},"required":["name","databaseConnectionId","sqlQuery"]},"UpdateDefinitionInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Human-readable definition name"},"referenceName":{"type":"string","minLength":1,"maxLength":100,"description":"Stable SQL reference name for the definition"},"description":{"type":"string","maxLength":10000,"description":"Definition description"},"sqlQuery":{"type":"string","minLength":1,"maxLength":100000,"description":"SQL query that defines the reusable dataset"}}},"PublicAuditLogListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicAuditLogEvent"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]},"PublicAuditLogEvent":{"type":"object","properties":{"id":{"type":"string","description":"Audit event ID"},"createdAt":{"type":"string","format":"date-time","description":"Event timestamp"},"organizationId":{"type":"string","description":"Organization ID"},"action":{"type":"string","description":"Stable dot-namespaced action name"},"category":{"type":"string","enum":["AUTHENTICATION","MEMBERS","ACCESS_CONTROL","DATA_SOURCES","QUERIES","EXPORTS","AI","ORGANIZATION","CONTENT","INTEGRATIONS"]},"actorType":{"type":"string","enum":["USER","API_KEY","SCIM","SYSTEM","ANONYMOUS"]},"actorUserId":{"type":["string","null"]},"actorEmail":{"type":["string","null"]},"apiKeyId":{"type":["string","null"]},"scimTokenId":{"type":["string","null"]},"targetType":{"type":["string","null"]},"targetId":{"type":["string","null"]},"targetDisplay":{"type":["string","null"]},"source":{"type":"string","enum":["WEB","PUBLIC_API","SCIM","SLACK","MCP","SYSTEM","PUBLIC_DASHBOARD"]},"ipAddress":{"type":["string","null"]},"userAgent":{"type":["string","null"]},"metadata":{}},"required":["id","createdAt","organizationId","action","category","actorType","actorUserId","actorEmail","apiKeyId","scimTokenId","targetType","targetId","targetDisplay","source","ipAddress","userAgent"]},"DashboardResponse":{"type":"object","properties":{"id":{"type":"string","description":"Dashboard ID"},"createdAt":{"type":"string","format":"date-time","description":"Dashboard creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Dashboard last update timestamp"},"name":{"type":"string","description":"Name of the dashboard"},"description":{"type":["string","null"],"description":"Description of the dashboard"},"icon":{"type":"string","description":"Icon name for the dashboard"},"color":{"type":"string","description":"Icon color key for the dashboard"},"dashboardFolderId":{"type":["string","null"],"description":"ID of the folder the dashboard is in"},"width":{"$ref":"#/components/schemas/DashboardWidth"},"defaultDateRange":{"$ref":"#/components/schemas/DateRange"},"defaultCustomDateRangeStart":{"type":["string","null"],"format":"date-time","description":"Start of the custom date range"},"defaultCustomDateRangeEnd":{"type":["string","null"],"format":"date-time","description":"End of the custom date range"},"defaultGroupByInterval":{"$ref":"#/components/schemas/GroupByInterval"},"organizationId":{"type":"string","description":"Organization ID"}},"required":["id","createdAt","updatedAt","name","description","icon","color","dashboardFolderId","width","defaultDateRange","defaultCustomDateRangeStart","defaultCustomDateRangeEnd","defaultGroupByInterval","organizationId"]},"DashboardWidth":{"anyOf":[{"type":"string","enum":["NORMAL"]},{"type":"string","enum":["WIDE"]},{"type":"string","enum":["ULTRAWIDE"]}],"description":"Width of the dashboard grid"},"DateRange":{"anyOf":[{"type":"string","enum":["CUSTOM"]},{"type":"string","enum":["TODAY"]},{"type":"string","enum":["YESTERDAY"]},{"type":"string","enum":["THIS_WEEK"]},{"type":"string","enum":["THIS_MONTH"]},{"type":"string","enum":["THIS_QUARTER"]},{"type":"string","enum":["THIS_YEAR"]},{"type":"string","enum":["LAST_7_DAYS"]},{"type":"string","enum":["LAST_30_DAYS"]},{"type":"string","enum":["LAST_60_DAYS"]},{"type":"string","enum":["LAST_90_DAYS"]},{"type":"string","enum":["LAST_6_MONTHS"]},{"type":"string","enum":["LAST_1_YEAR"]},{"type":"string","enum":["ALL_TIME"]}],"description":"Default date range applied to the dashboard"},"GroupByInterval":{"anyOf":[{"type":"string","enum":["HOUR"]},{"type":"string","enum":["DAY"]},{"type":"string","enum":["WEEK"]},{"type":"string","enum":["MONTH"]},{"type":"string","enum":["YEAR"]}],"description":"Default group-by interval applied to the dashboard"},"DashboardWithTabsResponse":{"allOf":[{"$ref":"#/components/schemas/DashboardResponse"},{"type":"object","properties":{"tabs":{"type":"array","items":{"$ref":"#/components/schemas/DashboardTab"},"description":"Tabs on the dashboard, ordered by their sort order"}},"required":["tabs"]}]},"DashboardTab":{"type":"object","properties":{"id":{"type":"string","description":"Dashboard tab ID"},"createdAt":{"type":"string","format":"date-time","description":"Tab creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Tab last update timestamp"},"name":{"type":"string","description":"Name of the tab"},"order":{"type":"number","description":"Sort order of the tab within the dashboard"},"dashboardId":{"type":"string","description":"ID of the dashboard the tab belongs to"}},"required":["id","createdAt","updatedAt","name","order","dashboardId"]},"CreateDashboardInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Name of the dashboard"},"description":{"type":["string","null"],"description":"Optional description of the dashboard"},"icon":{"type":"string","minLength":1,"description":"Icon name for the dashboard"},"color":{"type":"string","minLength":1,"description":"Icon color key for the dashboard"},"dashboardFolderId":{"type":["string","null"],"description":"ID of the folder to place the dashboard in"},"width":{"$ref":"#/components/schemas/DashboardWidth"},"defaultDateRange":{"$ref":"#/components/schemas/DateRange"},"defaultCustomDateRangeStart":{"type":["string","null"],"format":"date-time","description":"Start of the custom date range (when defaultDateRange is CUSTOM)"},"defaultCustomDateRangeEnd":{"type":["string","null"],"format":"date-time","description":"End of the custom date range (when defaultDateRange is CUSTOM)"},"defaultGroupByInterval":{"$ref":"#/components/schemas/GroupByInterval"}},"required":["name"]},"ChartResponse":{"type":"object","properties":{"id":{"type":"string","description":"Chart ID"},"createdAt":{"type":"string","format":"date-time","description":"Chart creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp of the last content or placement change"},"dashboardId":{"type":"string","description":"ID of the dashboard the chart is on"},"dashboardTabId":{"type":"string","description":"ID of the dashboard tab the chart is on"},"organizationId":{"type":"string","description":"Organization ID"},"name":{"type":"string","description":"Name of the chart"},"description":{"type":["string","null"],"description":"Description of the chart"},"chartType":{"$ref":"#/components/schemas/SqlChartType"},"sqlQuery":{"type":"string","description":"SQL query powering the chart"},"drilldownSqlQuery":{"type":["string","null"],"description":"SQL query used for chart drill-downs"},"databaseConnectionId":{"type":["string","null"],"description":"ID of the data source the SQL query runs against"},"xAxisProperty":{"type":["string","null"],"description":"Result column used for the x-axis"},"xAxisSecondaryProperty":{"type":["string","null"],"description":"Result column used to break down the x-axis into segments"},"yAxisProperty":{"type":["string","null"],"description":"Result column used for the y-axis"},"staticContent":{"type":["string","null"],"description":"Static content for DASHBOARD_HEADER and DASHBOARD_TEXT chart types"},"layout":{"$ref":"#/components/schemas/ChartLayout"},"imageUrl":{"type":"string","format":"uri","description":"URL that renders this chart as a PNG image (the \"Get a chart image\" endpoint). Request it with the same API key authentication."}},"required":["id","createdAt","updatedAt","dashboardId","dashboardTabId","organizationId","name","description","chartType","sqlQuery","drilldownSqlQuery","databaseConnectionId","xAxisProperty","xAxisSecondaryProperty","yAxisProperty","staticContent","layout","imageUrl"]},"SqlChartType":{"anyOf":[{"type":"string","enum":["TABLE"]},{"type":"string","enum":["LINE"]},{"type":"string","enum":["VERTICAL_BAR"]},{"type":"string","enum":["HORIZONTAL_BAR"]},{"type":"string","enum":["SCATTER"]},{"type":"string","enum":["FUNNEL"]},{"type":"string","enum":["NUMBER"]},{"type":"string","enum":["PROGRESS"]},{"type":"string","enum":["IMAGE"]},{"type":"string","enum":["RECORD"]},{"type":"string","enum":["TEXT"]},{"type":"string","enum":["PIE"]},{"type":"string","enum":["ACTIVITY"]},{"type":"string","enum":["MAP"]},{"type":"string","enum":["SANKEY"]},{"type":"string","enum":["DASHBOARD_HEADER"]},{"type":"string","enum":["DASHBOARD_TEXT"]},{"type":"null"}],"description":"Type of the chart"},"ChartLayout":{"type":"object","properties":{"x":{"type":"integer","minimum":0,"description":"Column position on the dashboard grid"},"y":{"type":"integer","minimum":0,"description":"Row position on the dashboard grid"},"width":{"type":"integer","minimum":1,"description":"Width of the chart in grid units"},"height":{"type":"integer","minimum":1,"description":"Height of the chart in grid units"}},"required":["x","y","width","height"]},"CreateChartInput":{"type":"object","properties":{"dashboardId":{"type":"string","minLength":1,"description":"ID of the dashboard to place the chart on"},"dashboardTabId":{"type":"string","description":"ID of the dashboard tab to place the chart on. Defaults to the first tab."},"layout":{"$ref":"#/components/schemas/ChartLayoutInput"},"name":{"type":"string","minLength":1,"description":"Name of the chart"},"description":{"type":["string","null"],"description":"Description of the chart"},"chartType":{"$ref":"#/components/schemas/SqlChartType"},"sqlQuery":{"type":"string","description":"SQL query powering the chart"},"drilldownSqlQuery":{"type":["string","null"],"description":"SQL query used for chart drill-downs"},"databaseConnectionId":{"type":["string","null"],"description":"ID of the data source the SQL query runs against"},"xAxisProperty":{"type":["string","null"],"description":"Result column used for the x-axis"},"xAxisSecondaryProperty":{"type":["string","null"],"description":"Result column used to break down the x-axis into segments"},"yAxisProperty":{"type":["string","null"],"description":"Result column used for the y-axis"},"staticContent":{"type":["string","null"],"description":"Static content for DASHBOARD_HEADER and DASHBOARD_TEXT chart types"}},"required":["dashboardId"]},"ChartLayoutInput":{"type":"object","properties":{"x":{"type":"integer","minimum":0,"description":"Column position on the dashboard grid"},"y":{"type":"integer","minimum":0,"description":"Row position on the dashboard grid"},"width":{"type":"integer","minimum":1,"description":"Width of the chart in grid units"},"height":{"type":"integer","minimum":1,"description":"Height of the chart in grid units"}},"description":"Position and size of the chart on the dashboard grid. Defaults to the bottom of the tab."},"CreateDashboardTabInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Name of the tab"},"order":{"type":"number","description":"Sort order of the tab within the dashboard. Defaults to placing the tab last."}},"required":["name"]},"UpdateDashboardTabInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Name of the tab"},"order":{"type":"number","description":"Sort order of the tab within the dashboard. Defaults to placing the tab last."}}},"UpdateDashboardInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Name of the dashboard"},"description":{"type":["string","null"],"description":"Optional description of the dashboard"},"icon":{"type":"string","minLength":1,"description":"Icon name for the dashboard"},"color":{"type":"string","minLength":1,"description":"Icon color key for the dashboard"},"dashboardFolderId":{"type":["string","null"],"description":"ID of the folder to place the dashboard in"},"width":{"$ref":"#/components/schemas/DashboardWidth"},"defaultDateRange":{"$ref":"#/components/schemas/DateRange"},"defaultCustomDateRangeStart":{"type":["string","null"],"format":"date-time","description":"Start of the custom date range (when defaultDateRange is CUSTOM)"},"defaultCustomDateRangeEnd":{"type":["string","null"],"format":"date-time","description":"End of the custom date range (when defaultDateRange is CUSTOM)"},"defaultGroupByInterval":{"$ref":"#/components/schemas/GroupByInterval"}}},"PublicAiUsageResponse":{"type":"object","properties":{"totalUsage":{"type":"number","description":"Total billable AI usage for the billing period in USD dollars"},"billingPeriodStart":{"type":"string","format":"date-time","description":"Billing period start timestamp"},"billingPeriodEnd":{"type":"string","format":"date-time","description":"Billing period end timestamp"},"memberUsage":{"type":"array","items":{"$ref":"#/components/schemas/PublicAiUsageMember"},"description":"Billable AI usage grouped by organization member"}},"required":["totalUsage","billingPeriodStart","billingPeriodEnd","memberUsage"]},"PublicAiUsageMember":{"type":"object","properties":{"userId":{"type":"string","description":"User ID"},"memberId":{"type":"string","description":"Organization member ID"},"email":{"type":"string","description":"Email address of the member"},"usage":{"type":"number","description":"Billable AI usage for this member in USD dollars"}},"required":["userId","memberId","email","usage"]},"PublicInsightListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicInsightListItem"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]},"PublicInsightListItem":{"type":"object","properties":{"id":{"type":"string","description":"Insight ID"},"organizationId":{"type":"string","description":"Organization ID"},"title":{"type":"string","description":"Insight title"},"chartId":{"type":"string","description":"Chart ID"},"chart":{"type":"object","properties":{"id":{"type":"string","description":"Chart ID"},"versionId":{"type":["string","null"],"description":"Latest chart version ID"},"name":{"type":["string","null"],"description":"Latest chart version name"},"type":{"type":["string","null"],"description":"Chart type"}},"required":["id","versionId","name","type"],"description":"Basic chart information"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}},"required":["id","organizationId","title","chartId","chart","createdAt","updatedAt"]},"GenerateInsightDataResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GenerateInsightResponse"}},"required":["data"]},"GenerateInsightResponse":{"type":"object","properties":{"insightId":{"type":["string","null"],"description":"Deterministic insight ID for the generated job"},"alreadyGenerating":{"type":"boolean","description":"Whether an insight generation job is already queued"}},"required":["insightId","alreadyGenerating"]},"PublicInsightDetailResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PublicInsightDetail"}},"required":["data"]},"PublicInsightDetail":{"allOf":[{"$ref":"#/components/schemas/PublicInsightListItem"},{"type":"object","properties":{"chart":{"$ref":"#/components/schemas/PublicInsightChart"},"bodyMarkdown":{"type":"string","description":"Insight body as Markdown"},"sourceMeta":{"description":"Insight generation metadata"},"rawData":{"$ref":"#/components/schemas/PublicInsightRawData"}},"required":["bodyMarkdown","rawData"]}]},"PublicInsightChart":{"type":"object","properties":{"id":{"type":"string","description":"Chart ID"},"versionId":{"type":["string","null"],"description":"Latest chart version ID"},"name":{"type":["string","null"],"description":"Latest chart version name"},"type":{"type":["string","null"],"description":"Chart type"},"sqlQuery":{"type":["string","null"],"description":"SQL query used by the chart"},"databaseConnectionId":{"type":["string","null"],"description":"Data source ID used by the chart"},"imageUrl":{"type":["string","null"],"format":"uri","description":"URL that renders the latest chart version as a PNG image (the \"Get a chart image\" endpoint). Request it with the same API key authentication."}},"required":["id","versionId","name","type","sqlQuery","databaseConnectionId","imageUrl"],"description":"Chart information"},"PublicInsightRawData":{"type":["object","null"],"properties":{"rows":{"type":"array","items":{"type":"object","additionalProperties":{},"description":"A raw chart data row"},"description":"Raw chart rows"},"count":{"type":"number","description":"Total row count for the chart query"},"page":{"type":"number","description":"Raw data page number"},"limit":{"type":"number","description":"Maximum raw rows returned"}},"required":["rows","count","page","limit"],"description":"Raw data returned by the insight chart query"},"MemberResponse":{"type":"object","properties":{"id":{"type":"string","description":"Member ID"},"createdAt":{"type":"string","format":"date-time","description":"Member creation timestamp"},"deactivatedAt":{"type":["string","null"],"format":"date-time","description":"When the member was deactivated, if applicable"},"role":{"anyOf":[{"type":"string","enum":["MEMBER"]},{"type":"string","enum":["ADMIN"]}],"description":"Role of the member in the organization"},"userId":{"type":"string","description":"ID of the associated user"},"organizationId":{"type":"string","description":"ID of the organization"},"user":{"$ref":"#/components/schemas/UserResponse"}},"required":["id","createdAt","deactivatedAt","role","userId","organizationId","user"]},"UserResponse":{"type":"object","properties":{"id":{"type":"string","description":"User ID"},"fullName":{"type":"string","description":"Full name of the user"},"avatarUrl":{"type":["string","null"],"description":"URL to the user avatar image"},"email":{"type":"string","description":"Email address of the user"},"isEmailVerified":{"type":"boolean","description":"Whether the user has verified their email"},"createdAt":{"type":"string","format":"date-time","description":"User creation timestamp"},"firstName":{"type":["string","null"],"description":"First name of the user"},"title":{"type":["string","null"],"description":"Job title of the user"}},"required":["id","fullName","avatarUrl","email","isEmailVerified","createdAt","firstName","title"],"description":"User information for this member"},"InviteMemberInput":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Email address of the user to invite"},"role":{"anyOf":[{"type":"string","enum":["MEMBER"]},{"type":"string","enum":["ADMIN"]}],"default":"MEMBER","description":"Role to assign to the invited member"}},"required":["email"]},"UpdateMemberInput":{"type":"object","properties":{"role":{"anyOf":[{"type":"string","enum":["MEMBER"]},{"type":"string","enum":["ADMIN"]}],"description":"Updated role for the member"},"fullName":{"type":"string","minLength":1,"description":"Updated full name for the member user"},"avatarUrl":{"type":["string","null"],"description":"Updated allowed HTTPS avatar URL for the member user"}}},"UpdateChartInput":{"type":"object","properties":{"dashboardId":{"type":"string","description":"ID of the dashboard to move the chart to"},"dashboardTabId":{"type":"string","description":"ID of the dashboard tab to move the chart to"},"layout":{"allOf":[{"$ref":"#/components/schemas/ChartLayoutInput"},{"description":"Position and size of the chart on the dashboard grid"}]},"name":{"type":"string","minLength":1,"description":"Name of the chart"},"description":{"type":["string","null"],"description":"Description of the chart"},"chartType":{"$ref":"#/components/schemas/SqlChartType"},"sqlQuery":{"type":"string","description":"SQL query powering the chart"},"drilldownSqlQuery":{"type":["string","null"],"description":"SQL query used for chart drill-downs"},"databaseConnectionId":{"type":["string","null"],"description":"ID of the data source the SQL query runs against"},"xAxisProperty":{"type":["string","null"],"description":"Result column used for the x-axis"},"xAxisSecondaryProperty":{"type":["string","null"],"description":"Result column used to break down the x-axis into segments"},"yAxisProperty":{"type":["string","null"],"description":"Result column used for the y-axis"},"staticContent":{"type":["string","null"],"description":"Static content for DASHBOARD_HEADER and DASHBOARD_TEXT chart types"}}},"GroupResponse":{"type":"object","properties":{"id":{"type":"string","description":"Group ID"},"createdAt":{"type":"string","format":"date-time","description":"Group creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Group last update timestamp"},"name":{"type":"string","description":"Name of the group"},"description":{"type":["string","null"],"description":"Description of the group"},"organizationId":{"type":"string","description":"Organization ID"},"memberCount":{"type":"integer","minimum":0,"description":"Number of active organization members currently in the group"}},"required":["id","createdAt","updatedAt","name","description","organizationId","memberCount"]},"GroupMembershipResponse":{"type":"object","properties":{"id":{"type":"string","description":"Group membership ID"},"createdAt":{"type":"string","format":"date-time","description":"Group membership creation timestamp"},"groupId":{"type":"string","description":"Group ID"},"memberId":{"type":"string","description":"Organization member ID"},"organizationId":{"type":"string","description":"Organization ID"}},"required":["id","createdAt","groupId","memberId","organizationId"]},"SkillResponse":{"type":"object","properties":{"id":{"type":"string","description":"Skill ID"},"createdAt":{"type":"string","format":"date-time","description":"Skill creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Skill last update timestamp"},"name":{"type":"string","description":"Human-readable skill name"},"description":{"type":["string","null"],"description":"Routing description that explains when the skill should be used"},"instructions":{"type":"string","description":"Full reusable skill instructions"},"organizationId":{"type":"string","description":"Organization ID"}},"required":["id","createdAt","updatedAt","name","description","instructions","organizationId"]},"CreateSkillInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Human-readable skill name"},"description":{"type":["string","null"],"minLength":1,"maxLength":1024,"description":"Optional routing description for the skill"},"instructions":{"type":"string","minLength":1,"maxLength":50000,"description":"Full reusable skill instructions"}},"required":["name","instructions"]},"UpdateSkillInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Human-readable skill name"},"description":{"type":["string","null"],"minLength":1,"maxLength":1024,"description":"Optional routing description for the skill"},"instructions":{"type":"string","minLength":1,"maxLength":50000,"description":"Full reusable skill instructions"}}},"PublicChatListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicChat"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]},"PublicChat":{"type":"object","properties":{"id":{"type":"string","description":"Chat ID"},"organizationId":{"type":"string","description":"Organization ID"},"name":{"type":"string","description":"Chat name, generated automatically from the first message"},"status":{"$ref":"#/components/schemas/PublicChatStatus"},"source":{"type":"string","enum":["api"],"description":"Chat creation source"},"memberId":{"type":["string","null"],"description":"Creating member ID"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}},"required":["id","organizationId","name","status","source","memberId","createdAt","updatedAt"]},"PublicChatStatus":{"type":"string","enum":["generating","finished"],"description":"`generating` while the assistant is responding, `finished` otherwise"},"PublicChatTurnResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PublicChatTurn"}},"required":["data"]},"PublicChatTurn":{"type":"object","properties":{"chat":{"allOf":[{"$ref":"#/components/schemas/PublicChat"},{"description":"The chat this exchange belongs to"}]},"userMessage":{"$ref":"#/components/schemas/PublicChatMessage"},"assistantMessage":{"allOf":[{"$ref":"#/components/schemas/PublicChatMessage"},{"description":"The assistant's response. Check its status to see whether it has finished responding."}]}},"required":["chat","userMessage","assistantMessage"]},"PublicChatMessage":{"type":"object","properties":{"id":{"type":"string","description":"Chat message ID"},"chatId":{"type":"string","description":"Chat ID"},"role":{"type":"string","enum":["user","assistant"],"description":"Message author role"},"status":{"$ref":"#/components/schemas/PublicChatMessageStatus"},"parentId":{"type":["string","null"],"description":"User message ID associated with an assistant response"},"text":{"type":"string","description":"The message as plain text. For assistant messages this is the final answer, without reasoning or tool activity; see parts for the full structured content."},"parts":{"type":"array","items":{"$ref":"#/components/schemas/PublicChatContentPart"},"description":"Ordered structured message content"},"charts":{"type":"array","items":{"$ref":"#/components/schemas/PublicChatChart"},"description":"Charts referenced by the assistant response"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}},"required":["id","chatId","role","status","parentId","text","parts","charts","createdAt","updatedAt"],"description":"The message you sent"},"PublicChatMessageStatus":{"type":"string","enum":["generating","finished","aborted","error","action_required"],"description":"`generating` while the assistant is responding, `finished` when the response is complete, `aborted` if it was canceled, `error` if it failed, and `action_required` if the assistant is waiting on a confirmation it cannot receive over the API"},"PublicChatContentPart":{"type":"object","properties":{"id":{"type":"string","description":"Content part ID"},"type":{"type":"string","enum":["text","reasoning_summary","tool_call","tool_call_result","context","action","image","file"],"description":"Content part type"},"content":{"type":"string","description":"Text content or a JSON-encoded payload for structured part types"},"externalId":{"type":["string","null"],"description":"Provider item or tool call ID, when present"},"name":{"type":["string","null"],"description":"Tool or content part name"},"phase":{"type":["string","null"],"enum":["commentary","final_answer",null],"description":"Assistant response phase"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}},"required":["id","type","content","externalId","name","phase","createdAt","updatedAt"]},"PublicChatChart":{"type":"object","properties":{"chartId":{"type":"string","description":"Chart ID"},"chartVersionId":{"type":"string","description":"Chart version ID"},"title":{"type":"string","description":"Chart title"},"imageUrl":{"type":"string","format":"uri","description":"URL that renders this chart as a PNG. Request it with the same API key authentication."},"mimeType":{"type":"string","description":"Screenshot MIME type"},"width":{"type":"integer","exclusiveMinimum":0,"description":"Screenshot width"},"height":{"type":"integer","exclusiveMinimum":0,"description":"Screenshot height"}},"required":["chartId","chartVersionId","title","imageUrl","mimeType","width","height"]},"CreatePublicChatInput":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":10000,"description":"The message to send to the AI agent, e.g. a question about your data. Maximum 10,000 characters."}},"required":["message"]},"PublicChatResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PublicChat"}},"required":["data"]},"PublicChatMessageListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicChatMessage"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]},"SendPublicChatMessageInput":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":10000,"description":"The follow-up message to send to the AI agent. Maximum 10,000 characters."}},"required":["message"]},"PublicChatMessageResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PublicChatMessage"}},"required":["data"]}},"parameters":{}},"paths":{"/api/public/organizations":{"get":{"summary":"List organizations","description":"Lists all organizations where the authenticated user is a member. Results are paginated and ordered by creation date (newest first).","tags":["Organizations"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Maximum number of items to return (1-100, default 50)"},"required":false,"description":"Maximum number of items to return (1-100, default 50)","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination (ID of the last item from previous page)"},"required":false,"description":"Cursor for pagination (ID of the last item from previous page)","name":"cursor","in":"query"},{"schema":{"type":"string","enum":["jwtSecret"],"description":"Include sensitive fields in the response. Use `jwtSecret` to include the embed JWT secret (only included for organizations where the user is an admin)."},"required":false,"description":"Include sensitive fields in the response. Use `jwtSecret` to include the embed JWT secret (only included for organizations where the user is an admin).","name":"include","in":"query"}],"responses":{"200":{"description":"Organizations retrieved successfully. The `jwtSecret` field is only included when explicitly requested via `?include=jwtSecret` and only for organizations where the user is an admin.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Organization ID"},"name":{"type":"string","description":"Name of the organization"},"slug":{"type":"string","description":"URL-friendly slug"},"customAiContext":{"type":["string","null"],"description":"Custom context for AI"},"insightsAiContext":{"type":["string","null"],"description":"Custom context injected into AI-generated insights"},"onboardingStatus":{"type":"string","enum":["LEGACY","STARTED","COMPLETED"],"description":"Onboarding status"},"fullEmbedEnabled":{"type":"boolean","description":"Full embed enabled flag"},"embedAllowedOrigins":{"type":"array","items":{"type":"string"},"description":"Allowed embed origins"},"isBillable":{"type":"boolean","description":"[Self-hosted] Whether the organization is billable. Defaults to true. Relevant for self-hosted deployments where billing gates certain features. When false, the organization will not be counted towards billable usage and will have a limited set of features. When true, the organization will be counted towards billable usage (after a 14-day trial) and will have access to all features."},"insightsEnabled":{"type":"boolean","description":"Whether automated insights generation is enabled for this organization."},"insightsFrequency":{"type":"string","enum":["DAILY","WEEKDAYS","WEEKLY","MONTHLY","NEVER"],"description":"How often automated insights are generated. NEVER means automatic generation is disabled."},"insightsPreferredDayOfWeek":{"type":["number","null"],"description":"Preferred day of week for weekly insights. 0 is Sunday."},"insightsPreferredDayOfMonth":{"type":["number","null"],"description":"Preferred day of month for monthly insights."},"allowOnDemandAiUsage":{"type":"boolean","description":"Whether the organization can continue using AI beyond included monthly AI credits."},"aiUsageOverageLimitCents":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":2147483647,"description":"Maximum AI usage overage for the organization in cents. Null means no limit."},"billingEmail":{"type":"string","description":"Email address used for billing communication and invoices"},"sendInvoicesToBillingEmail":{"type":"boolean","description":"Whether paid invoices are emailed to the billing email address"},"defaultDashboardAccessAudience":{"type":"string","enum":["EVERYONE","CREATOR_ONLY","CREATOR_GROUPS"],"description":"Default audience for newly created dashboards"},"defaultDashboardAccessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW"],"description":"Default permission level for the audience. Creator always gets MANAGE regardless."},"defaultChatAccessAudience":{"type":"string","enum":["EVERYONE","CREATOR_ONLY","CREATOR_GROUPS"],"description":"Default audience for newly created chats"},"defaultChatAccessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW"],"description":"Default permission level for new chats. Creator always gets MANAGE regardless."},"defaultAutomationAccessAudience":{"type":"string","enum":["EVERYONE","CREATOR_ONLY","CREATOR_GROUPS"],"description":"Default audience for newly created automations"},"defaultAutomationAccessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW"],"description":"Default permission level for new automations. Creator always gets MANAGE regardless."},"trialEndsAt":{"type":["string","null"],"description":"[Self-hosted] ISO 8601 date when the trial ends, or null if no trial. Trial starts after the organization is created and becomes billable."},"jwtSecret":{"type":"string","description":"JWT secret for embedding"}},"required":["id","name","slug","customAiContext","insightsAiContext","onboardingStatus","fullEmbedEnabled","embedAllowedOrigins","isBillable","insightsEnabled","insightsFrequency","insightsPreferredDayOfWeek","insightsPreferredDayOfMonth","allowOnDemandAiUsage","aiUsageOverageLimitCents","billingEmail","sendInvoicesToBillingEmail","defaultDashboardAccessAudience","defaultDashboardAccessLevel","defaultChatAccessAudience","defaultChatAccessLevel","defaultAutomationAccessAudience","defaultAutomationAccessLevel","trialEndsAt"]}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an organization","description":"Creates a new organization. The authenticated user becomes an admin.","tags":["Organizations"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["jwtSecret"],"description":"Include sensitive fields in the response. Use `jwtSecret` to include the embed JWT secret."},"required":false,"description":"Include sensitive fields in the response. Use `jwtSecret` to include the embed JWT secret.","name":"include","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Name of the organization"},"customAiContext":{"type":"string","description":"Custom context for AI features"},"insightsAiContext":{"type":["string","null"],"description":"Custom context for AI-generated insights"},"skipOnboarding":{"type":"boolean","description":"Skip onboarding flow"},"fullEmbedEnabled":{"type":"boolean","description":"Enable full embed functionality"},"embedAllowedOrigins":{"type":"array","items":{"type":"string"},"description":"Allowed origins for embedding. Supports exact URLs (https://example.com) and wildcard patterns (https://*.example.com)"},"slug":{"type":"string","description":"URL-friendly slug. If not provided, a unique slug will be generated."},"isBillable":{"type":"boolean","description":"[Self-hosted] Controls whether the organization is billable. Defaults to true. Relevant for self-hosted deployments where billing gates certain features. When false, the organization will not be counted towards billable usage and will have a limited set of features. When true, the organization will be counted towards billable usage (after a 14-day trial) and will have access to all features."},"insightsEnabled":{"type":"boolean","description":"Enable automated insights generation for this organization. Defaults to true."},"insightsFrequency":{"type":"string","enum":["DAILY","WEEKDAYS","WEEKLY","MONTHLY","NEVER"],"description":"How often automated insights are generated. Defaults to DAILY."},"insightsPreferredDayOfWeek":{"type":"integer","minimum":0,"maximum":6,"description":"Preferred day of week for WEEKLY insights. 0 is Sunday."},"insightsPreferredDayOfMonth":{"type":"integer","minimum":1,"maximum":31,"description":"Preferred day of month for MONTHLY insights."},"allowOnDemandAiUsage":{"type":"boolean","description":"Allow users in the organization to continue using AI beyond included monthly AI credits. Defaults to true."},"aiUsageOverageLimitCents":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":2147483647,"description":"Maximum AI usage overage for the organization in cents. Null means no limit. Only applies when on-demand AI usage is enabled."},"billingEmail":{"type":"string","format":"email","description":"Email address used for billing communication and invoices"},"sendInvoicesToBillingEmail":{"type":"boolean","description":"Whether paid invoices are emailed to the billing email address"},"defaultDashboardAccessAudience":{"type":"string","enum":["EVERYONE","CREATOR_ONLY","CREATOR_GROUPS"],"description":"Default audience for newly created dashboards"},"defaultDashboardAccessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW"],"description":"Default permission level for the audience. Creator always gets MANAGE regardless."},"defaultChatAccessAudience":{"type":"string","enum":["EVERYONE","CREATOR_ONLY","CREATOR_GROUPS"],"description":"Default audience for newly created chats"},"defaultChatAccessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW"],"description":"Default permission level for new chats. Creator always gets MANAGE regardless."},"defaultAutomationAccessAudience":{"type":"string","enum":["EVERYONE","CREATOR_ONLY","CREATOR_GROUPS"],"description":"Default audience for newly created automations"},"defaultAutomationAccessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW"],"description":"Default permission level for new automations. Creator always gets MANAGE regardless."}},"required":["name"]}}}},"responses":{"201":{"description":"Organization created successfully. The `jwtSecret` field is only included when explicitly requested via `?include=jwtSecret`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Organization ID"},"name":{"type":"string","description":"Name of the organization"},"slug":{"type":"string","description":"URL-friendly slug"},"customAiContext":{"type":["string","null"],"description":"Custom context for AI"},"insightsAiContext":{"type":["string","null"],"description":"Custom context injected into AI-generated insights"},"onboardingStatus":{"type":"string","enum":["STARTED","COMPLETED"],"description":"Onboarding status"},"fullEmbedEnabled":{"type":"boolean","description":"Full embed enabled flag"},"embedAllowedOrigins":{"type":"array","items":{"type":"string"},"description":"Allowed embed origins"},"isBillable":{"type":"boolean","description":"[Self-hosted] Whether the organization is billable. Defaults to true. Relevant for self-hosted deployments where billing gates certain features. When false, the organization will not be counted towards billable usage and will have a limited set of features. When true, the organization will be counted towards billable usage (after a 14-day trial) and will have access to all features."},"insightsEnabled":{"type":"boolean","description":"Whether automated insights generation is enabled for this organization."},"insightsFrequency":{"type":"string","enum":["DAILY","WEEKDAYS","WEEKLY","MONTHLY","NEVER"],"description":"How often automated insights are generated. NEVER means automatic generation is disabled."},"insightsPreferredDayOfWeek":{"type":["number","null"],"description":"Preferred day of week for weekly insights. 0 is Sunday."},"insightsPreferredDayOfMonth":{"type":["number","null"],"description":"Preferred day of month for monthly insights."},"allowOnDemandAiUsage":{"type":"boolean","description":"Whether the organization can continue using AI beyond included monthly AI credits."},"aiUsageOverageLimitCents":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":2147483647,"description":"Maximum AI usage overage for the organization in cents. Null means no limit."},"billingEmail":{"type":"string","description":"Email address used for billing communication and invoices"},"sendInvoicesToBillingEmail":{"type":"boolean","description":"Whether paid invoices are emailed to the billing email address"},"defaultDashboardAccessAudience":{"type":"string","enum":["EVERYONE","CREATOR_ONLY","CREATOR_GROUPS"],"description":"Default audience for newly created dashboards"},"defaultDashboardAccessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW"],"description":"Default permission level for the audience. Creator always gets MANAGE regardless."},"defaultChatAccessAudience":{"type":"string","enum":["EVERYONE","CREATOR_ONLY","CREATOR_GROUPS"],"description":"Default audience for newly created chats"},"defaultChatAccessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW"],"description":"Default permission level for new chats. Creator always gets MANAGE regardless."},"defaultAutomationAccessAudience":{"type":"string","enum":["EVERYONE","CREATOR_ONLY","CREATOR_GROUPS"],"description":"Default audience for newly created automations"},"defaultAutomationAccessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW"],"description":"Default permission level for new automations. Creator always gets MANAGE regardless."},"trialEndsAt":{"type":["string","null"],"description":"[Self-hosted] ISO 8601 date when the trial ends, or null if no trial. Trial starts after the organization is created and becomes billable."},"jwtSecret":{"type":"string","description":"JWT secret for embedding"}},"required":["id","name","slug","customAiContext","insightsAiContext","onboardingStatus","fullEmbedEnabled","embedAllowedOrigins","isBillable","insightsEnabled","insightsFrequency","insightsPreferredDayOfWeek","insightsPreferredDayOfMonth","allowOnDemandAiUsage","aiUsageOverageLimitCents","billingEmail","sendInvoicesToBillingEmail","defaultDashboardAccessAudience","defaultDashboardAccessLevel","defaultChatAccessAudience","defaultChatAccessLevel","defaultAutomationAccessAudience","defaultAutomationAccessLevel","trialEndsAt"]}},"required":["data"]}}}},"400":{"description":"Bad request - Invalid JSON body or validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict - Slug already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/embedded-users/{userId}/avatar":{"post":{"summary":"Upload embedded user avatar","description":"Uploads an avatar image for a managed (embedded) user. Only users created via JWT SSO who have not logged in independently can have their avatars set through this endpoint. Requires admin access to the organization.","tags":["Embedding"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"User ID of the embedded user"},"required":true,"description":"User ID of the embedded user","name":"userId","in":"path"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"avatar":{"type":"string","format":"binary","description":"Image file (JPEG or PNG). Maximum size: 2 MB."}}}}}},"responses":{"200":{"description":"Avatar uploaded successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"avatarUrl":{"type":"string","description":"URL of the uploaded avatar"}},"required":["avatarUrl"]}},"required":["data"]}}}},"400":{"description":"Bad request - Invalid file type, missing file, or malformed request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - User not found, not an embedded user, or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Payload too large - File size exceeds 2 MB limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Service unavailable - S3 storage is not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/data-sources/{id}":{"get":{"summary":"Get a data source","description":"Retrieves a data source by ID. Requires admin access to the organization. Returns extended connection information excluding sensitive fields like passwords and private keys.","tags":["Data Sources"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Data source ID"},"required":true,"description":"Data source ID","name":"id","in":"path"}],"responses":{"200":{"description":"Data source retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Data source ID"},"displayName":{"type":"string","description":"Display name for the data source"},"description":{"type":"string","description":"Description of the data source"},"dialect":{"$ref":"#/components/schemas/DatabaseDialect"},"databaseName":{"type":["string","null"],"description":"Database name"},"username":{"type":["string","null"],"description":"Database username"},"host":{"type":["string","null"],"description":"Database host"},"port":{"type":["number","null"],"description":"Database port"},"sslEnabled":{"type":["boolean","null"],"description":"Whether SSL is enabled"},"sslCustomCertificatesEnabled":{"type":["boolean","null"],"description":"Whether custom SSL certificates are enabled"},"sshEnabled":{"type":["boolean","null"],"description":"Whether SSH tunnel is enabled"},"sshHost":{"type":["string","null"],"description":"SSH tunnel host"},"sshPort":{"type":["number","null"],"description":"SSH tunnel port"},"sshUsername":{"type":["string","null"],"description":"SSH tunnel username"},"bigQueryProjectId":{"type":["string","null"],"description":"BigQuery project ID"},"spannerInstanceId":{"type":["string","null"],"description":"Spanner instance ID"},"athenaWorkgroup":{"type":["string","null"],"description":"Athena workgroup"},"athenaOutputLocation":{"type":["string","null"],"description":"Athena output location"},"athenaCatalog":{"type":["string","null"],"description":"Athena data catalog"},"snowflakeAccountId":{"type":["string","null"],"description":"Snowflake account ID"},"snowflakeWarehouse":{"type":["string","null"],"description":"Snowflake warehouse"},"snowflakeRole":{"type":["string","null"],"description":"Snowflake role"},"lastSuccessfulSyncAt":{"type":["string","null"],"format":"date-time","description":"Last successful schema sync timestamp"},"lastSyncStatus":{"$ref":"#/components/schemas/SyncStatus"},"lastSyncAttemptAt":{"type":["string","null"],"format":"date-time","description":"Last schema sync attempt timestamp"},"hasCompletedFirstSync":{"type":"boolean","description":"Whether the first schema sync has completed"},"syncErrorMessage":{"type":["string","null"],"description":"Error message from the last failed sync"},"lastHealthyAt":{"type":"string","format":"date-time","description":"Last time the connection was healthy"},"lastHealthStatus":{"$ref":"#/components/schemas/ConnectionHealthStatus"},"lastHealthCheckAttemptAt":{"type":"string","format":"date-time","description":"Last health check attempt timestamp"},"isDemo":{"type":"boolean","description":"Whether this is a demo data source"},"isBasedashWarehouse":{"type":"boolean","description":"Whether this is a Basedash-managed warehouse"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}},"required":["id","displayName","description","dialect","databaseName","username","host","port","sslEnabled","sslCustomCertificatesEnabled","sshEnabled","sshHost","sshPort","sshUsername","bigQueryProjectId","spannerInstanceId","athenaWorkgroup","athenaOutputLocation","athenaCatalog","snowflakeAccountId","snowflakeWarehouse","snowflakeRole","lastSuccessfulSyncAt","lastSyncStatus","lastSyncAttemptAt","hasCompletedFirstSync","syncErrorMessage","lastHealthyAt","lastHealthStatus","lastHealthCheckAttemptAt","isDemo","isBasedashWarehouse","createdAt","updatedAt"]}},"required":["data"]}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Data source not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a data source","description":"Updates an existing data source connection settings. Requires admin access to the organization.","tags":["Data Sources"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Data source ID"},"required":true,"description":"Data source ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"snowflakeAccountId":{"type":"string","description":"Snowflake account ID"},"snowflakeWarehouse":{"type":"string","description":"Snowflake warehouse"},"snowflakeRole":{"type":"string","description":"Snowflake role"},"snowflakePrivateKey":{"type":"string","description":"Snowflake private key"},"snowflakePrivateKeyPassphrase":{"type":"string","description":"Snowflake private key passphrase"},"databaseName":{"type":["string","null"],"default":null,"description":"Database name"},"username":{"type":"string","description":"Database username"},"host":{"type":"string","description":"Database host"},"port":{"type":"integer","minimum":0,"maximum":65535,"description":"Database port"},"bigQueryProjectId":{"type":"string","description":"BigQuery project ID"},"spannerInstanceId":{"type":"string","description":"Spanner instance ID"},"athenaWorkgroup":{"type":"string","description":"Athena workgroup"},"athenaOutputLocation":{"type":"string","description":"Athena output location (s3://...)"},"athenaCatalog":{"type":"string","description":"Athena catalog"},"sslEnabled":{"type":"boolean","default":false,"description":"Enable SSL connection"},"sshEnabled":{"type":"boolean","default":false,"description":"Enable SSH tunnel"},"sshHost":{"type":"string","description":"SSH tunnel host"},"sshPort":{"type":"integer","minimum":0,"maximum":65535,"description":"SSH tunnel port"},"sshUsername":{"type":"string","description":"SSH tunnel username"},"sshPassword":{"type":["string","null"],"description":"SSH tunnel password"},"sshPrivateKey":{"type":["string","null"],"description":"SSH private key"},"sshPrivateKeyPassphrase":{"type":["string","null"],"description":"SSH private key passphrase"},"maxPoolSize":{"type":["integer","null"],"minimum":1,"maximum":100,"description":"Maximum number of connections in the pool per container"},"unsetPassword":{"type":["boolean","null"]},"password":{"type":["string","null"],"description":"Database password"},"unsetSshPassword":{"type":["boolean","null"]},"unsetSshPrivateKey":{"type":["boolean","null"]},"unsetSshPrivateKeyPassphrase":{"type":["boolean","null"]},"bigQueryJsonKey":{"type":["string","null"],"description":"BigQuery JSON key"}}}}}},"responses":{"200":{"description":"Data source updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Data source ID"},"displayName":{"type":"string","description":"Display name for the data source"},"description":{"type":"string","description":"Description of the data source"},"dialect":{"$ref":"#/components/schemas/DatabaseDialect"},"databaseName":{"type":["string","null"],"description":"Database name"},"username":{"type":["string","null"],"description":"Database username"},"host":{"type":["string","null"],"description":"Database host"},"port":{"type":["number","null"],"description":"Database port"},"sslEnabled":{"type":["boolean","null"],"description":"Whether SSL is enabled"},"sslCustomCertificatesEnabled":{"type":["boolean","null"],"description":"Whether custom SSL certificates are enabled"},"sshEnabled":{"type":["boolean","null"],"description":"Whether SSH tunnel is enabled"},"sshHost":{"type":["string","null"],"description":"SSH tunnel host"},"sshPort":{"type":["number","null"],"description":"SSH tunnel port"},"sshUsername":{"type":["string","null"],"description":"SSH tunnel username"},"bigQueryProjectId":{"type":["string","null"],"description":"BigQuery project ID"},"spannerInstanceId":{"type":["string","null"],"description":"Spanner instance ID"},"athenaWorkgroup":{"type":["string","null"],"description":"Athena workgroup"},"athenaOutputLocation":{"type":["string","null"],"description":"Athena output location"},"athenaCatalog":{"type":["string","null"],"description":"Athena data catalog"},"snowflakeAccountId":{"type":["string","null"],"description":"Snowflake account ID"},"snowflakeWarehouse":{"type":["string","null"],"description":"Snowflake warehouse"},"snowflakeRole":{"type":["string","null"],"description":"Snowflake role"},"lastSuccessfulSyncAt":{"type":["string","null"],"format":"date-time","description":"Last successful schema sync timestamp"},"lastSyncStatus":{"$ref":"#/components/schemas/SyncStatus"},"lastSyncAttemptAt":{"type":["string","null"],"format":"date-time","description":"Last schema sync attempt timestamp"},"hasCompletedFirstSync":{"type":"boolean","description":"Whether the first schema sync has completed"},"syncErrorMessage":{"type":["string","null"],"description":"Error message from the last failed sync"},"lastHealthyAt":{"type":"string","format":"date-time","description":"Last time the connection was healthy"},"lastHealthStatus":{"$ref":"#/components/schemas/ConnectionHealthStatus"},"lastHealthCheckAttemptAt":{"type":"string","format":"date-time","description":"Last health check attempt timestamp"},"isDemo":{"type":"boolean","description":"Whether this is a demo data source"},"isBasedashWarehouse":{"type":"boolean","description":"Whether this is a Basedash-managed warehouse"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}},"required":["id","displayName","description","dialect","databaseName","username","host","port","sslEnabled","sslCustomCertificatesEnabled","sshEnabled","sshHost","sshPort","sshUsername","bigQueryProjectId","spannerInstanceId","athenaWorkgroup","athenaOutputLocation","athenaCatalog","snowflakeAccountId","snowflakeWarehouse","snowflakeRole","lastSuccessfulSyncAt","lastSyncStatus","lastSyncAttemptAt","hasCompletedFirstSync","syncErrorMessage","lastHealthyAt","lastHealthStatus","lastHealthCheckAttemptAt","isDemo","isBasedashWarehouse","createdAt","updatedAt"]}},"required":["data"]}}}},"400":{"description":"Bad request - Invalid JSON body or validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Data source not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a data source","description":"Soft-deletes a data source by ID. Requires admin access to the organization. The data source will be marked as deleted and a cleanup job will be triggered to remove related entities.","tags":["Data Sources"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Data source ID"},"required":true,"description":"Data source ID","name":"id","in":"path"}],"responses":{"200":{"description":"Data source deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Data source ID"},"displayName":{"type":"string","description":"Display name for the data source"},"description":{"type":"string","description":"Description of the data source"},"dialect":{"$ref":"#/components/schemas/DatabaseDialect"},"databaseName":{"type":["string","null"],"description":"Database name"},"username":{"type":["string","null"],"description":"Database username"},"host":{"type":["string","null"],"description":"Database host"},"port":{"type":["number","null"],"description":"Database port"},"sslEnabled":{"type":["boolean","null"],"description":"Whether SSL is enabled"},"sslCustomCertificatesEnabled":{"type":["boolean","null"],"description":"Whether custom SSL certificates are enabled"},"sshEnabled":{"type":["boolean","null"],"description":"Whether SSH tunnel is enabled"},"sshHost":{"type":["string","null"],"description":"SSH tunnel host"},"sshPort":{"type":["number","null"],"description":"SSH tunnel port"},"sshUsername":{"type":["string","null"],"description":"SSH tunnel username"},"bigQueryProjectId":{"type":["string","null"],"description":"BigQuery project ID"},"spannerInstanceId":{"type":["string","null"],"description":"Spanner instance ID"},"athenaWorkgroup":{"type":["string","null"],"description":"Athena workgroup"},"athenaOutputLocation":{"type":["string","null"],"description":"Athena output location"},"athenaCatalog":{"type":["string","null"],"description":"Athena data catalog"},"snowflakeAccountId":{"type":["string","null"],"description":"Snowflake account ID"},"snowflakeWarehouse":{"type":["string","null"],"description":"Snowflake warehouse"},"snowflakeRole":{"type":["string","null"],"description":"Snowflake role"},"lastSuccessfulSyncAt":{"type":["string","null"],"format":"date-time","description":"Last successful schema sync timestamp"},"lastSyncStatus":{"$ref":"#/components/schemas/SyncStatus"},"lastSyncAttemptAt":{"type":["string","null"],"format":"date-time","description":"Last schema sync attempt timestamp"},"hasCompletedFirstSync":{"type":"boolean","description":"Whether the first schema sync has completed"},"syncErrorMessage":{"type":["string","null"],"description":"Error message from the last failed sync"},"lastHealthyAt":{"type":"string","format":"date-time","description":"Last time the connection was healthy"},"lastHealthStatus":{"$ref":"#/components/schemas/ConnectionHealthStatus"},"lastHealthCheckAttemptAt":{"type":"string","format":"date-time","description":"Last health check attempt timestamp"},"isDemo":{"type":"boolean","description":"Whether this is a demo data source"},"isBasedashWarehouse":{"type":"boolean","description":"Whether this is a Basedash-managed warehouse"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}},"required":["id","displayName","description","dialect","databaseName","username","host","port","sslEnabled","sslCustomCertificatesEnabled","sshEnabled","sshHost","sshPort","sshUsername","bigQueryProjectId","spannerInstanceId","athenaWorkgroup","athenaOutputLocation","athenaCatalog","snowflakeAccountId","snowflakeWarehouse","snowflakeRole","lastSuccessfulSyncAt","lastSyncStatus","lastSyncAttemptAt","hasCompletedFirstSync","syncErrorMessage","lastHealthyAt","lastHealthStatus","lastHealthCheckAttemptAt","isDemo","isBasedashWarehouse","createdAt","updatedAt"]}},"required":["data"]}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Data source not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/data-sources":{"get":{"summary":"List data sources","description":"Lists all data sources for an organization. Requires admin access to the organization. Results are paginated and ordered by creation date (newest first).","tags":["Data Sources"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Maximum number of items to return (1-100, default 50)"},"required":false,"description":"Maximum number of items to return (1-100, default 50)","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination (ID of the last item from previous page)"},"required":false,"description":"Cursor for pagination (ID of the last item from previous page)","name":"cursor","in":"query"}],"responses":{"200":{"description":"Data sources retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Data source ID"},"displayName":{"type":"string","description":"Display name for the data source"},"description":{"type":"string","description":"Description of the data source"},"dialect":{"$ref":"#/components/schemas/DatabaseDialect"},"databaseName":{"type":["string","null"],"description":"Database name"},"username":{"type":["string","null"],"description":"Database username"},"host":{"type":["string","null"],"description":"Database host"},"port":{"type":["number","null"],"description":"Database port"},"sslEnabled":{"type":["boolean","null"],"description":"Whether SSL is enabled"},"sslCustomCertificatesEnabled":{"type":["boolean","null"],"description":"Whether custom SSL certificates are enabled"},"sshEnabled":{"type":["boolean","null"],"description":"Whether SSH tunnel is enabled"},"sshHost":{"type":["string","null"],"description":"SSH tunnel host"},"sshPort":{"type":["number","null"],"description":"SSH tunnel port"},"sshUsername":{"type":["string","null"],"description":"SSH tunnel username"},"bigQueryProjectId":{"type":["string","null"],"description":"BigQuery project ID"},"spannerInstanceId":{"type":["string","null"],"description":"Spanner instance ID"},"athenaWorkgroup":{"type":["string","null"],"description":"Athena workgroup"},"athenaOutputLocation":{"type":["string","null"],"description":"Athena output location"},"athenaCatalog":{"type":["string","null"],"description":"Athena data catalog"},"snowflakeAccountId":{"type":["string","null"],"description":"Snowflake account ID"},"snowflakeWarehouse":{"type":["string","null"],"description":"Snowflake warehouse"},"snowflakeRole":{"type":["string","null"],"description":"Snowflake role"},"lastSuccessfulSyncAt":{"type":["string","null"],"format":"date-time","description":"Last successful schema sync timestamp"},"lastSyncStatus":{"$ref":"#/components/schemas/SyncStatus"},"lastSyncAttemptAt":{"type":["string","null"],"format":"date-time","description":"Last schema sync attempt timestamp"},"hasCompletedFirstSync":{"type":"boolean","description":"Whether the first schema sync has completed"},"syncErrorMessage":{"type":["string","null"],"description":"Error message from the last failed sync"},"lastHealthyAt":{"type":"string","format":"date-time","description":"Last time the connection was healthy"},"lastHealthStatus":{"$ref":"#/components/schemas/ConnectionHealthStatus"},"lastHealthCheckAttemptAt":{"type":"string","format":"date-time","description":"Last health check attempt timestamp"},"isDemo":{"type":"boolean","description":"Whether this is a demo data source"},"isBasedashWarehouse":{"type":"boolean","description":"Whether this is a Basedash-managed warehouse"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}},"required":["id","displayName","description","dialect","databaseName","username","host","port","sslEnabled","sslCustomCertificatesEnabled","sshEnabled","sshHost","sshPort","sshUsername","bigQueryProjectId","spannerInstanceId","athenaWorkgroup","athenaOutputLocation","athenaCatalog","snowflakeAccountId","snowflakeWarehouse","snowflakeRole","lastSuccessfulSyncAt","lastSyncStatus","lastSyncAttemptAt","hasCompletedFirstSync","syncErrorMessage","lastHealthyAt","lastHealthStatus","lastHealthCheckAttemptAt","isDemo","isBasedashWarehouse","createdAt","updatedAt"]}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Organization not found or no access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a data source","description":"Creates a new data source connection for an organization. Requires admin access to the organization. Currently only direct database connections are supported.","tags":["Data Sources"],"security":[{"bearerAuth":[]}],"x-mint":{"content":"## Side effects\n\nWhen a data source is successfully created:\n\n1. **Schema sync** - A background job is triggered to connect to the database and sync its schema (tables, columns, etc.)\n2. **Trial activation** - If the organization has never been on a trial, a trial period is automatically started"},"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"snowflakeAccountId":{"type":"string","description":"Snowflake account ID"},"snowflakeWarehouse":{"type":"string","description":"Snowflake warehouse"},"snowflakeRole":{"type":"string","description":"Snowflake role"},"snowflakePrivateKey":{"type":"string","description":"Snowflake private key"},"snowflakePrivateKeyPassphrase":{"type":"string","description":"Snowflake private key passphrase"},"databaseName":{"type":["string","null"],"default":null,"description":"Database name"},"username":{"type":"string","description":"Database username"},"host":{"type":"string","description":"Database host"},"port":{"type":"integer","minimum":0,"maximum":65535,"description":"Database port"},"password":{"type":"string","description":"Database password"},"bigQueryJsonKey":{"type":"string","description":"BigQuery JSON key"},"bigQueryProjectId":{"type":"string","description":"BigQuery project ID"},"spannerInstanceId":{"type":"string","description":"Spanner instance ID"},"athenaWorkgroup":{"type":"string","description":"Athena workgroup"},"athenaOutputLocation":{"type":"string","description":"Athena output location (s3://...)"},"athenaCatalog":{"type":"string","description":"Athena catalog"},"sslEnabled":{"type":"boolean","default":true,"description":"Enable SSL connection"},"sshEnabled":{"type":"boolean","default":false,"description":"Enable SSH tunnel"},"sshHost":{"type":"string","description":"SSH tunnel host"},"sshPort":{"type":"integer","minimum":0,"maximum":65535,"description":"SSH tunnel port"},"sshUsername":{"type":"string","description":"SSH tunnel username"},"sshPassword":{"type":"string","description":"SSH tunnel password"},"sshPrivateKey":{"type":"string","description":"SSH private key"},"sshPrivateKeyPassphrase":{"type":"string","description":"SSH private key passphrase"},"maxPoolSize":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum number of connections in the pool per container"},"type":{"type":"string","enum":["direct"],"description":"Connection type (currently only direct)"},"dialect":{"$ref":"#/components/schemas/DatabaseDialect"},"displayName":{"type":"string","minLength":1,"description":"Display name for the data source"}},"required":["type","dialect","displayName"]}}}},"responses":{"201":{"description":"Data source created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Data source ID"},"displayName":{"type":"string","description":"Display name for the data source"},"description":{"type":"string","description":"Description of the data source"},"dialect":{"$ref":"#/components/schemas/DatabaseDialect"},"databaseName":{"type":["string","null"],"description":"Database name"},"username":{"type":["string","null"],"description":"Database username"},"host":{"type":["string","null"],"description":"Database host"},"port":{"type":["number","null"],"description":"Database port"},"sslEnabled":{"type":["boolean","null"],"description":"Whether SSL is enabled"},"sslCustomCertificatesEnabled":{"type":["boolean","null"],"description":"Whether custom SSL certificates are enabled"},"sshEnabled":{"type":["boolean","null"],"description":"Whether SSH tunnel is enabled"},"sshHost":{"type":["string","null"],"description":"SSH tunnel host"},"sshPort":{"type":["number","null"],"description":"SSH tunnel port"},"sshUsername":{"type":["string","null"],"description":"SSH tunnel username"},"bigQueryProjectId":{"type":["string","null"],"description":"BigQuery project ID"},"spannerInstanceId":{"type":["string","null"],"description":"Spanner instance ID"},"athenaWorkgroup":{"type":["string","null"],"description":"Athena workgroup"},"athenaOutputLocation":{"type":["string","null"],"description":"Athena output location"},"athenaCatalog":{"type":["string","null"],"description":"Athena data catalog"},"snowflakeAccountId":{"type":["string","null"],"description":"Snowflake account ID"},"snowflakeWarehouse":{"type":["string","null"],"description":"Snowflake warehouse"},"snowflakeRole":{"type":["string","null"],"description":"Snowflake role"},"lastSuccessfulSyncAt":{"type":["string","null"],"format":"date-time","description":"Last successful schema sync timestamp"},"lastSyncStatus":{"$ref":"#/components/schemas/SyncStatus"},"lastSyncAttemptAt":{"type":["string","null"],"format":"date-time","description":"Last schema sync attempt timestamp"},"hasCompletedFirstSync":{"type":"boolean","description":"Whether the first schema sync has completed"},"syncErrorMessage":{"type":["string","null"],"description":"Error message from the last failed sync"},"lastHealthyAt":{"type":"string","format":"date-time","description":"Last time the connection was healthy"},"lastHealthStatus":{"$ref":"#/components/schemas/ConnectionHealthStatus"},"lastHealthCheckAttemptAt":{"type":"string","format":"date-time","description":"Last health check attempt timestamp"},"isDemo":{"type":"boolean","description":"Whether this is a demo data source"},"isBasedashWarehouse":{"type":"boolean","description":"Whether this is a Basedash-managed warehouse"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}},"required":["id","displayName","description","dialect","databaseName","username","host","port","sslEnabled","sslCustomCertificatesEnabled","sshEnabled","sshHost","sshPort","sshUsername","bigQueryProjectId","spannerInstanceId","athenaWorkgroup","athenaOutputLocation","athenaCatalog","snowflakeAccountId","snowflakeWarehouse","snowflakeRole","lastSuccessfulSyncAt","lastSyncStatus","lastSyncAttemptAt","hasCompletedFirstSync","syncErrorMessage","lastHealthyAt","lastHealthStatus","lastHealthCheckAttemptAt","isDemo","isBasedashWarehouse","createdAt","updatedAt"]}},"required":["data"]}}}},"400":{"description":"Bad request - Invalid JSON body, validation error, or unsupported type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Organization not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/data-sources/verify":{"post":{"summary":"Verify data source credentials","description":"Tests database connection credentials without creating a data source. Use this endpoint to validate credentials before creating or updating a data source.","tags":["Data Sources"],"security":[{"bearerAuth":[]}],"x-mint":{"content":"## When to use\n\nThis endpoint is commonly used in combination with the create or update data source endpoints. It allows you to verify that the provided credentials can successfully connect to the database before committing to creating or updating a data source.\n\n## Typical workflow\n\n1. **Verify credentials** - Call this endpoint with the connection details\n2. **Check response** - If successful, proceed to create/update; if failed, display field-specific errors to the user\n3. **Create/update data source** - Once verified, call the create or update endpoint with the same credentials\n\n## Field-specific errors\n\nWhen a connection fails, the response includes `fieldErrors` that map specific fields to their errors. This allows you to display targeted feedback to users about which credential field is incorrect.\n\nCommon field errors:\n- `host`: \"Host not found\" - The hostname could not be resolved\n- `port`: \"Incorrect port\" - The connection was refused on the specified port\n- `username`/`password`: \"Incorrect username or password\" - Authentication failed\n- `databaseName`: \"Database does not exist\" - The specified database was not found\n\n## IP whitelisting\n\nIf the connection times out, ensure the Basedash IP address (24.199.77.73) is whitelisted in your database firewall rules."},"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"snowflakeAccountId":{"type":"string","description":"Snowflake account ID"},"snowflakeWarehouse":{"type":"string","description":"Snowflake warehouse"},"snowflakeRole":{"type":"string","description":"Snowflake role"},"snowflakePrivateKey":{"type":"string","description":"Snowflake private key"},"snowflakePrivateKeyPassphrase":{"type":"string","description":"Snowflake private key passphrase"},"databaseName":{"type":["string","null"],"default":null,"description":"Database name"},"username":{"type":"string","description":"Database username"},"host":{"type":"string","description":"Database host"},"port":{"type":"integer","minimum":0,"maximum":65535,"description":"Database port"},"password":{"type":"string","description":"Database password"},"bigQueryJsonKey":{"type":"string","description":"BigQuery JSON key"},"bigQueryProjectId":{"type":"string","description":"BigQuery project ID"},"spannerInstanceId":{"type":"string","description":"Spanner instance ID"},"athenaWorkgroup":{"type":"string","description":"Athena workgroup"},"athenaOutputLocation":{"type":"string","description":"Athena output location (s3://...)"},"athenaCatalog":{"type":"string","description":"Athena catalog"},"sslEnabled":{"type":"boolean","default":true,"description":"Enable SSL connection"},"sshEnabled":{"type":"boolean","default":false,"description":"Enable SSH tunnel"},"sshHost":{"type":"string","description":"SSH tunnel host"},"sshPort":{"type":"integer","minimum":0,"maximum":65535,"description":"SSH tunnel port"},"sshUsername":{"type":"string","description":"SSH tunnel username"},"sshPassword":{"type":"string","description":"SSH tunnel password"},"sshPrivateKey":{"type":"string","description":"SSH private key"},"sshPrivateKeyPassphrase":{"type":"string","description":"SSH private key passphrase"},"maxPoolSize":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum number of connections in the pool per container"},"dialect":{"$ref":"#/components/schemas/DatabaseDialect"}},"required":["dialect"]}}}},"responses":{"200":{"description":"Credentials verified successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"type":"boolean","enum":[true],"description":"Indicates successful connection"}},"required":["success"]}},"required":["data"]}}}},"400":{"description":"Bad request - Invalid JSON body, validation error, or connection failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"title":{"type":"string","enum":["ConnectionFailed"],"description":"Error type identifier"},"detail":{"type":"string","description":"Human-readable error description"},"fieldErrors":{"type":"object","properties":{"host":{"type":"string","description":"Host-related error"},"port":{"type":"string","description":"Port-related error"},"username":{"type":"string","description":"Username-related error"},"password":{"type":"string","description":"Password-related error"},"databaseName":{"type":"string","description":"Database name error"},"athenaOutputLocation":{"type":"string","description":"Athena output location error"},"bigQueryJsonKey":{"type":"string","description":"BigQuery JSON key error"},"snowflakePrivateKey":{"type":"string","description":"Snowflake private key error"},"snowflakePrivateKeyPassphrase":{"type":"string","description":"Snowflake passphrase error"}},"description":"Field-specific connection errors"}},"required":["title","detail"]}},"required":["error"]}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Organization not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/data-sources/{id}/access":{"get":{"summary":"Get data source access","description":"Retrieves the access policy for a data source. Requires admin access to the organization.","tags":["Data Sources"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Data source ID"},"required":true,"description":"Data source ID","name":"id","in":"path"}],"responses":{"200":{"description":"Data source access retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DataSourceAccessResponse"}},"required":["data"]}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Data source not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Update data source access","description":"Replaces the access policy for a data source. Use mode \"everyone\" to allow all organization members to view or edit it, or mode \"restricted\" with groupAccess/memberAccess to limit access. Legacy groupIds/memberIds grant view access. Requires admin access to the organization.","tags":["Data Sources"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Data source ID"},"required":true,"description":"Data source ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDataSourceAccessInput"}}}},"responses":{"200":{"description":"Data source access updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DataSourceAccessResponse"}},"required":["data"]}}}},"400":{"description":"Bad request - Invalid JSON body or validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Data source, group, or member not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/automations":{"get":{"summary":"List automations","description":"Lists automations for an organization. Requires admin access to the organization. Results are paginated and ordered by creation date (newest first).","tags":["Automations"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Maximum number of items to return (1-100, default 50)"},"required":false,"description":"Maximum number of items to return (1-100, default 50)","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination (ID of the last item from previous page)"},"required":false,"description":"Cursor for pagination (ID of the last item from previous page)","name":"cursor","in":"query"},{"schema":{"type":["boolean","null"],"description":"Whether archived automations should be included"},"required":false,"description":"Whether archived automations should be included","name":"includeArchived","in":"query"}],"responses":{"200":{"description":"Automations retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAutomationListResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Organization not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an automation","description":"Creates an automation for an organization. Requires admin access to the organization.","tags":["Automations"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAutomationInput"}}}},"responses":{"201":{"description":"Automation created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAutomationResponse"}}}},"400":{"description":"Bad request - Invalid JSON body or validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Automations are disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Organization not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/automations/{id}":{"get":{"summary":"Get an automation","description":"Retrieves an automation by ID. Requires admin access to the organization.","tags":["Automations"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Automation ID"},"required":true,"description":"Automation ID","name":"id","in":"path"}],"responses":{"200":{"description":"Automation retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAutomationResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Automation not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an automation","description":"Updates an automation by ID. Requires admin access to the organization.","tags":["Automations"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Automation ID"},"required":true,"description":"Automation ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAutomationInput"}}}},"responses":{"200":{"description":"Automation updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAutomationResponse"}}}},"400":{"description":"Bad request - Invalid JSON body or validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Automation not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Archive an automation","description":"Archives an automation by ID. Requires admin access to the organization.","tags":["Automations"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Automation ID"},"required":true,"description":"Automation ID","name":"id","in":"path"}],"responses":{"204":{"description":"Automation archived successfully"},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Automation not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/automations/{id}/runs":{"get":{"summary":"List automation runs","description":"Lists runs for an automation. Requires admin access to the organization. Results are paginated and ordered by creation date (newest first).","tags":["Automations"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Automation ID"},"required":true,"description":"Automation ID","name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Maximum number of items to return (1-100, default 50)"},"required":false,"description":"Maximum number of items to return (1-100, default 50)","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination (ID of the last item from previous page)"},"required":false,"description":"Cursor for pagination (ID of the last item from previous page)","name":"cursor","in":"query"}],"responses":{"200":{"description":"Automation runs retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAutomationRunListResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Automation not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Start an automation run","description":"Starts a manual run for a scheduled or manual automation. Requires admin access to the organization. Run generation happens asynchronously.","tags":["Automations"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Automation ID"},"required":true,"description":"Automation ID","name":"id","in":"path"}],"responses":{"202":{"description":"Automation run started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAutomationRunResponse"}}}},"400":{"description":"Bad request - Automation cannot be manually started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Automation not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/automations/{id}/runs/{runId}":{"get":{"summary":"Get an automation run","description":"Retrieves an automation run by ID, including the final assistant response content. Requires admin access to the organization.","tags":["Automations"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Automation ID"},"required":true,"description":"Automation ID","name":"id","in":"path"},{"schema":{"type":"string","description":"Automation run ID"},"required":true,"description":"Automation run ID","name":"runId","in":"path"}],"responses":{"200":{"description":"Automation run retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAutomationRunResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Automation run not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/definitions":{"get":{"summary":"List definitions","description":"Lists definitions for an organization. Requires admin access to the organization. Results are paginated and ordered by creation date (newest first).","tags":["Definitions"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Maximum number of items to return (1-100, default 50)"},"required":false,"description":"Maximum number of items to return (1-100, default 50)","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination (ID of the last item from previous page)"},"required":false,"description":"Cursor for pagination (ID of the last item from previous page)","name":"cursor","in":"query"},{"schema":{"type":"string","description":"Optional data source ID to filter definitions by"},"required":false,"description":"Optional data source ID to filter definitions by","name":"databaseConnectionId","in":"query"}],"responses":{"200":{"description":"Definitions retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DefinitionResponse"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Organization, data source, or admin access not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a definition","description":"Creates a new definition within an organization. Requires admin access to the organization.","tags":["Definitions"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDefinitionInput"}}}},"responses":{"201":{"description":"Definition created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DefinitionResponse"}},"required":["data"]}}}},"400":{"description":"Bad request - Invalid JSON body or validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Organization, data source, or admin access not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict - Definition reference name already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/definitions/{id}":{"get":{"summary":"Get a definition","description":"Retrieves a definition by ID. Requires admin access to the organization.","tags":["Definitions"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Definition ID"},"required":true,"description":"Definition ID","name":"id","in":"path"}],"responses":{"200":{"description":"Definition retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DefinitionResponse"}},"required":["data"]}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Definition not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a definition","description":"Updates an existing definition. Requires admin access to the organization.","tags":["Definitions"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Definition ID"},"required":true,"description":"Definition ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDefinitionInput"}}}},"responses":{"200":{"description":"Definition updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DefinitionResponse"}},"required":["data"]}}}},"400":{"description":"Bad request - Invalid JSON body or validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Definition not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict - Definition reference name already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a definition","description":"Archives a definition by ID. Requires admin access to the organization.","tags":["Definitions"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Definition ID"},"required":true,"description":"Definition ID","name":"id","in":"path"}],"responses":{"204":{"description":"Definition deleted successfully"},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Definition not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/mcp-servers/{id}":{"get":{"summary":"Get an MCP server","description":"Retrieves an MCP server by ID. Requires admin access to the organization. Returns server status and synced tools, excluding configured headers and OAuth tokens.","tags":["MCP servers"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"MCP server ID"},"required":true,"description":"MCP server ID","name":"id","in":"path"}],"responses":{"200":{"description":"MCP server retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"MCP server ID"},"displayName":{"type":"string","description":"Display name for the MCP server"},"serverUrl":{"type":"string","description":"MCP server URL"},"serverLabel":{"type":"string","description":"Stable server label used when exposing tools to AI models"},"transportType":{"type":["string","null"],"enum":["STREAMABLE_HTTP","SSE",null],"description":"Transport protocol used by the MCP server"},"setupState":{"type":"string","enum":["INCOMPLETE","CONNECTED","BROKEN"],"description":"MCP server setup state"},"lastSyncStatus":{"$ref":"#/components/schemas/SyncStatus"},"lastSyncAttemptAt":{"type":["string","null"],"format":"date-time","description":"Last tool sync attempt timestamp"},"lastSuccessfulSyncAt":{"type":["string","null"],"format":"date-time","description":"Last successful tool sync timestamp"},"hasCompletedFirstSync":{"type":"boolean","description":"Whether the first tool sync has completed"},"syncErrorMessage":{"type":["string","null"],"description":"Error message from the last failed sync"},"tools":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Tool ID"},"name":{"type":"string","description":"Tool name"},"description":{"type":["string","null"],"description":"Tool description"},"readOnlyHint":{"type":["boolean","null"],"description":"Whether the tool advertises that it only reads data"},"accessMode":{"type":"string","enum":["ALWAYS_ALLOW","NEEDS_APPROVAL","BLOCKED"],"description":"Tool access mode"},"foundInServer":{"type":"boolean","description":"Whether this tool was found during the latest sync"}},"required":["id","name","description","readOnlyHint","accessMode","foundInServer"]},"description":"Available MCP tools"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}},"required":["id","displayName","serverUrl","serverLabel","transportType","setupState","lastSyncStatus","lastSyncAttemptAt","lastSuccessfulSyncAt","hasCompletedFirstSync","syncErrorMessage","tools","createdAt","updatedAt"]}},"required":["data"]}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - MCP server not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an MCP server","description":"Updates an MCP server display name, URL, static headers, or synced tool access modes. Requires admin access to the organization.","tags":["MCP servers"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"MCP server ID"},"required":true,"description":"MCP server ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"displayName":{"type":"string","minLength":1,"maxLength":120,"description":"Display name for the MCP server"},"serverUrl":{"type":"string","minLength":1,"maxLength":2000,"description":"MCP server URL"},"headers":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}},"required":["key","value"]},"description":"Static headers to use when connecting to the MCP server"},"tools":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Tool ID"},"accessMode":{"type":"string","enum":["ALWAYS_ALLOW","NEEDS_APPROVAL","BLOCKED"],"description":"Tool access mode"}},"required":["id","accessMode"]},"minItems":1,"description":"Tool access modes to update for this MCP server"}}}}}},"responses":{"200":{"description":"MCP server updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"MCP server ID"},"displayName":{"type":"string","description":"Display name for the MCP server"},"serverUrl":{"type":"string","description":"MCP server URL"},"serverLabel":{"type":"string","description":"Stable server label used when exposing tools to AI models"},"transportType":{"type":["string","null"],"enum":["STREAMABLE_HTTP","SSE",null],"description":"Transport protocol used by the MCP server"},"setupState":{"type":"string","enum":["INCOMPLETE","CONNECTED","BROKEN"],"description":"MCP server setup state"},"lastSyncStatus":{"$ref":"#/components/schemas/SyncStatus"},"lastSyncAttemptAt":{"type":["string","null"],"format":"date-time","description":"Last tool sync attempt timestamp"},"lastSuccessfulSyncAt":{"type":["string","null"],"format":"date-time","description":"Last successful tool sync timestamp"},"hasCompletedFirstSync":{"type":"boolean","description":"Whether the first tool sync has completed"},"syncErrorMessage":{"type":["string","null"],"description":"Error message from the last failed sync"},"tools":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Tool ID"},"name":{"type":"string","description":"Tool name"},"description":{"type":["string","null"],"description":"Tool description"},"readOnlyHint":{"type":["boolean","null"],"description":"Whether the tool advertises that it only reads data"},"accessMode":{"type":"string","enum":["ALWAYS_ALLOW","NEEDS_APPROVAL","BLOCKED"],"description":"Tool access mode"},"foundInServer":{"type":"boolean","description":"Whether this tool was found during the latest sync"}},"required":["id","name","description","readOnlyHint","accessMode","foundInServer"]},"description":"Available MCP tools"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}},"required":["id","displayName","serverUrl","serverLabel","transportType","setupState","lastSyncStatus","lastSyncAttemptAt","lastSuccessfulSyncAt","hasCompletedFirstSync","syncErrorMessage","tools","createdAt","updatedAt"]}},"required":["data"]}}}},"400":{"description":"Bad request - Invalid JSON body or validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - MCP server not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete an MCP server","description":"Deletes an MCP server by ID. Requires admin access to the organization.","tags":["MCP servers"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"MCP server ID"},"required":true,"description":"MCP server ID","name":"id","in":"path"}],"responses":{"200":{"description":"MCP server deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"MCP server ID"},"displayName":{"type":"string","description":"Display name for the MCP server"},"serverUrl":{"type":"string","description":"MCP server URL"},"serverLabel":{"type":"string","description":"Stable server label used when exposing tools to AI models"},"transportType":{"type":["string","null"],"enum":["STREAMABLE_HTTP","SSE",null],"description":"Transport protocol used by the MCP server"},"setupState":{"type":"string","enum":["INCOMPLETE","CONNECTED","BROKEN"],"description":"MCP server setup state"},"lastSyncStatus":{"$ref":"#/components/schemas/SyncStatus"},"lastSyncAttemptAt":{"type":["string","null"],"format":"date-time","description":"Last tool sync attempt timestamp"},"lastSuccessfulSyncAt":{"type":["string","null"],"format":"date-time","description":"Last successful tool sync timestamp"},"hasCompletedFirstSync":{"type":"boolean","description":"Whether the first tool sync has completed"},"syncErrorMessage":{"type":["string","null"],"description":"Error message from the last failed sync"},"tools":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Tool ID"},"name":{"type":"string","description":"Tool name"},"description":{"type":["string","null"],"description":"Tool description"},"readOnlyHint":{"type":["boolean","null"],"description":"Whether the tool advertises that it only reads data"},"accessMode":{"type":"string","enum":["ALWAYS_ALLOW","NEEDS_APPROVAL","BLOCKED"],"description":"Tool access mode"},"foundInServer":{"type":"boolean","description":"Whether this tool was found during the latest sync"}},"required":["id","name","description","readOnlyHint","accessMode","foundInServer"]},"description":"Available MCP tools"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}},"required":["id","displayName","serverUrl","serverLabel","transportType","setupState","lastSyncStatus","lastSyncAttemptAt","lastSuccessfulSyncAt","hasCompletedFirstSync","syncErrorMessage","tools","createdAt","updatedAt"]}},"required":["data"]}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - MCP server not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/mcp-servers":{"get":{"summary":"List MCP servers","description":"Lists all MCP servers for an organization. Requires admin access to the organization. Results are paginated and ordered by creation date (newest first).","tags":["MCP servers"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Maximum number of items to return (1-100, default 50)"},"required":false,"description":"Maximum number of items to return (1-100, default 50)","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination (ID of the last item from previous page)"},"required":false,"description":"Cursor for pagination (ID of the last item from previous page)","name":"cursor","in":"query"}],"responses":{"200":{"description":"MCP servers retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"MCP server ID"},"displayName":{"type":"string","description":"Display name for the MCP server"},"serverUrl":{"type":"string","description":"MCP server URL"},"serverLabel":{"type":"string","description":"Stable server label used when exposing tools to AI models"},"transportType":{"type":["string","null"],"enum":["STREAMABLE_HTTP","SSE",null],"description":"Transport protocol used by the MCP server"},"setupState":{"type":"string","enum":["INCOMPLETE","CONNECTED","BROKEN"],"description":"MCP server setup state"},"lastSyncStatus":{"$ref":"#/components/schemas/SyncStatus"},"lastSyncAttemptAt":{"type":["string","null"],"format":"date-time","description":"Last tool sync attempt timestamp"},"lastSuccessfulSyncAt":{"type":["string","null"],"format":"date-time","description":"Last successful tool sync timestamp"},"hasCompletedFirstSync":{"type":"boolean","description":"Whether the first tool sync has completed"},"syncErrorMessage":{"type":["string","null"],"description":"Error message from the last failed sync"},"tools":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Tool ID"},"name":{"type":"string","description":"Tool name"},"description":{"type":["string","null"],"description":"Tool description"},"readOnlyHint":{"type":["boolean","null"],"description":"Whether the tool advertises that it only reads data"},"accessMode":{"type":"string","enum":["ALWAYS_ALLOW","NEEDS_APPROVAL","BLOCKED"],"description":"Tool access mode"},"foundInServer":{"type":"boolean","description":"Whether this tool was found during the latest sync"}},"required":["id","name","description","readOnlyHint","accessMode","foundInServer"]},"description":"Available MCP tools"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}},"required":["id","displayName","serverUrl","serverLabel","transportType","setupState","lastSyncStatus","lastSyncAttemptAt","lastSuccessfulSyncAt","hasCompletedFirstSync","syncErrorMessage","tools","createdAt","updatedAt"]}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Organization not found or no access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an MCP server","description":"Creates a new MCP server for an organization. Requires admin access to the organization. The server URL is validated, static headers are encrypted, and tools are synced after creation.","tags":["MCP servers"],"security":[{"bearerAuth":[]}],"x-mint":{"content":"## Side effects\n\nWhen an MCP server is successfully created:\n\n1. **Tool sync** - Basedash connects to the MCP server and syncs its tools\n2. **OAuth bootstrap** - If the server advertises OAuth, the response includes an authorization URL\n3. **Trial activation** - If the organization has never been on a trial, a trial period is automatically started"},"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"displayName":{"type":"string","minLength":1,"maxLength":120,"description":"Display name for the MCP server"},"serverUrl":{"type":"string","minLength":1,"maxLength":2000,"description":"MCP server URL"},"headers":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}},"required":["key","value"]},"default":[],"description":"Static headers to use when connecting to the MCP server"},"everyoneInOrganizationCanAccess":{"type":"boolean","default":true,"description":"Whether every member in the organization can use this MCP server"}},"required":["displayName","serverUrl"]}}}},"responses":{"201":{"description":"MCP server created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"MCP server ID"},"displayName":{"type":"string","description":"Display name for the MCP server"},"serverUrl":{"type":"string","description":"MCP server URL"},"serverLabel":{"type":"string","description":"Stable server label used when exposing tools to AI models"},"transportType":{"type":["string","null"],"enum":["STREAMABLE_HTTP","SSE",null],"description":"Transport protocol used by the MCP server"},"setupState":{"type":"string","enum":["INCOMPLETE","CONNECTED","BROKEN"],"description":"MCP server setup state"},"lastSyncStatus":{"$ref":"#/components/schemas/SyncStatus"},"lastSyncAttemptAt":{"type":["string","null"],"format":"date-time","description":"Last tool sync attempt timestamp"},"lastSuccessfulSyncAt":{"type":["string","null"],"format":"date-time","description":"Last successful tool sync timestamp"},"hasCompletedFirstSync":{"type":"boolean","description":"Whether the first tool sync has completed"},"syncErrorMessage":{"type":["string","null"],"description":"Error message from the last failed sync"},"tools":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Tool ID"},"name":{"type":"string","description":"Tool name"},"description":{"type":["string","null"],"description":"Tool description"},"readOnlyHint":{"type":["boolean","null"],"description":"Whether the tool advertises that it only reads data"},"accessMode":{"type":"string","enum":["ALWAYS_ALLOW","NEEDS_APPROVAL","BLOCKED"],"description":"Tool access mode"},"foundInServer":{"type":"boolean","description":"Whether this tool was found during the latest sync"}},"required":["id","name","description","readOnlyHint","accessMode","foundInServer"]},"description":"Available MCP tools"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"},"authUrl":{"type":["string","null"],"description":"OAuth authorization URL when the MCP server requires OAuth"},"requiresAuth":{"type":"boolean","description":"Whether the MCP server requires OAuth authorization"}},"required":["id","displayName","serverUrl","serverLabel","transportType","setupState","lastSyncStatus","lastSyncAttemptAt","lastSuccessfulSyncAt","hasCompletedFirstSync","syncErrorMessage","tools","createdAt","updatedAt","authUrl","requiresAuth"]}},"required":["data"]}}}},"400":{"description":"Bad request - Invalid JSON body or validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Organization not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/audit-logs":{"get":{"summary":"List audit log events","description":"Returns immutable organization audit events in reverse chronological order for SIEM ingestion. Requires an Enterprise organization and an administrator API key.","tags":["Organizations"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Maximum number of items to return (1-100, default 50)"},"required":false,"description":"Maximum number of items to return (1-100, default 50)","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination (ID of the last item from previous page)"},"required":false,"description":"Cursor for pagination (ID of the last item from previous page)","name":"cursor","in":"query"},{"schema":{"type":"string","enum":["user.login","user.logout","member.joined","member.invited","member.invite_revoked","member.role_changed","member.deactivated","member.reactivated","group.created","group.updated","group.deleted","group.member_added","group.member_removed","grant.created","grant.updated","grant.deleted","data_source.created","data_source.updated","data_source.deleted","data_source.sync_requested","data_source.schema_synced","data_source.credentials_viewed","api_key.created","api_key.deleted","scim_token.created","scim_token.deleted","organization.created","organization.updated","organization.jwt_secret_viewed","organization.jwt_secret_copied","domain.created","domain.updated","domain.deleted","dashboard.created","dashboard.deleted","dashboard.archived","dashboard.restored","dashboard.public_sharing_enabled","dashboard.public_sharing_disabled","automation.created","automation.deleted","automation.archived","automation.restored","mcp_connector.created","mcp_connector.updated","mcp_connector.deleted","mcp_connector.tool_access_updated","public_api.request","scim.user_created","scim.user_updated","scim.user_deactivated","scim.group_created","scim.group_updated","scim.group_deleted","query.executed","query.mutating_executed","data.exported","ai.tool_executed"],"description":"Exact dot-namespaced action"},"required":false,"description":"Exact dot-namespaced action","name":"action","in":"query"},{"schema":{"type":"string","description":"Actor user ID"},"required":false,"description":"Actor user ID","name":"actorId","in":"query"},{"schema":{"type":"string","enum":["AUTHENTICATION","MEMBERS","ACCESS_CONTROL","DATA_SOURCES","QUERIES","EXPORTS","AI","ORGANIZATION","CONTENT","INTEGRATIONS"]},"required":false,"name":"category","in":"query"},{"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","format":"date"}],"description":"Inclusive lower timestamp or date boundary"},"required":false,"description":"Inclusive lower timestamp or date boundary","name":"from","in":"query"},{"schema":{"type":"string","description":"Case-insensitive actor, action, target name, or target ID search"},"required":false,"description":"Case-insensitive actor, action, target name, or target ID search","name":"search","in":"query"},{"schema":{"type":"string","enum":["WEB","PUBLIC_API","SCIM","SLACK","MCP","SYSTEM","PUBLIC_DASHBOARD"]},"required":false,"name":"source","in":"query"},{"schema":{"type":"string","description":"Exact target resource type"},"required":false,"description":"Exact target resource type","name":"targetType","in":"query"},{"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","format":"date"}],"description":"Inclusive upper timestamp or date boundary"},"required":false,"description":"Inclusive upper timestamp or date boundary","name":"to","in":"query"}],"responses":{"200":{"description":"Audit events retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAuditLogListResponse"}}}},"400":{"description":"Bad request - Invalid filters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Enterprise plan required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Organization not found or no administrator access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/dashboards":{"get":{"summary":"List dashboards","description":"Lists all active (non-archived) dashboards for an organization. Requires admin access to the organization. Results are paginated and ordered by creation date (newest first).","tags":["Dashboards"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Maximum number of items to return (1-100, default 50)"},"required":false,"description":"Maximum number of items to return (1-100, default 50)","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination (ID of the last item from previous page)"},"required":false,"description":"Cursor for pagination (ID of the last item from previous page)","name":"cursor","in":"query"}],"responses":{"200":{"description":"Dashboards retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DashboardResponse"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Organization not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a dashboard","description":"Creates a new dashboard within an organization, including a default \"Main\" tab. Requires admin access to the organization.","tags":["Dashboards"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDashboardInput"}}}},"responses":{"201":{"description":"Dashboard created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DashboardWithTabsResponse"}},"required":["data"]}}}},"400":{"description":"Bad request - Invalid JSON body or validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Organization trial has expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Organization not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/charts":{"post":{"summary":"Create a chart","description":"Creates a new chart on a dashboard. The chart is placed on the specified tab (or the first tab by default) at the bottom of the tab unless a layout is provided. Requires admin access to the organization.","tags":["Charts"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateChartInput"}}}},"responses":{"201":{"description":"Chart created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChartResponse"}},"required":["data"]}}}},"400":{"description":"Bad request - Invalid JSON body or validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Organization trial has expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Organization not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/dashboards/{dashboardId}/charts":{"get":{"summary":"List charts on a dashboard","description":"Lists all active (non-archived) charts on a dashboard, including the content of each chart’s latest version (name, SQL query, chart type, axes). Requires admin access to the organization. Results are paginated and ordered by creation date (newest first).","tags":["Dashboards"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Dashboard ID"},"required":true,"description":"Dashboard ID","name":"dashboardId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Maximum number of items to return (1-100, default 50)"},"required":false,"description":"Maximum number of items to return (1-100, default 50)","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination (ID of the last item from previous page)"},"required":false,"description":"Cursor for pagination (ID of the last item from previous page)","name":"cursor","in":"query"}],"responses":{"200":{"description":"Charts retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ChartResponse"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Dashboard not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/dashboards/{dashboardId}/tabs":{"post":{"summary":"Create a dashboard tab","description":"Creates a new tab on a dashboard. Requires admin access to the organization.","tags":["Dashboards"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Dashboard ID"},"required":true,"description":"Dashboard ID","name":"dashboardId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDashboardTabInput"}}}},"responses":{"201":{"description":"Dashboard tab created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DashboardTab"}},"required":["data"]}}}},"400":{"description":"Bad request - Invalid JSON body or validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Organization trial has expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Dashboard not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/dashboards/{dashboardId}/tabs/{tabId}":{"patch":{"summary":"Update a dashboard tab","description":"Updates a dashboard tab (name and sort order). Requires admin access to the organization.","tags":["Dashboards"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Dashboard ID"},"required":true,"description":"Dashboard ID","name":"dashboardId","in":"path"},{"schema":{"type":"string","description":"Dashboard tab ID"},"required":true,"description":"Dashboard tab ID","name":"tabId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDashboardTabInput"}}}},"responses":{"200":{"description":"Dashboard tab updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DashboardTab"}},"required":["data"]}}}},"400":{"description":"Bad request - Invalid JSON body or validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Dashboard tab not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a dashboard tab","description":"Deletes a dashboard tab and archives the charts on it. The last tab on a dashboard cannot be deleted. Requires admin access to the organization.","tags":["Dashboards"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Dashboard ID"},"required":true,"description":"Dashboard ID","name":"dashboardId","in":"path"},{"schema":{"type":"string","description":"Dashboard tab ID"},"required":true,"description":"Dashboard tab ID","name":"tabId","in":"path"}],"responses":{"204":{"description":"Dashboard tab deleted successfully"},"400":{"description":"Bad request - Cannot delete the last tab on a dashboard","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Dashboard tab not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/dashboards/{id}":{"get":{"summary":"Get a dashboard","description":"Retrieves a dashboard by ID, including its tabs. Requires admin access to the organization.","tags":["Dashboards"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Dashboard ID"},"required":true,"description":"Dashboard ID","name":"id","in":"path"}],"responses":{"200":{"description":"Dashboard retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DashboardWithTabsResponse"}},"required":["data"]}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Dashboard not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a dashboard","description":"Updates dashboard metadata (name, description, icon, color, folder, width, and default date range settings). Requires admin access to the organization.","tags":["Dashboards"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Dashboard ID"},"required":true,"description":"Dashboard ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDashboardInput"}}}},"responses":{"200":{"description":"Dashboard updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DashboardWithTabsResponse"}},"required":["data"]}}}},"400":{"description":"Bad request - Invalid JSON body or validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Dashboard not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a dashboard","description":"Archives a dashboard by ID, along with the charts on it. Requires admin access to the organization.","tags":["Dashboards"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Dashboard ID"},"required":true,"description":"Dashboard ID","name":"id","in":"path"}],"responses":{"204":{"description":"Dashboard archived successfully"},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Dashboard not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/ai-usage":{"get":{"summary":"Get AI usage","description":"Gets total billable AI usage and member usage for the current billing period. Requires admin access to the organization.","tags":["Organizations"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"}],"responses":{"200":{"description":"AI usage retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAiUsageResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Organization not found, no admin access, or billing period unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/insights":{"get":{"summary":"List insights","description":"Lists insight summaries for an organization. Requires admin access to the organization. Results are paginated and ordered by creation date (newest first).","tags":["Insights"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Maximum number of items to return (1-100, default 50)"},"required":false,"description":"Maximum number of items to return (1-100, default 50)","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination (ID of the last item from previous page)"},"required":false,"description":"Cursor for pagination (ID of the last item from previous page)","name":"cursor","in":"query"}],"responses":{"200":{"description":"Insights retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicInsightListResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Organization not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Generate an insight","description":"Queues generation of a new insight for an organization. Requires admin access to the organization. Generation runs asynchronously.","tags":["Insights"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"}],"responses":{"202":{"description":"Insight generation queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateInsightDataResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insights are disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Organization not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/insights/{id}":{"get":{"summary":"Get an insight","description":"Retrieves an insight by ID, including the Markdown body, chart details, a chart image URL, and raw chart data. Requires admin access to the organization.","tags":["Insights"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Insight ID"},"required":true,"description":"Insight ID","name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":1000,"default":1000,"description":"Maximum raw chart rows to return (1-1000, default 1000)"},"required":false,"description":"Maximum raw chart rows to return (1-1000, default 1000)","name":"rawDataLimit","in":"query"},{"schema":{"type":"integer","minimum":1,"default":1,"description":"Raw chart data page number"},"required":false,"description":"Raw chart data page number","name":"rawDataPage","in":"query"}],"responses":{"200":{"description":"Insight retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicInsightDetailResponse"},"examples":{"revenueGrowth":{"summary":"Revenue growth insight","value":{"data":{"id":"insight_01jvmk3x9r6p8q4n2b7z5c1h0a","organizationId":"org_01jvmjz0f4m8t9s6r2p3q1n7xb","title":"Enterprise expansion drove revenue growth","chartId":"chart_01jvmk1ay8m4n6p2q9r7t3c5hd","chart":{"id":"chart_01jvmk1ay8m4n6p2q9r7t3c5hd","versionId":"chart_version_01jvmk1c2e7f9h4j6m8p0q3r5t","name":"Monthly recurring revenue by segment","type":"LINE","sqlQuery":"select date_trunc('month', started_at) as month, segment, sum(mrr) as mrr from subscriptions where status = 'active' group by 1, 2 order by 1","databaseConnectionId":"db_conn_01jvmhy3v6b9n2p4q8r5t7x1zc","imageUrl":"https://charts.basedash.com/api/public/organizations/org_01jvmjz0f4m8t9s6r2p3q1n7xb/charts/chart_01jvmk1ay8m4n6p2q9r7t3c5hd/image?chartVersionId=chart_version_01jvmk1c2e7f9h4j6m8p0q3r5t"},"createdAt":"2026-05-26T13:42:18.000Z","updatedAt":"2026-05-26T13:42:18.000Z","bodyMarkdown":"Enterprise MRR increased 18% month over month, outpacing self-serve growth by 11 percentage points. The increase was concentrated in the final week of April, when three annual expansions were booked.\n\nThis suggests the expansion motion is becoming a larger contributor to new recurring revenue.","sourceMeta":{"model":"gpt-5.4","generatedAt":"2026-05-26T13:42:18.000Z"},"rawData":{"rows":[{"month":"2026-02-01T00:00:00.000Z","segment":"Self serve","mrr":84200},{"month":"2026-02-01T00:00:00.000Z","segment":"Enterprise","mrr":126500},{"month":"2026-03-01T00:00:00.000Z","segment":"Self serve","mrr":89300},{"month":"2026-03-01T00:00:00.000Z","segment":"Enterprise","mrr":141800},{"month":"2026-04-01T00:00:00.000Z","segment":"Self serve","mrr":95600},{"month":"2026-04-01T00:00:00.000Z","segment":"Enterprise","mrr":167300}],"count":6,"page":1,"limit":1000}}}}}}}},"400":{"description":"Bad request - Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Insight not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete an insight","description":"Deletes an insight by ID. Requires admin access to the organization.","tags":["Insights"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Insight ID"},"required":true,"description":"Insight ID","name":"id","in":"path"}],"responses":{"204":{"description":"Insight deleted successfully"},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Insight not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/members":{"get":{"summary":"List members","description":"Lists all members for an organization, including their user information. Requires admin access to the organization. Results are paginated and ordered by creation date (newest first).","tags":["Members"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Maximum number of items to return (1-100, default 50)"},"required":false,"description":"Maximum number of items to return (1-100, default 50)","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination (ID of the last item from previous page)"},"required":false,"description":"Cursor for pagination (ID of the last item from previous page)","name":"cursor","in":"query"}],"responses":{"200":{"description":"Members retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MemberResponse"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Organization not found or no access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Invite a member","description":"Invites a user to an organization by email and role. Creates a pending user when the email does not belong to an existing user, reactivates deactivated memberships, and sends the same invitation email as the app. Requires admin access to the organization.","tags":["Members"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteMemberInput"}}}},"responses":{"201":{"description":"Member invited successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MemberResponse"}},"required":["data"]}}}},"400":{"description":"Bad request - Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Organization not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict - User is already a member","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/members/{id}":{"get":{"summary":"Get a member","description":"Retrieves a member by ID, including their user information. Requires admin access to the organization.","tags":["Members"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Member ID"},"required":true,"description":"Member ID","name":"id","in":"path"}],"responses":{"200":{"description":"Member retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MemberResponse"}},"required":["data"]}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Member not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Deactivate a member","description":"Deactivates a member in the organization. Requires admin access to the organization. Cannot deactivate the last active admin.","tags":["Members"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Member ID"},"required":true,"description":"Member ID","name":"id","in":"path"}],"responses":{"204":{"description":"Member deactivated successfully"},"400":{"description":"Bad request - Cannot remove the last admin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Member not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a member","description":"Updates a member role and supported user profile fields. Requires admin access to the organization. Cannot demote the last verified admin.","tags":["Members"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Member ID"},"required":true,"description":"Member ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMemberInput"}}}},"responses":{"200":{"description":"Member updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MemberResponse"}},"required":["data"]}}}},"400":{"description":"Bad request - Invalid request body or last admin demotion","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Member not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/charts/{id}":{"get":{"summary":"Get a chart","description":"Retrieves a chart by ID, including the content of its latest version (name, SQL query, chart type, axes) and its dashboard placement. Requires admin access to the organization.","tags":["Charts"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Chart ID"},"required":true,"description":"Chart ID","name":"id","in":"path"}],"responses":{"200":{"description":"Chart retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChartResponse"}},"required":["data"]}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Chart not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a chart","description":"Updates a chart. Content changes (name, SQL query, chart type, axes, etc.) create a new chart version behind the scenes so the version history is preserved. Placement changes (dashboardId, dashboardTabId, layout) move or resize the chart without creating a version. Requires admin access to the organization.","tags":["Charts"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Chart ID"},"required":true,"description":"Chart ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateChartInput"}}}},"responses":{"200":{"description":"Chart updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChartResponse"}},"required":["data"]}}}},"400":{"description":"Bad request - Invalid JSON body or validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Organization trial has expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Chart not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a chart","description":"Archives a chart by ID and removes it from its dashboard. Requires admin access to the organization.","tags":["Charts"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Chart ID"},"required":true,"description":"Chart ID","name":"id","in":"path"}],"responses":{"204":{"description":"Chart archived successfully"},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Chart not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/charts/{id}/image":{"get":{"summary":"Get a chart image","description":"Renders a chart as a PNG image. Works for any chart the API key owner can access: charts on dashboards, charts created in chats, and insight charts. The image only includes data the API key owner is allowed to see. Pass chartVersionId to render a specific version; otherwise the latest version is rendered. Rendered images are cached per chart version.","tags":["Charts"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Chart ID"},"required":true,"description":"Chart ID","name":"id","in":"path"},{"schema":{"type":"string","description":"Chart version to render. Defaults to the latest version of the chart."},"required":false,"description":"Chart version to render. Defaults to the latest version of the chart.","name":"chartVersionId","in":"query"}],"responses":{"200":{"description":"PNG chart image","content":{"image/png":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Chart not found or no access to the chart","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/groups":{"get":{"summary":"List groups","description":"Lists all groups for an organization. Requires admin access to the organization. Results are paginated and ordered by creation date (newest first).","tags":["Groups"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Maximum number of items to return (1-100, default 50)"},"required":false,"description":"Maximum number of items to return (1-100, default 50)","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination (ID of the last item from previous page)"},"required":false,"description":"Cursor for pagination (ID of the last item from previous page)","name":"cursor","in":"query"}],"responses":{"200":{"description":"Groups retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GroupResponse"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Organization not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a group","description":"Creates a new group within an organization. Requires admin access to the organization.","tags":["Groups"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Name of the group"},"description":{"type":["string","null"],"description":"Optional description of the group"}},"required":["name"]}}}},"responses":{"201":{"description":"Group created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GroupResponse"}},"required":["data"]}}}},"400":{"description":"Bad request - Invalid JSON body or validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Organization not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/groups/{id}":{"get":{"summary":"Get a group","description":"Retrieves a group by ID. Requires admin access to the organization.","tags":["Groups"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Group ID"},"required":true,"description":"Group ID","name":"id","in":"path"}],"responses":{"200":{"description":"Group retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GroupResponse"}},"required":["data"]}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Group not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a group","description":"Updates an existing group. Requires admin access to the organization.","tags":["Groups"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Group ID"},"required":true,"description":"Group ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Name of the group"},"description":{"type":["string","null"],"description":"Optional description of the group"}}}}}},"responses":{"200":{"description":"Group updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GroupResponse"}},"required":["data"]}}}},"400":{"description":"Bad request - Invalid JSON body or validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Group not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a group","description":"Deletes a group by ID. Requires admin access to the organization.","tags":["Groups"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Group ID"},"required":true,"description":"Group ID","name":"id","in":"path"}],"responses":{"204":{"description":"Group deleted successfully"},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Group not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/groups/{id}/members":{"post":{"summary":"Add a member to a group","description":"Adds an active organization member or pending invite to a group. Requires admin access to the organization.","tags":["Groups"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Group ID"},"required":true,"description":"Group ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"memberId":{"type":"string","description":"Organization member ID to add to the group"}},"required":["memberId"]}}}},"responses":{"201":{"description":"Member added to group successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GroupMembershipResponse"}},"required":["data"]}}}},"400":{"description":"Bad request - Invalid JSON body or validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Group/member not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict - Member is already in the group","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/skills":{"get":{"summary":"List skills","description":"Lists all skills for an organization. Requires admin access to the organization. Results are paginated and ordered by creation date (newest first).","tags":["Skills"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Maximum number of items to return (1-100, default 50)"},"required":false,"description":"Maximum number of items to return (1-100, default 50)","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination (ID of the last item from previous page)"},"required":false,"description":"Cursor for pagination (ID of the last item from previous page)","name":"cursor","in":"query"}],"responses":{"200":{"description":"Skills retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SkillResponse"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","pagination"]}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Organization not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a skill","description":"Creates a new skill within an organization. Requires admin access to the organization.","tags":["Skills"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSkillInput"}}}},"responses":{"201":{"description":"Skill created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SkillResponse"}},"required":["data"]}}}},"400":{"description":"Bad request - Invalid JSON body or validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Organization not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/skills/{id}":{"get":{"summary":"Get a skill","description":"Retrieves a skill by ID. Requires admin access to the organization.","tags":["Skills"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Skill ID"},"required":true,"description":"Skill ID","name":"id","in":"path"}],"responses":{"200":{"description":"Skill retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SkillResponse"}},"required":["data"]}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Skill not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a skill","description":"Updates an existing skill. Requires admin access to the organization.","tags":["Skills"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Skill ID"},"required":true,"description":"Skill ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSkillInput"}}}},"responses":{"200":{"description":"Skill updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SkillResponse"}},"required":["data"]}}}},"400":{"description":"Bad request - Invalid JSON body or validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Skill not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a skill","description":"Deletes a skill by ID. Requires admin access to the organization.","tags":["Skills"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Skill ID"},"required":true,"description":"Skill ID","name":"id","in":"path"}],"responses":{"204":{"description":"Skill deleted successfully"},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Skill not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/chats":{"get":{"summary":"List chats","description":"Lists chats created through the API, newest first. Only chats the API key owner has access to are returned.","tags":["Chats"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Maximum number of items to return (1-100, default 50)"},"required":false,"description":"Maximum number of items to return (1-100, default 50)","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination (ID of the last item from previous page)"},"required":false,"description":"Cursor for pagination (ID of the last item from previous page)","name":"cursor","in":"query"}],"responses":{"200":{"description":"Chats retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicChatListResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Organization not found or no member access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Start a chat","description":"Sends a message to the AI agent in a new chat, like sending the first message in the app. The response includes the new chat, your message, and the assistant message. The assistant responds asynchronously by default: use the `wait` parameter to receive the finished response directly, or poll the assistant message (or stream its events) after receiving HTTP 202. To continue the conversation, use \"Send a follow-up message\".","tags":["Chats"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":300,"description":"Maximum number of seconds (1-300) to hold the request open while the assistant responds. If the response finishes in time the completed message is returned; otherwise the request returns HTTP 202 with the in-progress message. Omit to return immediately."},"required":false,"description":"Maximum number of seconds (1-300) to hold the request open while the assistant responds. If the response finishes in time the completed message is returned; otherwise the request returns HTTP 202 with the in-progress message. Omit to return immediately.","name":"wait","in":"query"},{"schema":{"type":"string","maxLength":255,"description":"A unique key (up to 255 characters) that makes retries safe: repeating a request with the same key returns the original result instead of creating a duplicate."},"required":false,"description":"A unique key (up to 255 characters) that makes retries safe: repeating a request with the same key returns the original result instead of creating a duplicate.","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePublicChatInput"}}}},"responses":{"200":{"description":"The Idempotency-Key was already used, so the existing chat is returned instead of creating a duplicate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicChatTurnResponse"}}}},"201":{"description":"Chat created and the assistant finished responding","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicChatTurnResponse"}}}},"202":{"description":"Chat created; the assistant is still responding","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicChatTurnResponse"}}}},"400":{"description":"Bad request - Invalid JSON body or validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Organization trial has expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Organization not found or no member access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/chats/{chatId}":{"get":{"summary":"Get a chat","description":"Retrieves a single chat, including its name and whether the assistant is currently responding.","tags":["Chats"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Chat ID"},"required":true,"description":"Chat ID","name":"chatId","in":"path"}],"responses":{"200":{"description":"Chat retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicChatResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Chat not found or no member access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a chat","description":"Permanently deletes a chat and all of its messages, canceling any response that is still generating.","tags":["Chats"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Chat ID"},"required":true,"description":"Chat ID","name":"chatId","in":"path"}],"responses":{"204":{"description":"Chat deleted successfully"},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Chat not found or no manage access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/chats/{chatId}/messages":{"get":{"summary":"List messages in a chat","description":"Lists the messages in a chat, newest first. Each message includes its plain-text content plus structured parts (reasoning, tool activity, and referenced charts).","tags":["Chats"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Chat ID"},"required":true,"description":"Chat ID","name":"chatId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Maximum number of items to return (1-100, default 50)"},"required":false,"description":"Maximum number of items to return (1-100, default 50)","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination (ID of the last item from previous page)"},"required":false,"description":"Cursor for pagination (ID of the last item from previous page)","name":"cursor","in":"query"}],"responses":{"200":{"description":"Messages retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicChatMessageListResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Chat not found or no member access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Send a follow-up message","description":"Sends the next message in an existing chat, continuing the conversation. Works like \"Start a chat\": use the `wait` parameter to receive the finished response directly, or poll the assistant message (or stream its events) after receiving HTTP 202. Only one response can be generating per chat at a time; sending while the assistant is busy returns HTTP 409.","tags":["Chats"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Chat ID"},"required":true,"description":"Chat ID","name":"chatId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":300,"description":"Maximum number of seconds (1-300) to hold the request open while the assistant responds. If the response finishes in time the completed message is returned; otherwise the request returns HTTP 202 with the in-progress message. Omit to return immediately."},"required":false,"description":"Maximum number of seconds (1-300) to hold the request open while the assistant responds. If the response finishes in time the completed message is returned; otherwise the request returns HTTP 202 with the in-progress message. Omit to return immediately.","name":"wait","in":"query"},{"schema":{"type":"string","maxLength":255,"description":"A unique key (up to 255 characters) that makes retries safe: repeating a request with the same key returns the original result instead of creating a duplicate."},"required":false,"description":"A unique key (up to 255 characters) that makes retries safe: repeating a request with the same key returns the original result instead of creating a duplicate.","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendPublicChatMessageInput"}}}},"responses":{"200":{"description":"The assistant finished responding","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicChatTurnResponse"}}}},"202":{"description":"Message sent; the assistant is still responding","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicChatTurnResponse"}}}},"400":{"description":"Bad request - Invalid JSON body or validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Organization trial has expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Chat not found or no edit access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict - The assistant is still responding to an earlier message in this chat. Wait for it to finish or cancel it first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/chats/{chatId}/messages/{messageId}":{"get":{"summary":"Get a message","description":"Retrieves a single message. Poll this endpoint after receiving HTTP 202 to check whether the assistant has finished responding; the message status becomes `finished` when the response is complete.","tags":["Chats"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Chat ID"},"required":true,"description":"Chat ID","name":"chatId","in":"path"},{"schema":{"type":"string","description":"Message ID"},"required":true,"description":"Message ID","name":"messageId","in":"path"}],"responses":{"200":{"description":"Message retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicChatMessageResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Message not found or no member access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/chats/{chatId}/messages/{messageId}/cancel":{"post":{"summary":"Cancel a response","description":"Stops an assistant response that is still generating. Calling this again, or after the response has already finished, is safe and returns the current message.","tags":["Chats"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Chat ID"},"required":true,"description":"Chat ID","name":"chatId","in":"path"},{"schema":{"type":"string","description":"Assistant message ID"},"required":true,"description":"Assistant message ID","name":"messageId","in":"path"}],"responses":{"200":{"description":"Message generation canceled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicChatMessageResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Message not found or no edit access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{orgId}/chats/{chatId}/messages/{messageId}/events":{"get":{"summary":"Stream an assistant message","description":"Streams an assistant message over Server-Sent Events while it generates. You receive a `snapshot` event with the full message on connect, `content` events as content parts are added or updated, and a `done` event with the final message when the response completes. If the connection drops, reconnect with the Last-Event-ID header set to the id of the last event you received to resume where you left off.","tags":["Chats"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Chat ID"},"required":true,"description":"Chat ID","name":"chatId","in":"path"},{"schema":{"type":"string","description":"Assistant message ID"},"required":true,"description":"Assistant message ID","name":"messageId","in":"path"},{"schema":{"type":"string","description":"The id of the last event received. On reconnect, streaming resumes after this event instead of restarting from a full snapshot."},"required":false,"description":"The id of the last event received. On reconnect, streaming resumes after this event instead of restarting from a full snapshot.","name":"Last-Event-ID","in":"header"}],"responses":{"200":{"description":"SSE stream opened successfully","content":{"text/event-stream":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Message not found or no member access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{id}":{"get":{"summary":"Get an organization","description":"Retrieves an organization by ID. Requires membership in the organization.","tags":["Organizations"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"id","in":"path"},{"schema":{"type":"string","enum":["jwtSecret"],"description":"Include sensitive fields in the response. Use `jwtSecret` to include the embed JWT secret (requires admin access)."},"required":false,"description":"Include sensitive fields in the response. Use `jwtSecret` to include the embed JWT secret (requires admin access).","name":"include","in":"query"}],"responses":{"200":{"description":"Organization retrieved successfully. The `jwtSecret` field is only included when explicitly requested via `?include=jwtSecret` and the user has admin access.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Organization ID"},"name":{"type":"string","description":"Name of the organization"},"slug":{"type":"string","description":"URL-friendly slug"},"customAiContext":{"type":["string","null"],"description":"Custom context for AI"},"insightsAiContext":{"type":["string","null"],"description":"Custom context injected into AI-generated insights"},"onboardingStatus":{"type":"string","enum":["STARTED","COMPLETED"],"description":"Onboarding status"},"fullEmbedEnabled":{"type":"boolean","description":"Full embed enabled flag"},"embedAllowedOrigins":{"type":"array","items":{"type":"string"},"description":"Allowed embed origins"},"isBillable":{"type":"boolean","description":"[Self-hosted] Whether the organization is billable. Defaults to true. Relevant for self-hosted deployments where billing gates certain features. When false, the organization will not be counted towards billable usage and will have a limited set of features. When true, the organization will be counted towards billable usage (after a 14-day trial) and will have access to all features."},"insightsEnabled":{"type":"boolean","description":"Whether automated insights generation is enabled for this organization."},"insightsFrequency":{"type":"string","enum":["DAILY","WEEKDAYS","WEEKLY","MONTHLY","NEVER"],"description":"How often automated insights are generated. NEVER means automatic generation is disabled."},"insightsPreferredDayOfWeek":{"type":["number","null"],"description":"Preferred day of week for weekly insights. 0 is Sunday."},"insightsPreferredDayOfMonth":{"type":["number","null"],"description":"Preferred day of month for monthly insights."},"allowOnDemandAiUsage":{"type":"boolean","description":"Whether the organization can continue using AI beyond included monthly AI credits."},"aiUsageOverageLimitCents":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":2147483647,"description":"Maximum AI usage overage for the organization in cents. Null means no limit."},"billingEmail":{"type":"string","description":"Email address used for billing communication and invoices"},"sendInvoicesToBillingEmail":{"type":"boolean","description":"Whether paid invoices are emailed to the billing email address"},"defaultDashboardAccessAudience":{"type":"string","enum":["EVERYONE","CREATOR_ONLY","CREATOR_GROUPS"],"description":"Default audience for newly created dashboards"},"defaultDashboardAccessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW"],"description":"Default permission level for the audience. Creator always gets MANAGE regardless."},"defaultChatAccessAudience":{"type":"string","enum":["EVERYONE","CREATOR_ONLY","CREATOR_GROUPS"],"description":"Default audience for newly created chats"},"defaultChatAccessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW"],"description":"Default permission level for new chats. Creator always gets MANAGE regardless."},"defaultAutomationAccessAudience":{"type":"string","enum":["EVERYONE","CREATOR_ONLY","CREATOR_GROUPS"],"description":"Default audience for newly created automations"},"defaultAutomationAccessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW"],"description":"Default permission level for new automations. Creator always gets MANAGE regardless."},"trialEndsAt":{"type":["string","null"],"description":"[Self-hosted] ISO 8601 date when the trial ends, or null if no trial. Trial starts after the organization is created and becomes billable."},"jwtSecret":{"type":"string","description":"JWT secret for embedding. Only returned when `?include=jwtSecret` is specified and the user has admin access."}},"required":["id","name","slug","customAiContext","insightsAiContext","onboardingStatus","fullEmbedEnabled","embedAllowedOrigins","isBillable","insightsEnabled","insightsFrequency","insightsPreferredDayOfWeek","insightsPreferredDayOfMonth","allowOnDemandAiUsage","aiUsageOverageLimitCents","billingEmail","sendInvoicesToBillingEmail","defaultDashboardAccessAudience","defaultDashboardAccessLevel","defaultChatAccessAudience","defaultChatAccessLevel","defaultAutomationAccessAudience","defaultAutomationAccessLevel","trialEndsAt"]}},"required":["data"]}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Organization not found or no membership","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an organization","description":"Updates an existing organization. Requires admin access.","tags":["Organizations"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"id","in":"path"},{"schema":{"type":"string","enum":["jwtSecret"],"description":"Include sensitive fields in the response. Use `jwtSecret` to include the embed JWT secret."},"required":false,"description":"Include sensitive fields in the response. Use `jwtSecret` to include the embed JWT secret.","name":"include","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Name of the organization"},"customAiContext":{"type":"string","description":"Custom context for AI features"},"insightsAiContext":{"type":["string","null"],"description":"Custom context for AI-generated insights"},"skipOnboarding":{"type":"boolean","description":"Skip onboarding flow"},"fullEmbedEnabled":{"type":"boolean","description":"Enable full embed functionality"},"embedAllowedOrigins":{"type":"array","items":{"type":"string"},"description":"Allowed origins for embedding. Supports exact URLs (https://example.com) and wildcard patterns (https://*.example.com)"},"isBillable":{"type":"boolean","description":"[Self-hosted] Controls whether the organization is billable. Defaults to true. Relevant for self-hosted deployments where billing gates certain features. When false, the organization will not be counted towards billable usage and will have a limited set of features. When true, the organization will be counted towards billable usage (after a 14-day trial) and will have access to all features."},"insightsEnabled":{"type":"boolean","description":"Enable automated insights generation for this organization. Defaults to true."},"insightsFrequency":{"type":"string","enum":["DAILY","WEEKDAYS","WEEKLY","MONTHLY","NEVER"],"description":"How often automated insights are generated. Defaults to DAILY."},"insightsPreferredDayOfWeek":{"type":"integer","minimum":0,"maximum":6,"description":"Preferred day of week for WEEKLY insights. 0 is Sunday."},"insightsPreferredDayOfMonth":{"type":"integer","minimum":1,"maximum":31,"description":"Preferred day of month for MONTHLY insights."},"allowOnDemandAiUsage":{"type":"boolean","description":"Allow users in the organization to continue using AI beyond included monthly AI credits. Defaults to true."},"aiUsageOverageLimitCents":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":2147483647,"description":"Maximum AI usage overage for the organization in cents. Null means no limit. Only applies when on-demand AI usage is enabled."},"billingEmail":{"type":"string","format":"email","description":"Email address used for billing communication and invoices"},"sendInvoicesToBillingEmail":{"type":"boolean","description":"Whether paid invoices are emailed to the billing email address"},"defaultDashboardAccessAudience":{"type":"string","enum":["EVERYONE","CREATOR_ONLY","CREATOR_GROUPS"],"description":"Default audience for newly created dashboards"},"defaultDashboardAccessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW"],"description":"Default permission level for the audience. Creator always gets MANAGE regardless."},"defaultChatAccessAudience":{"type":"string","enum":["EVERYONE","CREATOR_ONLY","CREATOR_GROUPS"],"description":"Default audience for newly created chats"},"defaultChatAccessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW"],"description":"Default permission level for new chats. Creator always gets MANAGE regardless."},"defaultAutomationAccessAudience":{"type":"string","enum":["EVERYONE","CREATOR_ONLY","CREATOR_GROUPS"],"description":"Default audience for newly created automations"},"defaultAutomationAccessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW"],"description":"Default permission level for new automations. Creator always gets MANAGE regardless."}}}}}},"responses":{"200":{"description":"Organization updated successfully. The `jwtSecret` field is only included when explicitly requested via `?include=jwtSecret`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Organization ID"},"name":{"type":"string","description":"Name of the organization"},"slug":{"type":"string","description":"URL-friendly slug"},"customAiContext":{"type":["string","null"],"description":"Custom context for AI"},"insightsAiContext":{"type":["string","null"],"description":"Custom context injected into AI-generated insights"},"onboardingStatus":{"type":"string","enum":["STARTED","COMPLETED"],"description":"Onboarding status"},"fullEmbedEnabled":{"type":"boolean","description":"Full embed enabled flag"},"embedAllowedOrigins":{"type":"array","items":{"type":"string"},"description":"Allowed embed origins"},"isBillable":{"type":"boolean","description":"[Self-hosted] Whether the organization is billable. Defaults to true. Relevant for self-hosted deployments where billing gates certain features. When false, the organization will not be counted towards billable usage and will have a limited set of features. When true, the organization will be counted towards billable usage (after a 14-day trial) and will have access to all features."},"insightsEnabled":{"type":"boolean","description":"Whether automated insights generation is enabled for this organization."},"insightsFrequency":{"type":"string","enum":["DAILY","WEEKDAYS","WEEKLY","MONTHLY","NEVER"],"description":"How often automated insights are generated. NEVER means automatic generation is disabled."},"insightsPreferredDayOfWeek":{"type":["number","null"],"description":"Preferred day of week for weekly insights. 0 is Sunday."},"insightsPreferredDayOfMonth":{"type":["number","null"],"description":"Preferred day of month for monthly insights."},"allowOnDemandAiUsage":{"type":"boolean","description":"Whether the organization can continue using AI beyond included monthly AI credits."},"aiUsageOverageLimitCents":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":2147483647,"description":"Maximum AI usage overage for the organization in cents. Null means no limit."},"billingEmail":{"type":"string","description":"Email address used for billing communication and invoices"},"sendInvoicesToBillingEmail":{"type":"boolean","description":"Whether paid invoices are emailed to the billing email address"},"defaultDashboardAccessAudience":{"type":"string","enum":["EVERYONE","CREATOR_ONLY","CREATOR_GROUPS"],"description":"Default audience for newly created dashboards"},"defaultDashboardAccessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW"],"description":"Default permission level for the audience. Creator always gets MANAGE regardless."},"defaultChatAccessAudience":{"type":"string","enum":["EVERYONE","CREATOR_ONLY","CREATOR_GROUPS"],"description":"Default audience for newly created chats"},"defaultChatAccessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW"],"description":"Default permission level for new chats. Creator always gets MANAGE regardless."},"defaultAutomationAccessAudience":{"type":"string","enum":["EVERYONE","CREATOR_ONLY","CREATOR_GROUPS"],"description":"Default audience for newly created automations"},"defaultAutomationAccessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW"],"description":"Default permission level for new automations. Creator always gets MANAGE regardless."},"trialEndsAt":{"type":["string","null"],"description":"[Self-hosted] ISO 8601 date when the trial ends, or null if no trial. Trial starts after the organization is created and becomes billable."},"jwtSecret":{"type":"string","description":"JWT secret for embedding. Only returned when `?include=jwtSecret` is specified and the user has admin access."}},"required":["id","name","slug","customAiContext","insightsAiContext","onboardingStatus","fullEmbedEnabled","embedAllowedOrigins","isBillable","insightsEnabled","insightsFrequency","insightsPreferredDayOfWeek","insightsPreferredDayOfMonth","allowOnDemandAiUsage","aiUsageOverageLimitCents","billingEmail","sendInvoicesToBillingEmail","defaultDashboardAccessAudience","defaultDashboardAccessLevel","defaultChatAccessAudience","defaultChatAccessLevel","defaultAutomationAccessAudience","defaultAutomationAccessLevel","trialEndsAt"]}},"required":["data"]}}}},"400":{"description":"Bad request - Invalid JSON body or validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Organization not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/public/organizations/{id}/icon":{"post":{"summary":"Upload organization icon","description":"Uploads an icon image for an organization. The image is stored and the organization is updated with the new icon URL. Requires admin access.","tags":["Organizations"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"id","in":"path"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"icon":{"type":"string","format":"binary","description":"Image file (JPEG or PNG). Maximum size: 2 MB."}}}}}},"responses":{"200":{"description":"Icon uploaded successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"iconUrl":{"type":"string","description":"URL of the uploaded icon"}},"required":["iconUrl"]}},"required":["data"]}}}},"400":{"description":"Bad request - Invalid file type, missing file, or malformed request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Organization not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Payload too large - File size exceeds 2 MB limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded - Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Service unavailable - S3 storage is not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/sso/jwt":{"get":{"summary":"JWT authentication","description":"Validates a JWT signed by the embedding application and creates a Basedash session for the user specified in the JWT claims. On success, redirects to the organization dashboard.","tags":["Embedding"],"security":[],"x-mint":{"content":"## When to use\n\nThis endpoint is used for **full app embedding** - embedding the entire Basedash application within your own product via an iframe. This allows your users to access Basedash dashboards without leaving your application or managing separate Basedash credentials.\n\n## How it works\n\n1. Your server generates a JWT containing user information, signed with your organization's embed JWT secret\n2. You set the iframe `src` to this endpoint with the JWT as a query parameter\n3. Basedash validates the JWT signature against your organization's secret\n4. If valid, Basedash creates or updates the user account and establishes a session\n5. The user is redirected to your organization's dashboard inside the iframe\n\n## Setup requirements\n\nBefore using this endpoint, you must:\n\n1. **Enable embedding** for your organization via the API or Basedash settings\n2. **Store the embed JWT secret** returned when creating/updating your organization - this is used to sign your JWTs\n3. **Configure allowed origins** (recommended) to restrict which domains can embed your Basedash organization\n\n## JWT structure\n\nSign your JWT using the HS256 algorithm with your organization's `jwtSecret`. The JWT payload should contain:\n\n```json\n{\n  \"email\": \"user@example.com\",\n  \"orgId\": \"org_abc123\",\n  \"firstName\": \"Jane\",\n  \"lastName\": \"Doe\",\n  \"role\": \"MEMBER\",\n  \"exp\": 1234567890,\n  \"iat\": 1234567800\n}\n```\n\n## Example implementation\n\n```html\n<iframe \n  src=\"https://charts.basedash.com/api/sso/jwt?jwt=YOUR_JWT_TOKEN\"\n  width=\"100%\"\n  height=\"600\"\n  frameborder=\"0\"\n/>\n```\n\n```javascript\n// Server-side JWT generation (Node.js example)\nimport jwt from 'jsonwebtoken';\n\nconst token = jwt.sign(\n  {\n    email: user.email,\n    orgId: 'org_abc123',\n    firstName: user.firstName,\n    lastName: user.lastName,\n    role: 'MEMBER',\n  },\n  process.env.BASEDASH_EMBED_JWT_SECRET,\n  { expiresIn: '10m' }\n);\n```\n\n## Security considerations\n\n- **Keep your JWT secret secure** - Never expose it in client-side code\n- **Use short expiration times** - JWTs should expire within minutes\n- **Configure allowed origins** - Restrict embedding to your domains only\n- **Generate JWTs server-side** - Never generate JWTs in the browser"},"parameters":[{"schema":{"type":"string","description":"JWT token signed with your organization embed secret (HS256)"},"required":true,"description":"JWT token signed with your organization embed secret (HS256)","name":"jwt","in":"query"}],"responses":{"302":{"description":"Redirect to organization dashboard on successful authentication","headers":{"Location":{"schema":{"type":"string","description":"URL to the organization dashboard"},"required":true,"description":"URL to the organization dashboard"},"Set-Cookie":{"schema":{"type":"string","description":"Session cookie"},"required":true,"description":"Session cookie"}}},"400":{"description":"Bad request - Missing JWT, invalid format, or invalid claims","content":{"text/html":{"schema":{"type":"string","description":"HTML error page"}}}},"401":{"description":"Unauthorized - JWT signature verification failed or expired","content":{"text/html":{"schema":{"type":"string","description":"HTML error page"}}}},"403":{"description":"Forbidden - Embedding not enabled or request from disallowed origin","content":{"text/html":{"schema":{"type":"string","description":"HTML error page"}}}},"404":{"description":"Not found - Organization not found","content":{"text/html":{"schema":{"type":"string","description":"HTML error page"}}}},"500":{"description":"Internal server error","content":{"text/html":{"schema":{"type":"string","description":"HTML error page"}}}}}}}},"webhooks":{}}