{"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":"Models","description":"Manage reusable SQL models"},{"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":["MEMBER","ADMIN","VIEWER"],"description":"Managed membership role. Applied on every login when supplied; new memberships default to MEMBER."},"groups":{"type":"array","items":{"type":"string"},"description":"Names of existing Basedash groups the user belongs to (case-insensitive). Applied on every login when supplied: the user is added to the named groups and removed from groups this claim added earlier. Memberships set in Basedash, through the API or by SCIM are never removed, unknown names are skipped, and groups are never created."},"exp":{"type":"number","description":"JWT expiration timestamp (Unix seconds)"},"iat":{"type":"number","description":"JWT issued-at timestamp (Unix seconds)"}},"required":["email","orgId","exp","iat"]},"PublicBillingAccount":{"type":"object","properties":{"id":{"type":"string","description":"Billing account ID"},"name":{"type":"string","description":"Name of the billing account"},"isActive":{"type":"boolean","description":"Whether the billing account is active. Attached organizations lose paid coverage when the account is inactive."},"ownerOrganizationId":{"type":"string","description":"Organization whose admins manage this billing account. Attach and detach operations require admin access to this organization."},"subscriptionStatus":{"type":["string","null"],"description":"Stripe subscription status for the billing account, or null when billing is managed outside Stripe."},"platformFeeWaived":{"type":"boolean","description":"Whether the per-organization platform fee is waived for this account."},"aiUsageIncludedCreditsCents":{"type":"integer","description":"Included AI usage credits in cents, pooled across all attached organizations per billing period."},"allowOnDemandAiUsage":{"type":"boolean","description":"Whether the billing account can continue using AI beyond its pooled included credits. This is a hard gate for every attached organization in addition to each organization’s own setting."},"aiUsageOverageLimitCents":{"type":["integer","null"],"description":"Maximum AI usage overage for the whole billing account in cents. This hard cap applies across all attached organizations in addition to any organization-level cap. Null means no account limit."},"billingPeriodStart":{"type":["string","null"],"description":"Billing period start"},"billingPeriodEnd":{"type":["string","null"],"description":"Billing period end"},"organizationCount":{"type":"integer","description":"Number of organizations attached to this billing account"},"createdAt":{"type":"string","description":"Creation timestamp"}},"required":["id","name","isActive","ownerOrganizationId","subscriptionStatus","platformFeeWaived","aiUsageIncludedCreditsCents","allowOnDemandAiUsage","aiUsageOverageLimitCents","billingPeriodStart","billingPeriodEnd","organizationCount","createdAt"]},"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"]}]},"PublicBillingAccountOrganization":{"type":"object","properties":{"id":{"type":"string","description":"Organization ID"},"name":{"type":"string","description":"Name of the organization"},"slug":{"type":"string","description":"URL-friendly slug"},"isBillable":{"type":"boolean","description":"Whether the organization counts toward the billing account platform fee quantity"},"attachedIsSelf":{"type":"boolean","description":"Whether this organization is the billing account owner organization"},"createdAt":{"type":"string","description":"Creation timestamp"}},"required":["id","name","slug","isBillable","createdAt"]},"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"]},"PublicBillingAccountOrganizationDetached":{"type":"object","properties":{"id":{"type":"string","description":"Organization ID"},"billingAccountId":{"type":"string","description":"Billing account ID"},"detached":{"type":"boolean","enum":[true],"description":"Whether the organization is detached"}},"required":["id","billingAccountId","detached"]},"PublicBillingAccountAiUsageResponse":{"type":"object","properties":{"totalUsage":{"type":"number","description":"Total billable AI usage pooled across all attached organizations for the billing period, in USD dollars"},"includedCredits":{"type":"number","description":"Included AI usage credits for the account 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"},"organizationUsage":{"type":"array","items":{"$ref":"#/components/schemas/PublicBillingAccountOrganizationUsage"},"description":"Billable AI usage grouped by attached organization"}},"required":["totalUsage","includedCredits","billingPeriodStart","billingPeriodEnd","organizationUsage"]},"PublicBillingAccountOrganizationUsage":{"type":"object","properties":{"organizationId":{"type":"string","description":"Organization ID"},"name":{"type":"string","description":"Name of the organization"},"slug":{"type":"string","description":"URL-friendly slug"},"usage":{"type":"number","description":"Billable AI usage for this organization in USD dollars"}},"required":["organizationId","name","slug","usage"]},"DatabaseDialect":{"anyOf":[{"type":"string","enum":["ELASTICSEARCH"]},{"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"]},{"type":"string","enum":["MOTHERDUCK"]}],"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"},"objects":{"type":"array","items":{"type":"object","properties":{"schemaName":{"type":"string","description":"Schema name"},"tableName":{"type":["string","null"],"description":"Table name, or null for a schema-level rule"},"columnName":{"type":["string","null"],"description":"Column name, or null for a schema- or table-level rule"},"everyoneAccessLevel":{"type":["string","null"],"enum":["FULL","NO_ACCESS",null],"description":"Access for everyone in the organization, or null if unset"},"groupAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["FULL","NO_ACCESS"],"description":"FULL allows querying the object; NO_ACCESS blocks it in queries, chat, and metadata"}},"required":["id","accessLevel"]},"description":"Group rules on this object"},"memberAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["FULL","NO_ACCESS"],"description":"FULL allows querying the object; NO_ACCESS blocks it in queries, chat, and metadata"}},"required":["id","accessLevel"]},"description":"Member rules on this object"}},"required":["schemaName","tableName","columnName","everyoneAccessLevel","groupAccess","memberAccess"]},"description":"Schema, table, and column rules: objects with at least one rule, sorted by schema, table, and column"}},"required":["dataSourceId","mode","accessLevel","groupIds","memberIds","groupAccess","memberAccess","objects"]},"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"},"objects":{"type":"array","items":{"type":"object","properties":{"schemaName":{"type":"string","minLength":1,"description":"Schema name exactly as synced from the data source"},"tableName":{"type":["string","null"],"minLength":1,"description":"Table name exactly as synced. Omit or null for a schema-level rule."},"columnName":{"type":["string","null"],"minLength":1,"description":"Column name exactly as synced. Omit or null for a table-level rule. Requires tableName."},"everyoneAccessLevel":{"type":["string","null"],"enum":["FULL","NO_ACCESS",null],"description":"Access for everyone in the organization on this object. Omit or null for no everyone rule."},"groupAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["FULL","NO_ACCESS"],"description":"FULL allows querying the object; NO_ACCESS blocks it in queries, chat, and metadata"}},"required":["id","accessLevel"]},"maxItems":500,"default":[],"description":"Group rules on this object"},"memberAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["FULL","NO_ACCESS"],"description":"FULL allows querying the object; NO_ACCESS blocks it in queries, chat, and metadata"}},"required":["id","accessLevel"]},"maxItems":500,"default":[],"description":"Member rules on this object"}},"required":["schemaName"],"additionalProperties":false},"maxItems":1000,"description":"Schema, table, and column rules. Omit to leave existing object rules unchanged. The complete set of schema, table, and column rules for the data source (at most 5000 rules in total): objects not listed lose all of their rules, and an empty array removes every object rule."}},"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"},"objects":{"type":"array","items":{"type":"object","properties":{"schemaName":{"type":"string","minLength":1,"description":"Schema name exactly as synced from the data source"},"tableName":{"type":["string","null"],"minLength":1,"description":"Table name exactly as synced. Omit or null for a schema-level rule."},"columnName":{"type":["string","null"],"minLength":1,"description":"Column name exactly as synced. Omit or null for a table-level rule. Requires tableName."},"everyoneAccessLevel":{"type":["string","null"],"enum":["FULL","NO_ACCESS",null],"description":"Access for everyone in the organization on this object. Omit or null for no everyone rule."},"groupAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["FULL","NO_ACCESS"],"description":"FULL allows querying the object; NO_ACCESS blocks it in queries, chat, and metadata"}},"required":["id","accessLevel"]},"maxItems":500,"default":[],"description":"Group rules on this object"},"memberAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["FULL","NO_ACCESS"],"description":"FULL allows querying the object; NO_ACCESS blocks it in queries, chat, and metadata"}},"required":["id","accessLevel"]},"maxItems":500,"default":[],"description":"Member rules on this object"}},"required":["schemaName"],"additionalProperties":false},"maxItems":1000,"description":"Schema, table, and column rules. Omit to leave existing object rules unchanged. The complete set of schema, table, and column rules for the data source (at most 5000 rules in total): objects not listed lose all of their rules, and an empty array removes every object rule."}},"required":["mode"]},{"type":"object","properties":{"mode":{"type":"string","not":{},"description":"Leave mode out to keep connection-level access unchanged"},"objects":{"type":"array","items":{"type":"object","properties":{"schemaName":{"type":"string","minLength":1,"description":"Schema name exactly as synced from the data source"},"tableName":{"type":["string","null"],"minLength":1,"description":"Table name exactly as synced. Omit or null for a schema-level rule."},"columnName":{"type":["string","null"],"minLength":1,"description":"Column name exactly as synced. Omit or null for a table-level rule. Requires tableName."},"everyoneAccessLevel":{"type":["string","null"],"enum":["FULL","NO_ACCESS",null],"description":"Access for everyone in the organization on this object. Omit or null for no everyone rule."},"groupAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["FULL","NO_ACCESS"],"description":"FULL allows querying the object; NO_ACCESS blocks it in queries, chat, and metadata"}},"required":["id","accessLevel"]},"maxItems":500,"default":[],"description":"Group rules on this object"},"memberAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["FULL","NO_ACCESS"],"description":"FULL allows querying the object; NO_ACCESS blocks it in queries, chat, and metadata"}},"required":["id","accessLevel"]},"maxItems":500,"default":[],"description":"Member rules on this object"}},"required":["schemaName"],"additionalProperties":false},"maxItems":1000,"description":"Schema, table, and column rules. The complete set of schema, table, and column rules for the data source (at most 5000 rules in total): objects not listed lose all of their rules, and an empty array removes every object rule."}},"required":["objects"],"additionalProperties":false}]},"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"}}},"AutomationAccessResponse":{"type":"object","properties":{"automationId":{"type":"string","description":"Automation ID"},"mode":{"type":"string","enum":["everyone","restricted"],"description":"everyone: all members have accessLevel, plus any listed principals. restricted: only listed principals, the creator and admins."},"accessLevel":{"type":["string","null"],"enum":["MANAGE","EDIT","VIEW",null],"description":"Access level for every member when mode is everyone"},"groupAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW","NONE"],"description":"MANAGE can edit and change access, EDIT can edit, VIEW can view. NONE explicitly denies this principal, overriding group or everyone access."}},"required":["id","accessLevel"]},"description":"Organization groups and their access level"},"memberAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW","NONE"],"description":"MANAGE can edit and change access, EDIT can edit, VIEW can view. NONE explicitly denies this principal, overriding group or everyone access."}},"required":["id","accessLevel"]},"description":"Organization members and their access level"}},"required":["automationId","mode","accessLevel","groupAccess","memberAccess"]},"UpdateAutomationAccessInput":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["everyone"]},"accessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW"],"default":"VIEW","description":"Access level for every member of the organization"},"groupAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW","NONE"],"default":"VIEW","description":"MANAGE can edit and change access, EDIT can edit, VIEW can view. NONE explicitly denies this principal, overriding group or everyone access."}},"required":["id"]},"maxItems":500,"description":"Organization groups and their access level. Required: send [] for none."},"memberAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW","NONE"],"default":"VIEW","description":"MANAGE can edit and change access, EDIT can edit, VIEW can view. NONE explicitly denies this principal, overriding group or everyone access."}},"required":["id"]},"maxItems":500,"description":"Organization members and their access level. Required: send [] for none."}},"required":["mode","groupAccess","memberAccess"]},{"type":"object","properties":{"mode":{"type":"string","enum":["restricted"]},"groupAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW","NONE"],"default":"VIEW","description":"MANAGE can edit and change access, EDIT can edit, VIEW can view. NONE explicitly denies this principal, overriding group or everyone access."}},"required":["id"]},"maxItems":500,"description":"Organization groups and their access level. Required: send [] for none."},"memberAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW","NONE"],"default":"VIEW","description":"MANAGE can edit and change access, EDIT can edit, VIEW can view. NONE explicitly denies this principal, overriding group or everyone access."}},"required":["id"]},"maxItems":500,"description":"Organization members and their access level. Required: send [] for none."}},"required":["mode","groupAccess","memberAccess"]}]},"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 answer as markdown. Internal chart tags are replaced with authenticated chart image URLs that require the same Bearer token as this request."},"charts":{"type":"array","items":{"$ref":"#/components/schemas/PublicAutomationRunChart"},"description":"Charts included in the final automation run response"}},"required":["finalMessageContent","charts"]}]},"PublicAutomationRunChart":{"type":"object","properties":{"id":{"type":"string","description":"Chart ID"},"chartVersionId":{"type":"string","description":"Chart version shown in the run"},"imageUrl":{"type":"string","format":"uri","description":"Authenticated public API URL for fetching the chart version as a PNG. Send the same Bearer token used for this request."}},"required":["id","chartVersionId","imageUrl"]},"ModelResponse":{"type":"object","properties":{"id":{"type":"string","description":"Model ID"},"createdAt":{"type":"string","format":"date-time","description":"Model creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Model last update timestamp"},"name":{"type":"string","description":"Human-readable model name"},"referenceName":{"type":"string","description":"Stable SQL reference name for the model"},"description":{"type":"string","description":"Model description"},"sqlQuery":{"type":"string","description":"SQL query for the latest model version"},"organizationId":{"type":"string","description":"Organization ID"},"databaseConnectionId":{"type":"string","description":"Data source ID"},"verifiedAt":{"type":["string","null"],"format":"date-time","description":"Verification timestamp for the current model SQL"},"verifiedByMemberId":{"type":["string","null"],"description":"Member who verified the current model SQL"},"columns":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","maxLength":10000},"synonyms":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":20},"type":{"type":"string","enum":["array","bigint","boolean","date","mixed","null","number","object","string","unknown"],"description":"Best-effort type inferred from sampled result values."},"nullable":{"type":"boolean","description":"Whether null or undefined appeared in sampled result values."},"example":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}],"description":"First non-null sampled value, normalized for JSON."},"sampleValues":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"description":"Distinct non-null sampled values (capped), normalized for JSON."}},"required":["name","type","nullable","example"]},"description":"Inferred result columns and their documentation"},"measures":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-z][a-z0-9_]*$"},"sql":{"type":"string","minLength":1,"maxLength":10000},"description":{"type":"string","maxLength":10000},"synonyms":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":20,"default":[]}},"required":["name","sql"]},"maxItems":50,"description":"Ordered reusable aggregate expressions"},"segments":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-z][a-z0-9_]*$"},"sql":{"type":"string","minLength":1,"maxLength":10000},"description":{"type":"string","maxLength":10000},"synonyms":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":20,"default":[]}},"required":["name","sql"]},"maxItems":50,"description":"Ordered reusable predicate expressions"},"defaultTimeColumn":{"type":["string","null"],"minLength":1,"maxLength":256,"description":"Default date result column"},"synonyms":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":20,"description":"Alternative model names"},"grain":{"type":"string","maxLength":10000,"description":"What one model row represents"},"keyColumns":{"type":"array","items":{"type":"string","minLength":1,"maxLength":256},"maxItems":10,"description":"Columns that uniquely identify a model row"},"relationships":{"type":"array","items":{"type":"object","properties":{"targetModelId":{"type":"string","minLength":1},"sourceColumn":{"type":"string","minLength":1,"maxLength":256},"targetColumn":{"type":"string","minLength":1,"maxLength":256},"cardinality":{"type":"string","enum":["many_to_one","one_to_one","one_to_many"]}},"required":["targetModelId","sourceColumn","targetColumn","cardinality"]},"maxItems":50,"description":"Relationships to other models"},"usageGuidance":{"type":"string","maxLength":10000,"description":"Guidance about when and how to use the model"},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["base_sql_contains_group_by","default_time_column_cleared","measure_may_not_aggregate","semantic_expression_may_be_stale"]},"message":{"type":"string"},"field":{"type":"string","enum":["sqlQuery","measures","segments","defaultTimeColumn"]},"name":{"type":"string"}},"required":["code","message","field"]},"description":"Non-blocking semantic metadata warnings"}},"required":["id","createdAt","updatedAt","name","referenceName","description","sqlQuery","organizationId","databaseConnectionId","verifiedAt","verifiedByMemberId","columns","measures","segments","defaultTimeColumn","synonyms","grain","keyColumns","relationships","usageGuidance","warnings"]},"ModelReferenceNameConflictErrorResponse":{"type":"object","properties":{"error":{"allOf":[{"$ref":"#/components/schemas/ApiError"},{"type":"object","properties":{"title":{"type":"string","enum":["Conflict"]},"referenceName":{"type":"string","description":"Normalized reference name that is already in use"},"suggestedReferenceName":{"type":"string","description":"An available reference name to retry with. Reference names are unique across the organization."}},"required":["referenceName","suggestedReferenceName"]}]}},"required":["error"]},"CreateModelInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Human-readable model name"},"referenceName":{"type":"string","minLength":1,"maxLength":100,"description":"Stable SQL reference name for the model"},"description":{"type":"string","maxLength":10000,"description":"Model description"},"databaseConnectionId":{"type":"string","description":"Data source ID"},"sqlQuery":{"type":"string","minLength":1,"maxLength":100000,"description":"SQL query that defines the reusable dataset"},"measures":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-z][a-z0-9_]*$"},"sql":{"type":"string","minLength":1,"maxLength":10000},"description":{"type":"string","maxLength":10000},"synonyms":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":20,"default":[]}},"required":["name","sql"]},"maxItems":50,"description":"Ordered reusable aggregate expressions"},"segments":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-z][a-z0-9_]*$"},"sql":{"type":"string","minLength":1,"maxLength":10000},"description":{"type":"string","maxLength":10000},"synonyms":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":20,"default":[]}},"required":["name","sql"]},"maxItems":50,"description":"Ordered reusable predicate expressions"},"defaultTimeColumn":{"type":["string","null"],"minLength":1,"maxLength":256,"description":"Default date result column, or null for no default"},"synonyms":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":20,"description":"Alternative names for the model"},"grain":{"type":"string","maxLength":10000,"description":"What one row in the model represents"},"keyColumns":{"type":"array","items":{"type":"string","minLength":1,"maxLength":256},"maxItems":10,"description":"Columns that uniquely identify a row"},"relationships":{"type":"array","items":{"type":"object","properties":{"targetModelId":{"type":"string","minLength":1},"sourceColumn":{"type":"string","minLength":1,"maxLength":256},"targetColumn":{"type":"string","minLength":1,"maxLength":256},"cardinality":{"type":"string","enum":["many_to_one","one_to_one","one_to_many"]}},"required":["targetModelId","sourceColumn","targetColumn","cardinality"]},"maxItems":50,"description":"Relationships from this model to other models"},"usageGuidance":{"type":"string","maxLength":10000,"description":"Guidance about when and how to use the model"},"columnSynonyms":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"synonyms":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":20}},"required":["name","synonyms"]},"description":"Alternative names for model result columns"}},"required":["name","databaseConnectionId","sqlQuery"]},"UpdateModelInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Human-readable model name"},"referenceName":{"type":"string","minLength":1,"maxLength":100,"description":"Stable SQL reference name for the model"},"description":{"type":"string","maxLength":10000,"description":"Model description"},"sqlQuery":{"type":"string","minLength":1,"maxLength":100000,"description":"SQL query that defines the reusable dataset"},"measures":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-z][a-z0-9_]*$"},"sql":{"type":"string","minLength":1,"maxLength":10000},"description":{"type":"string","maxLength":10000},"synonyms":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":20}},"required":["name","sql"]},"maxItems":50,"description":"Ordered reusable aggregate expressions"},"segments":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-z][a-z0-9_]*$"},"sql":{"type":"string","minLength":1,"maxLength":10000},"description":{"type":"string","maxLength":10000},"synonyms":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":20}},"required":["name","sql"]},"maxItems":50,"description":"Ordered reusable predicate expressions"},"defaultTimeColumn":{"type":["string","null"],"minLength":1,"maxLength":256,"description":"Default date result column, or null for no default"},"synonyms":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":20,"description":"Alternative names for the model"},"grain":{"type":"string","maxLength":10000,"description":"What one row in the model represents"},"keyColumns":{"type":"array","items":{"type":"string","minLength":1,"maxLength":256},"maxItems":10,"description":"Columns that uniquely identify a row"},"relationships":{"type":"array","items":{"type":"object","properties":{"targetModelId":{"type":"string","minLength":1},"sourceColumn":{"type":"string","minLength":1,"maxLength":256},"targetColumn":{"type":"string","minLength":1,"maxLength":256},"cardinality":{"type":"string","enum":["many_to_one","one_to_one","one_to_many"]}},"required":["targetModelId","sourceColumn","targetColumn","cardinality"]},"maxItems":50,"description":"Relationships from this model to other models"},"usageGuidance":{"type":"string","maxLength":10000,"description":"Guidance about when and how to use the model"},"columnSynonyms":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"synonyms":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":20}},"required":["name","synonyms"]},"description":"Alternative names for model result columns"},"verified":{"type":"boolean","description":"Whether the model is verified"}}},"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"},"numericalFormat":{"$ref":"#/components/schemas/NumericalFormat"},"currencyCode":{"type":["string","null"],"description":"ISO 4217 currency code (for example USD or EUR) used when numericalFormat is CURRENCY. Null uses USD."},"showFullNumbers":{"type":"boolean","description":"Show full numbers (1,234,567) instead of abbreviated ones (1.2M)."},"metricLabel":{"type":["string","null"],"description":"NUMBER charts: label shown with the value. Null uses the chart name."},"timeSeriesMetricType":{"$ref":"#/components/schemas/TimeSeriesMetricType"},"tableMetricType":{"$ref":"#/components/schemas/TableMetricType"},"showLegend":{"type":"boolean","description":"Show the series legend (LINE, VERTICAL_BAR, HORIZONTAL_BAR, PIE, FUNNEL and SCATTER charts)."},"goalLineValue":{"type":["number","null"],"description":"Value of the target (goal) line on LINE, VERTICAL_BAR and SCATTER charts. Null hides it."},"yAxisMinimum":{"type":["number","null"],"description":"Lower bound of the y-axis. Null picks it from the data."},"yAxisMaximum":{"type":["number","null"],"description":"Upper bound of the y-axis. Null picks it from the data."},"xAxisMinimum":{"type":["number","null"],"description":"SCATTER charts: lower bound of the x-axis. Null picks it from the data."},"xAxisMaximum":{"type":["number","null"],"description":"SCATTER charts: upper bound of the x-axis. Null picks it from the data."},"barMode":{"$ref":"#/components/schemas/BarMode"},"colorByCategory":{"type":"boolean","description":"Give each bar its own color by category on a single-series HORIZONTAL_BAR, categorical VERTICAL_BAR or FUNNEL chart. segmentColors are then keyed by category (xAxisProperty) value. Ignored while the chart has a breakdown."},"seriesColor":{"anyOf":[{"$ref":"#/components/schemas/ChartColor"},{"type":"null"}],"description":"Color of the series on a chart without a breakdown (LINE, VERTICAL_BAR, HORIZONTAL_BAR, FUNNEL, SCATTER). Null picks it automatically."},"segmentColors":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ChartColor"},"description":"Colors of segments, keyed by segment value: breakdown values on LINE, VERTICAL_BAR, HORIZONTAL_BAR, FUNNEL and SCATTER charts, slices on PIE charts, nodes on SANKEY charts, or categories with colorByCategory. Segments left out are colored automatically."},"imageProperty":{"type":["string","null"],"description":"IMAGE charts: result column holding the image URL."},"imageFit":{"$ref":"#/components/schemas/ImageFit"},"imageGrowToFit":{"type":"boolean","description":"IMAGE charts: grow the image to fill the card."},"textProperty":{"type":["string","null"],"description":"TEXT charts: result column holding the text to show."},"mapVariant":{"$ref":"#/components/schemas/MapVariant"},"tableColumns":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ChartTableColumn"},"description":"TABLE charts: column widths and pins, keyed by result column name. Columns left out use the defaults."},"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","numericalFormat","currencyCode","showFullNumbers","metricLabel","timeSeriesMetricType","tableMetricType","showLegend","goalLineValue","yAxisMinimum","yAxisMaximum","xAxisMinimum","xAxisMaximum","barMode","colorByCategory","seriesColor","segmentColors","imageProperty","imageFit","imageGrowToFit","textProperty","mapVariant","tableColumns","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"},"NumericalFormat":{"anyOf":[{"type":"string","enum":["NUMBER"]},{"type":"string","enum":["CURRENCY"]},{"type":"string","enum":["PERCENTAGE"]}],"description":"How values are formatted. PERCENTAGE expects values on a 0-100 scale (42.5 shows as 42.5%); it does not convert 0-1 ratios."},"TimeSeriesMetricType":{"anyOf":[{"type":"string","enum":["SUM"]},{"type":"string","enum":["LATEST"]},{"type":"string","enum":["AVERAGE"]},{"type":"string","enum":["NONE"]}],"description":"Summary value shown above LINE and VERTICAL_BAR charts: the SUM, AVERAGE or LATEST value of the series, or NONE to hide it. With a breakdown, NONE plus showLegend true shows segment labels only. PIE, FUNNEL and HORIZONTAL_BAR charts show the total unless this is NONE."},"TableMetricType":{"anyOf":[{"type":"string","enum":["NONE"]},{"type":"string","enum":["COUNT"]}],"description":"TABLE charts: COUNT shows the record count above the table, NONE hides it."},"BarMode":{"anyOf":[{"type":"string","enum":["STACKED"]},{"type":"string","enum":["GROUPED"]}],"description":"How bars of a VERTICAL_BAR or HORIZONTAL_BAR chart with a breakdown (xAxisSecondaryProperty) combine: STACKED or side by side (GROUPED)."},"ChartColor":{"type":"string","enum":["NEUTRAL","BLUE","ORANGE","PURPLE","RED","TEAL","GREEN","YELLOW","PINK"],"description":"A color from the chart palette. NEUTRAL is near-black in light mode and near-white in dark mode."},"ImageFit":{"anyOf":[{"type":"string","enum":["CONTAIN"]},{"type":"string","enum":["COVER"]}],"description":"IMAGE charts: whether the image covers the card or fits inside it."},"MapVariant":{"anyOf":[{"type":"string","enum":["WORLD"]},{"type":"string","enum":["UNITED_STATES"]}],"description":"MAP charts: WORLD (matches country names) or UNITED_STATES (matches state names)."},"ChartTableColumn":{"type":"object","properties":{"width":{"type":["number","null"],"minimum":0,"maximum":2147483647,"description":"Column width in pixels. Null sizes the column automatically."},"pinned":{"type":"boolean","description":"Whether the column is pinned to the left of the table."}},"required":["width","pinned"]},"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,"maxLength":500,"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"},"numericalFormat":{"$ref":"#/components/schemas/NumericalFormat"},"currencyCode":{"type":["string","null"],"description":"ISO 4217 currency code (for example USD or EUR) used when numericalFormat is CURRENCY. Null uses USD."},"showFullNumbers":{"type":"boolean","description":"Show full numbers (1,234,567) instead of abbreviated ones (1.2M)."},"metricLabel":{"type":["string","null"],"description":"NUMBER charts: label shown with the value. Null uses the chart name."},"timeSeriesMetricType":{"$ref":"#/components/schemas/TimeSeriesMetricType"},"tableMetricType":{"$ref":"#/components/schemas/TableMetricType"},"showLegend":{"type":"boolean","description":"Show the series legend (LINE, VERTICAL_BAR, HORIZONTAL_BAR, PIE, FUNNEL and SCATTER charts)."},"goalLineValue":{"type":["number","null"],"description":"Value of the target (goal) line on LINE, VERTICAL_BAR and SCATTER charts. Null hides it."},"yAxisMinimum":{"type":["number","null"],"description":"Lower bound of the y-axis. Null picks it from the data."},"yAxisMaximum":{"type":["number","null"],"description":"Upper bound of the y-axis. Null picks it from the data."},"xAxisMinimum":{"type":["number","null"],"description":"SCATTER charts: lower bound of the x-axis. Null picks it from the data."},"xAxisMaximum":{"type":["number","null"],"description":"SCATTER charts: upper bound of the x-axis. Null picks it from the data."},"barMode":{"$ref":"#/components/schemas/BarMode"},"colorByCategory":{"type":"boolean","description":"Give each bar its own color by category on a single-series HORIZONTAL_BAR, categorical VERTICAL_BAR or FUNNEL chart. segmentColors are then keyed by category (xAxisProperty) value. Ignored while the chart has a breakdown."},"seriesColor":{"anyOf":[{"$ref":"#/components/schemas/ChartColor"},{"type":"null"}],"description":"Color of the series on a chart without a breakdown (LINE, VERTICAL_BAR, HORIZONTAL_BAR, FUNNEL, SCATTER). Null picks it automatically."},"segmentColors":{"type":["object","null"],"additionalProperties":{"anyOf":[{"$ref":"#/components/schemas/ChartColor"},{"type":"null"}]},"description":"Colors of segments, keyed by segment value: breakdown values on LINE, VERTICAL_BAR, HORIZONTAL_BAR, FUNNEL and SCATTER charts, slices on PIE charts, nodes on SANKEY charts, or categories with colorByCategory. Segments left out are colored automatically. Merged by key: null for a segment resets it to automatic; null for the whole field resets every segment."},"imageProperty":{"type":["string","null"],"description":"IMAGE charts: result column holding the image URL."},"imageFit":{"$ref":"#/components/schemas/ImageFit"},"imageGrowToFit":{"type":"boolean","description":"IMAGE charts: grow the image to fill the card."},"textProperty":{"type":["string","null"],"description":"TEXT charts: result column holding the text to show."},"mapVariant":{"$ref":"#/components/schemas/MapVariant"},"tableColumns":{"type":["object","null"],"additionalProperties":{"anyOf":[{"$ref":"#/components/schemas/ChartTableColumnInput"},{"type":"null"}]},"description":"TABLE charts: column widths and pins, keyed by result column name. Columns left out use the defaults. Merged by column: a column given replaces that column's settings, null resets it; null for the whole field resets every column."}},"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."},"ChartTableColumnInput":{"type":"object","properties":{"width":{"type":["number","null"],"minimum":0,"maximum":2147483647,"description":"Column width in pixels. Null sizes the column automatically."},"pinned":{"type":"boolean","description":"Whether the column is pinned to the left of the table. Defaults to false."}}},"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"}}},"DashboardAccessResponse":{"type":"object","properties":{"dashboardId":{"type":"string","description":"Dashboard ID"},"mode":{"type":"string","enum":["everyone","restricted","inherit"],"description":"everyone: all members have accessLevel, plus any listed principals. restricted: only listed principals, the creator and admins. inherit: the dashboard has no access of its own and uses its folder access."},"accessLevel":{"type":["string","null"],"enum":["MANAGE","EDIT","VIEW",null],"description":"Access level for every member when mode is everyone"},"groupAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW","NONE"],"description":"MANAGE can edit and change access, EDIT can edit, VIEW can view. NONE explicitly denies this principal, overriding group or everyone access."}},"required":["id","accessLevel"]},"description":"Organization groups and their access level"},"memberAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW","NONE"],"description":"MANAGE can edit and change access, EDIT can edit, VIEW can view. NONE explicitly denies this principal, overriding group or everyone access."}},"required":["id","accessLevel"]},"description":"Organization members and their access level"}},"required":["dashboardId","mode","accessLevel","groupAccess","memberAccess"]},"UpdateDashboardAccessInput":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["everyone"]},"accessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW"],"default":"VIEW","description":"Access level for every member of the organization"},"groupAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW","NONE"],"default":"VIEW","description":"MANAGE can edit and change access, EDIT can edit, VIEW can view. NONE explicitly denies this principal, overriding group or everyone access."}},"required":["id"]},"maxItems":500,"description":"Organization groups and their access level. Required: send [] for none."},"memberAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW","NONE"],"default":"VIEW","description":"MANAGE can edit and change access, EDIT can edit, VIEW can view. NONE explicitly denies this principal, overriding group or everyone access."}},"required":["id"]},"maxItems":500,"description":"Organization members and their access level. Required: send [] for none."}},"required":["mode","groupAccess","memberAccess"]},{"type":"object","properties":{"mode":{"type":"string","enum":["restricted"]},"groupAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW","NONE"],"default":"VIEW","description":"MANAGE can edit and change access, EDIT can edit, VIEW can view. NONE explicitly denies this principal, overriding group or everyone access."}},"required":["id"]},"maxItems":500,"description":"Organization groups and their access level. Required: send [] for none."},"memberAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW","NONE"],"default":"VIEW","description":"MANAGE can edit and change access, EDIT can edit, VIEW can view. NONE explicitly denies this principal, overriding group or everyone access."}},"required":["id"]},"maxItems":500,"description":"Organization members and their access level. Required: send [] for none."}},"required":["mode","groupAccess","memberAccess"]},{"type":"object","properties":{"mode":{"type":"string","enum":["inherit"]}},"required":["mode"]}]},"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"},"sourceQueries":{"type":"array","items":{"type":"object","properties":{"alias":{"type":"string","description":"Source alias used by the DuckDB join query"},"sqlQuery":{"type":"string","description":"SQL query executed against this data source"},"databaseConnectionId":{"type":["string","null"],"description":"Data source ID for this query. Null if the data source was deleted."},"position":{"type":"integer","description":"Source query order"}},"required":["alias","sqlQuery","databaseConnectionId","position"]},"description":"Source queries used by a multi-source chart. Empty for single-source charts."},"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","sourceQueries","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"]},{"type":"string","enum":["VIEWER"]}],"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"]},{"type":"string","enum":["VIEWER"]}],"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"]},{"type":"string","enum":["VIEWER"]}],"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,"maxLength":500,"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"},"numericalFormat":{"$ref":"#/components/schemas/NumericalFormat"},"currencyCode":{"type":["string","null"],"description":"ISO 4217 currency code (for example USD or EUR) used when numericalFormat is CURRENCY. Null uses USD."},"showFullNumbers":{"type":"boolean","description":"Show full numbers (1,234,567) instead of abbreviated ones (1.2M)."},"metricLabel":{"type":["string","null"],"description":"NUMBER charts: label shown with the value. Null uses the chart name."},"timeSeriesMetricType":{"$ref":"#/components/schemas/TimeSeriesMetricType"},"tableMetricType":{"$ref":"#/components/schemas/TableMetricType"},"showLegend":{"type":"boolean","description":"Show the series legend (LINE, VERTICAL_BAR, HORIZONTAL_BAR, PIE, FUNNEL and SCATTER charts)."},"goalLineValue":{"type":["number","null"],"description":"Value of the target (goal) line on LINE, VERTICAL_BAR and SCATTER charts. Null hides it."},"yAxisMinimum":{"type":["number","null"],"description":"Lower bound of the y-axis. Null picks it from the data."},"yAxisMaximum":{"type":["number","null"],"description":"Upper bound of the y-axis. Null picks it from the data."},"xAxisMinimum":{"type":["number","null"],"description":"SCATTER charts: lower bound of the x-axis. Null picks it from the data."},"xAxisMaximum":{"type":["number","null"],"description":"SCATTER charts: upper bound of the x-axis. Null picks it from the data."},"barMode":{"$ref":"#/components/schemas/BarMode"},"colorByCategory":{"type":"boolean","description":"Give each bar its own color by category on a single-series HORIZONTAL_BAR, categorical VERTICAL_BAR or FUNNEL chart. segmentColors are then keyed by category (xAxisProperty) value. Ignored while the chart has a breakdown."},"seriesColor":{"anyOf":[{"$ref":"#/components/schemas/ChartColor"},{"type":"null"}],"description":"Color of the series on a chart without a breakdown (LINE, VERTICAL_BAR, HORIZONTAL_BAR, FUNNEL, SCATTER). Null picks it automatically."},"segmentColors":{"type":["object","null"],"additionalProperties":{"anyOf":[{"$ref":"#/components/schemas/ChartColor"},{"type":"null"}]},"description":"Colors of segments, keyed by segment value: breakdown values on LINE, VERTICAL_BAR, HORIZONTAL_BAR, FUNNEL and SCATTER charts, slices on PIE charts, nodes on SANKEY charts, or categories with colorByCategory. Segments left out are colored automatically. Merged by key: null for a segment resets it to automatic; null for the whole field resets every segment."},"imageProperty":{"type":["string","null"],"description":"IMAGE charts: result column holding the image URL."},"imageFit":{"$ref":"#/components/schemas/ImageFit"},"imageGrowToFit":{"type":"boolean","description":"IMAGE charts: grow the image to fill the card."},"textProperty":{"type":["string","null"],"description":"TEXT charts: result column holding the text to show."},"mapVariant":{"$ref":"#/components/schemas/MapVariant"},"tableColumns":{"type":["object","null"],"additionalProperties":{"anyOf":[{"$ref":"#/components/schemas/ChartTableColumnInput"},{"type":"null"}]},"description":"TABLE charts: column widths and pins, keyed by result column name. Columns left out use the defaults. Merged by column: a column given replaces that column's settings, null resets it; null for the whole field resets every column."}}},"ChartImageIneligibleErrorResponse":{"type":"object","properties":{"error":{"allOf":[{"$ref":"#/components/schemas/ApiError"},{"type":"object","properties":{"chartType":{"type":["string","null"],"description":"Type of the chart that cannot be rendered"}},"required":["chartType"]}]}},"required":["error"]},"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"]},"ChatAccessResponse":{"type":"object","properties":{"chatId":{"type":"string","description":"Chat ID"},"mode":{"type":"string","enum":["everyone","restricted"],"description":"everyone: all members have accessLevel, plus any listed principals. restricted: only listed principals, the creator and admins."},"accessLevel":{"type":["string","null"],"enum":["MANAGE","EDIT","VIEW",null],"description":"Access level for every member when mode is everyone"},"groupAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW","NONE"],"description":"MANAGE can edit and change access, EDIT can edit, VIEW can view. NONE explicitly denies this principal, overriding group or everyone access."}},"required":["id","accessLevel"]},"description":"Organization groups and their access level"},"memberAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW","NONE"],"description":"MANAGE can edit and change access, EDIT can edit, VIEW can view. NONE explicitly denies this principal, overriding group or everyone access."}},"required":["id","accessLevel"]},"description":"Organization members and their access level"}},"required":["chatId","mode","accessLevel","groupAccess","memberAccess"]},"UpdateChatAccessInput":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["everyone"]},"accessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW"],"default":"VIEW","description":"Access level for every member of the organization"},"groupAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW","NONE"],"default":"VIEW","description":"MANAGE can edit and change access, EDIT can edit, VIEW can view. NONE explicitly denies this principal, overriding group or everyone access."}},"required":["id"]},"maxItems":500,"description":"Organization groups and their access level. Required: send [] for none."},"memberAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW","NONE"],"default":"VIEW","description":"MANAGE can edit and change access, EDIT can edit, VIEW can view. NONE explicitly denies this principal, overriding group or everyone access."}},"required":["id"]},"maxItems":500,"description":"Organization members and their access level. Required: send [] for none."}},"required":["mode","groupAccess","memberAccess"]},{"type":"object","properties":{"mode":{"type":"string","enum":["restricted"]},"groupAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW","NONE"],"default":"VIEW","description":"MANAGE can edit and change access, EDIT can edit, VIEW can view. NONE explicitly denies this principal, overriding group or everyone access."}},"required":["id"]},"maxItems":500,"description":"Organization groups and their access level. Required: send [] for none."},"memberAccess":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Organization group or member ID"},"accessLevel":{"type":"string","enum":["MANAGE","EDIT","VIEW","NONE"],"default":"VIEW","description":"MANAGE can edit and change access, EDIT can edit, VIEW can view. NONE explicitly denies this principal, overriding group or everyone access."}},"required":["id"]},"maxItems":500,"description":"Organization members and their access level. Required: send [] for none."}},"required":["mode","groupAccess","memberAccess"]}]}},"parameters":{}},"paths":{"/api/public/billing-accounts":{"get":{"summary":"List billing accounts","description":"Lists billing accounts managed by the authenticated user (accounts whose owner organization the user administers). Billing accounts are created by Basedash — contact support to set one up.","tags":["Billing accounts"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Billing accounts retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicBillingAccount"}}},"required":["data"]}}}},"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"}}}}}}},"/api/public/billing-accounts/{billingAccountId}":{"get":{"summary":"Get a billing account","description":"Gets a billing account. Requires admin access to the account's owner organization.","tags":["Billing accounts"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Billing account ID"},"required":true,"description":"Billing account ID","name":"billingAccountId","in":"path"}],"responses":{"200":{"description":"Billing account retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PublicBillingAccount"}},"required":["data"]}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Billing account 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/billing-accounts/{billingAccountId}/organizations":{"get":{"summary":"List attached organizations","description":"Lists organizations attached to the billing account. Requires admin access to the account's owner organization.","tags":["Billing accounts"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Billing account ID"},"required":true,"description":"Billing account ID","name":"billingAccountId","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":"Attached organizations retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicBillingAccountOrganization"}},"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 - Billing account 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":"Attach an organization","description":"Attaches an existing organization to the billing account so it is billed through the account. Requires admin access to both the organization and the account's owner organization. The organization becomes a paid (GROWTH) organization with no trial limitations.","tags":["Billing accounts"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Billing account ID"},"required":true,"description":"Billing account ID","name":"billingAccountId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"organizationId":{"type":"string","description":"Organization to attach. You must be an admin of both this organization and the billing account owner organization."}},"required":["organizationId"]}}}},"responses":{"201":{"description":"Organization attached successfully","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"},"billingAccountId":{"type":"string","description":"Billing account ID"},"attached":{"type":"boolean","description":"True when the organization was attached by this request. False when it was already attached."}},"required":["id","name","billingAccountId","attached"]}},"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 - Billing account or organization not found, or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict - Organization is attached to another billing account or has its own subscription","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/billing-accounts/{billingAccountId}/organizations/{orgId}":{"delete":{"summary":"Detach an organization","description":"Detaches an organization from the billing account. The organization reverts to the FREE plan. Requires admin access to either the account's owner organization or the organization being detached.","tags":["Billing accounts"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Billing account ID"},"required":true,"description":"Billing account ID","name":"billingAccountId","in":"path"},{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"}],"responses":{"200":{"description":"Organization detached successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PublicBillingAccountOrganizationDetached"}},"required":["data"]}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Billing account or organization not found, not attached, 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/billing-accounts/{billingAccountId}/ai-usage":{"get":{"summary":"Get pooled AI usage","description":"Gets pooled billable AI usage for the billing account's current billing period, broken down by attached organization. Requires admin access to the account's owner organization.","tags":["Billing accounts"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Billing account ID"},"required":true,"description":"Billing account ID","name":"billingAccountId","in":"path"}],"responses":{"200":{"description":"AI usage retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicBillingAccountAiUsageResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Billing account 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":{"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"},"billingAccountId":{"type":["string","null"],"description":"Billing account this organization is billed through, or null when the organization manages its own billing."},"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."},"modelsEnabled":{"type":"boolean","description":"Whether Models is shown in the product and creating or editing models is allowed."},"automationNotificationsVisible":{"type":"boolean","description":"Whether the Slack and email notifications section is shown on the automation page. Does not affect existing notification delivery or the automations API."},"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. For an organization attached to a billing account, this controls access beyond the account's pooled included credits for this tenant; the billing account setting still applies to the whole account."},"aiUsageOverageLimitCents":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":2147483647,"description":"Maximum AI usage overage for the organization in cents. For an organization attached to a billing account, this is an absolute cap on that organization’s usage during the account billing period, not a share of the pooled credits. The billing account cap also applies. Null means no tenant 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","billingAccountId","isBillable","insightsEnabled","modelsEnabled","automationNotificationsVisible","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."},"billingAccountId":{"type":"string","description":"Billing account to attach the new organization to. Requires admin access to the billing account owner organization. The organization is billed through the account and treated as a paid (GROWTH) organization with no trial limitations."},"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."},"modelsEnabled":{"type":"boolean","description":"Show Models in the product and allow creating or editing models. Defaults to true."},"automationNotificationsVisible":{"type":"boolean","description":"When true, the Slack and email notifications section is shown on the automation page. When false, that section is hidden. Does not affect existing notification delivery or the automations API. 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. For an organization attached to a billing account, this controls access beyond the account's pooled included credits for this tenant; the billing account setting still applies to the whole account. Defaults to true."},"aiUsageOverageLimitCents":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":2147483647,"description":"Maximum AI usage overage for the organization in cents. For an organization attached to a billing account, this is an absolute cap on that organization’s usage during the account billing period, not a share of the pooled credits. The billing account cap also applies. Null means no tenant 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"},"billingAccountId":{"type":["string","null"],"description":"Billing account this organization is billed through, or null when the organization manages its own billing."},"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."},"modelsEnabled":{"type":"boolean","description":"Whether Models is shown in the product and creating or editing models is allowed."},"automationNotificationsVisible":{"type":"boolean","description":"Whether the Slack and email notifications section is shown on the automation page. Does not affect existing notification delivery or the automations API."},"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. For an organization attached to a billing account, this controls access beyond the account's pooled included credits for this tenant; the billing account setting still applies to the whole account."},"aiUsageOverageLimitCents":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":2147483647,"description":"Maximum AI usage overage for the organization in cents. For an organization attached to a billing account, this is an absolute cap on that organization’s usage during the account billing period, not a share of the pooled credits. The billing account cap also applies. Null means no tenant 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","billingAccountId","isBillable","insightsEnabled","modelsEnabled","automationNotificationsVisible","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 - Billing account not found or no admin access","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"},"sslVerifyServerCertificate":{"type":["boolean","null"],"description":"Whether the server's TLS certificate is verified when SSL is on. Null for data sources created before this setting, which don't verify"},"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","sslVerifyServerCertificate","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"},"sslVerifyServerCertificate":{"type":"boolean","description":"Verify the server's TLS certificate when SSL is on"},"sslCaCertificate":{"type":["string","null"],"maxLength":65536,"description":"PEM CA certificate to trust for the server certificate"},"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"},"sslVerifyServerCertificate":{"type":["boolean","null"],"description":"Whether the server's TLS certificate is verified when SSL is on. Null for data sources created before this setting, which don't verify"},"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","sslVerifyServerCertificate","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"},"sslVerifyServerCertificate":{"type":["boolean","null"],"description":"Whether the server's TLS certificate is verified when SSL is on. Null for data sources created before this setting, which don't verify"},"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","sslVerifyServerCertificate","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"},"sslVerifyServerCertificate":{"type":["boolean","null"],"description":"Whether the server's TLS certificate is verified when SSL is on. Null for data sources created before this setting, which don't verify"},"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","sslVerifyServerCertificate","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"},"sslVerifyServerCertificate":{"type":"boolean","description":"Verify the server's TLS certificate when SSL is on"},"sslCaCertificate":{"type":["string","null"],"maxLength":65536,"description":"PEM CA certificate to trust for the server certificate"},"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"},"sslVerifyServerCertificate":{"type":["boolean","null"],"description":"Whether the server's TLS certificate is verified when SSL is on. Null for data sources created before this setting, which don't verify"},"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","sslVerifyServerCertificate","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"},"sslVerifyServerCertificate":{"type":"boolean","description":"Verify the server's TLS certificate when SSL is on"},"sslCaCertificate":{"type":["string","null"],"maxLength":65536,"description":"PEM CA certificate to trust for the server certificate"},"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: who can query it, and the schema, table, and column rules on it. The response can be sent back to the update endpoint unchanged. 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":"Updates the access policy for a data source. Requires admin access to the organization.\n\nConnection-level access: when mode is sent, it replaces who can query the data source. Use mode \"everyone\" to allow all organization members to view or edit it, or mode \"restricted\" with groupAccess/memberAccess to limit access; an omitted groupAccess or memberAccess means none. Legacy groupIds/memberIds grant view access. Omit mode to leave connection-level access unchanged; the body must then contain only objects, and sending accessLevel, groupAccess, memberAccess, groupIds, or memberIds without mode returns 400. A body with neither mode nor objects also returns 400.\n\nSchema, table, and column rules are optional. Omit objects to leave them unchanged. When objects is sent, even as an empty array, it replaces every object rule on the data source, including rules configured in the app. Objects are identified by their synced schema, table, and column names. Each object must set at least one of everyoneAccessLevel, groupAccess, or memberAccess, and unknown fields return 400; to remove an object's rules, leave the object out.\n\nObject rules are evaluated from schema to table to column; an object without a matching rule inherits from its parent. At each object a member rule beats group rules, a group with FULL beats groups with NO_ACCESS, and group rules beat the everyone rule. Rules apply to every role, including admins. To restrict tables to a group, set everyoneAccessLevel to NO_ACCESS and give the group FULL on the same object. Prefer schema-level rules for allow-lists: new tables in the schema inherit NO_ACCESS.\n\nNew object rules must reference groups, active members, and objects that exist in the synced schema; otherwise nothing is changed, including the connection-level policy, and the request returns 404. Existing rules are kept as-is even if their object has since been dropped. Sending the same object rules again is a no-op for them: unchanged rules are not rewritten and open clients are not notified.","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, validation error, connection-level fields without mode, a body with neither mode nor objects, a duplicated object, an object with no rules or unknown fields, or conflicting levels for one principal on an object","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, member, or schema object 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}/access":{"get":{"summary":"Get automation access","description":"Retrieves who can view, edit and manage an automation. Organization admins and the automation creator always have full access and are not listed. 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 access retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AutomationAccessResponse"}},"required":["data"]}}}},"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"}}}}}},"put":{"summary":"Update automation access","description":"Replaces the access policy. Send the complete policy: groups and members not listed lose their access. Use mode \"everyone\" to give every organization member accessLevel (plus any listed groupAccess/memberAccess), or mode \"restricted\" so only the listed groups and members, the creator and organization admins can access it; restricting removes the default everyone access. groupAccess and memberAccess are required (send [] for none), and listing one principal twice with different levels is rejected. The GET response can be sent back unchanged, and sending the current policy again changes nothing. View-only members are capped at VIEW whatever their grant. The automation creator cannot be listed in memberAccess. 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/UpdateAutomationAccessInput"}}}},"responses":{"200":{"description":"Automation access updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AutomationAccessResponse"}},"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 - Automation, 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/{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 answer as markdown and its charts. Markdown image URLs and chart imageUrl values require the same Bearer authentication as this request. 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}/models":{"get":{"summary":"List models","description":"Lists models for an organization. Requires admin access to the organization. Results are paginated and ordered by creation date (newest first).","tags":["Models"],"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 models by"},"required":false,"description":"Optional data source ID to filter models by","name":"databaseConnectionId","in":"query"}],"responses":{"200":{"description":"Models retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ModelResponse"}},"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 model","description":"Creates a new model within an organization. Requires admin access to the organization.","tags":["Models"],"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/CreateModelInput"}}}},"responses":{"201":{"description":"Model created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ModelResponse"}},"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 - Another model in the organization already uses this reference name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelReferenceNameConflictErrorResponse"}}}},"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}/models/{id}":{"get":{"summary":"Get a model","description":"Retrieves a model by ID. Requires admin access to the organization.","tags":["Models"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Model ID"},"required":true,"description":"Model ID","name":"id","in":"path"}],"responses":{"200":{"description":"Model retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ModelResponse"}},"required":["data"]}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Model not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict - Model changed while it was being deleted","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 model","description":"Updates an existing model. Requires admin access to the organization.","tags":["Models"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Model ID"},"required":true,"description":"Model ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateModelInput"}}}},"responses":{"200":{"description":"Model updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ModelResponse"}},"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 - Model not found or no admin access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict - Another model in the organization already uses this reference name, or the model changed while it was being edited","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ModelReferenceNameConflictErrorResponse"},{"$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 model","description":"Archives a model by ID. Requires admin access to the organization.","tags":["Models"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"orgId","in":"path"},{"schema":{"type":"string","description":"Model ID"},"required":true,"description":"Model ID","name":"id","in":"path"}],"responses":{"204":{"description":"Model deleted successfully"},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Model 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","group.login_token_synced","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","catalog.description_updated","api_key.created","api_key.renamed","api_key.revoked","scim_token.created","scim_token.deleted","organization.created","organization.updated","organization.jwt_secret_viewed","organization.jwt_secret_copied","organization.billing_account_attached","organization.billing_account_detached","domain.created","domain.updated","domain.deleted","dashboard.created","dashboard.deleted","dashboard.archived","dashboard.restored","dashboard.public_sharing_enabled","dashboard.public_sharing_disabled","dashboard.public_sharing_link_reset","dashboard.verified","dashboard.unverified","automation.created","automation.deleted","automation.archived","automation.restored","automation.updated","chart.query_saved","chart.settings_saved","subscription.created","subscription.updated","subscription.archived","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","query.staff_explained","data.exported","ai.tool_executed","ai_context.global_updated","ai_skill.created","ai_skill.updated","ai_skill.deleted","model.created","model.updated","model.archived","model.restored","org_permission.updated","org_permission.reset"],"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}/dashboards/{id}/access":{"get":{"summary":"Get dashboard access","description":"Retrieves who can view, edit and manage a dashboard. Organization admins and the dashboard creator always have full access and are not listed. 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 access retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DashboardAccessResponse"}},"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"}}}}}},"put":{"summary":"Update dashboard access","description":"Replaces the access policy. Send the complete policy: groups and members not listed lose their access. Use mode \"everyone\" to give every organization member accessLevel (plus any listed groupAccess/memberAccess), or mode \"restricted\" so only the listed groups and members, the creator and organization admins can access it; restricting removes the default everyone access. groupAccess and memberAccess are required (send [] for none), and listing one principal twice with different levels is rejected. The GET response can be sent back unchanged, and sending the current policy again changes nothing. View-only members are capped at VIEW whatever their grant. For a dashboard in a folder, mode \"inherit\" removes the dashboard's own access so it uses its folder's access. 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/UpdateDashboardAccessInput"}}}},"responses":{"200":{"description":"Dashboard access updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DashboardAccessResponse"}},"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, 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}/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"}}}},"503":{"description":"Service unavailable - The insight chart data source was temporarily unreachable","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. IMAGE charts and dashboard header and text blocks (DASHBOARD_HEADER, DASHBOARD_TEXT) are never rendered as images; requesting one returns 422.","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"}}}},"422":{"description":"Unprocessable - The chart type is never rendered as an image (IMAGE, DASHBOARD_HEADER, DASHBOARD_TEXT). The error has title ChartTypeNotRenderable and includes chartType.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChartImageIneligibleErrorResponse"}}}},"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. Group names are unique within an organization, compared case-insensitively; a duplicate name returns 409. 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. Unique within the organization, compared case-insensitively."},"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"}}}},"409":{"description":"Conflict - Another group in the organization has the same name (compared case-insensitively)","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. Renaming a group to a name another group in the organization already uses (compared case-insensitively) returns 409. 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. Unique within the organization, compared case-insensitively."},"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"}}}},"409":{"description":"Conflict - Another group in the organization has the same name (compared case-insensitively)","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 and body within 30 days returns the original result instead of creating a duplicate. Reusing a key with a different body returns HTTP 409; repeating one whose chat was since deleted returns HTTP 404."},"required":false,"description":"A unique key (up to 255 characters) that makes retries safe: repeating a request with the same key and body within 30 days returns the original result instead of creating a duplicate. Reusing a key with a different body returns HTTP 409; repeating one whose chat was since deleted returns HTTP 404.","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"}}}},"409":{"description":"Conflict - The Idempotency-Key was already used with a different message","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 and body within 30 days returns the original result instead of creating a duplicate. Reusing a key with a different body returns HTTP 409; repeating one whose chat was since deleted returns HTTP 404."},"required":false,"description":"A unique key (up to 255 characters) that makes retries safe: repeating a request with the same key and body within 30 days returns the original result instead of creating a duplicate. Reusing a key with a different body returns HTTP 409; repeating one whose chat was since deleted returns HTTP 404.","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), or the Idempotency-Key was already used with a different message.","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/{orgId}/chats/{chatId}/access":{"get":{"summary":"Get chat access","description":"Retrieves who can view, edit and manage an API chat. Organization admins and the chat creator always have full access and are not listed. Requires view access to the chat.","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 access retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChatAccessResponse"}},"required":["data"]}}}},"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 access to it","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 chat access","description":"Replaces the access policy. Send the complete policy: groups and members not listed lose their access. Use mode \"everyone\" to give every organization member accessLevel (plus any listed groupAccess/memberAccess), or mode \"restricted\" so only the listed groups and members, the creator and organization admins can access it; restricting removes the default everyone access. groupAccess and memberAccess are required (send [] for none), and listing one principal twice with different levels is rejected. The GET response can be sent back unchanged, and sending the current policy again changes nothing. View-only members are capped at VIEW whatever their grant. The chat creator cannot be listed in memberAccess. Requires manage access to the chat.","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"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateChatAccessInput"}}}},"responses":{"200":{"description":"Chat access updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChatAccessResponse"}},"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 - View-only member, or no manage access to the chat","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found - Chat, group, or member not found or no access to the chat","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"},"billingAccountId":{"type":["string","null"],"description":"Billing account this organization is billed through, or null when the organization manages its own billing."},"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."},"modelsEnabled":{"type":"boolean","description":"Whether Models is shown in the product and creating or editing models is allowed."},"automationNotificationsVisible":{"type":"boolean","description":"Whether the Slack and email notifications section is shown on the automation page. Does not affect existing notification delivery or the automations API."},"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. For an organization attached to a billing account, this controls access beyond the account's pooled included credits for this tenant; the billing account setting still applies to the whole account."},"aiUsageOverageLimitCents":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":2147483647,"description":"Maximum AI usage overage for the organization in cents. For an organization attached to a billing account, this is an absolute cap on that organization’s usage during the account billing period, not a share of the pooled credits. The billing account cap also applies. Null means no tenant 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","billingAccountId","isBillable","insightsEnabled","modelsEnabled","automationNotificationsVisible","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)"},"billingAccountId":{"type":"string","description":"Billing account to attach the new organization to. Requires admin access to the billing account owner organization. The organization is billed through the account and treated as a paid (GROWTH) organization with no trial limitations."},"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."},"modelsEnabled":{"type":"boolean","description":"Show Models in the product and allow creating or editing models. Defaults to true."},"automationNotificationsVisible":{"type":"boolean","description":"When true, the Slack and email notifications section is shown on the automation page. When false, that section is hidden. Does not affect existing notification delivery or the automations API. 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. For an organization attached to a billing account, this controls access beyond the account's pooled included credits for this tenant; the billing account setting still applies to the whole account. Defaults to true."},"aiUsageOverageLimitCents":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":2147483647,"description":"Maximum AI usage overage for the organization in cents. For an organization attached to a billing account, this is an absolute cap on that organization’s usage during the account billing period, not a share of the pooled credits. The billing account cap also applies. Null means no tenant 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"},"billingAccountId":{"type":["string","null"],"description":"Billing account this organization is billed through, or null when the organization manages its own billing."},"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."},"modelsEnabled":{"type":"boolean","description":"Whether Models is shown in the product and creating or editing models is allowed."},"automationNotificationsVisible":{"type":"boolean","description":"Whether the Slack and email notifications section is shown on the automation page. Does not affect existing notification delivery or the automations API."},"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. For an organization attached to a billing account, this controls access beyond the account's pooled included credits for this tenant; the billing account setting still applies to the whole account."},"aiUsageOverageLimitCents":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":2147483647,"description":"Maximum AI usage overage for the organization in cents. For an organization attached to a billing account, this is an absolute cap on that organization’s usage during the account billing period, not a share of the pooled credits. The billing account cap also applies. Null means no tenant 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","billingAccountId","isBillable","insightsEnabled","modelsEnabled","automationNotificationsVisible","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"}}}}}},"delete":{"summary":"Delete an organization","description":"Permanently deletes an organization and all organization-owned data. Deletion runs asynchronously and requires admin access, exact-name confirmation, and a canceled subscription. Repeating the request while deletion is pending is safe.","tags":["Organizations"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Organization ID"},"required":true,"description":"Organization ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"confirmationText":{"type":"string","description":"Exact organization name, required to confirm permanent deletion"}},"required":["confirmationText"]}}}},"responses":{"202":{"description":"Organization deletion accepted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Organization deletion request ID"},"organizationId":{"type":"string","description":"Organization ID"},"status":{"type":"string","enum":["PENDING"]}},"required":["id","organizationId","status"]}},"required":["data"]}}}},"400":{"description":"Bad request - Invalid body or confirmation text","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 - Active subscription must be canceled 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"}}}},"503":{"description":"Service unavailable - Subscription status cannot be verified","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 restricted to that organization\n5. The user is redirected to your organization's dashboard inside the iframe\n\n## Existing Basedash accounts\n\nIf the JWT `email` belongs to a verified Basedash account that is already an\nactive member of your organization, including an admin, the embed signs in as\nthat account, so the person keeps their role, groups and work. The `role` and\n`groups` claims are not applied to that account; manage its access in\nBasedash. Any other email gets a separate embed user that the claims manage.\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  \"groups\": [\"Billing\", \"Program A\"],\n  \"exp\": 1234567890,\n  \"iat\": 1234567800\n}\n```\n\nThe optional `role` claim accepts `ADMIN`, `MEMBER`, or `VIEWER`.\nWhen supplied, it is the source of truth for the active membership on every\nlogin. Omit it to preserve an active membership's role; new or reactivated\nmemberships without a role claim default to `MEMBER`. `VIEWER` is read-only.\n\n## Groups\n\nThe optional `groups` claim lists the names of existing Basedash groups the\nuser belongs to. Use it to scope dashboards, chats, data sources and row-level\nsecurity to groups you manage from your application. When supplied, it is\napplied on every login:\n\n| Situation | Result |\n| --- | --- |\n| A name matches a group the user isn't in | The user is added to the group |\n| The claim no longer names a group this claim added the user to | The user is removed from that group |\n| The user was added to a group in Basedash, through the API or by SCIM | Never removed by the claim |\n| `groups` is `[]` | Removes every membership the claim added |\n| `groups` is omitted | Group memberships are left unchanged |\n\n- Names match case-insensitively, ignoring leading and trailing spaces.\n- Groups are never created. Create them first with `POST /organizations/{orgId}/groups`,\n  and give them access before users log in.\n- A name that matches no group, matches more than one group, or names a\n  SCIM-managed group is skipped. So is the whole claim when it lists more than\n  100 distinct names. The login still succeeds. Each login that changes\n  memberships or skips a name records a `group.login_token_synced` audit event\n  listing the groups added and removed and every skipped name with its reason\n  (`unknown`, `ambiguous`, `scim_managed` or `invalid_name`).\n- Audit logs require the Enterprise plan. On Enterprise, find these events\n  under **Settings → Audit logs**, or query them with an administrator API key:\n  `GET /organizations/{orgId}/audit-logs?action=group.login_token_synced`.\n  On other plans, compare the names you send with\n  `GET /organizations/{orgId}/groups`.\n- If an admin removes a membership the claim added, the next login adds it back.\n  To revoke access, remove the group from the claim. To revoke it immediately\n  as well, also remove the membership in Basedash or through the API.\n- On data sources with row-level security, group names are passed to your\n  policies, so adding a group can widen the data a user sees.\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    groups: ['Billing', 'Program A'],\n  },\n  process.env.BASEDASH_EMBED_JWT_SECRET,\n  { expiresIn: '10m' }\n);\n```\n\n## Customizing the embed\n\nAppend any of these query parameters to the iframe URL. They are forwarded through the redirect.\n\n**Appearance and features** apply for the rest of the iframe session, so later in-app navigation keeps them:\n\n| Parameter | Values | Effect |\n| --- | --- | --- |\n| `theme` | `light`, `dark`, `auto` | Override the theme |\n| `hide_org_name` | `true`, `false` | Hide the organization name in the sidebar |\n| `hide_chat` | `true`, `false` | Hide the Chat page and chat panel |\n| `hide_dashboards` | `true`, `false` | Hide dashboards |\n| `hide_insights` | `true`, `false` | Hide insights |\n| `hide_automations` | `true`, `false` | Hide automations |\n| `hide_models` | `true`, `false` | Hide models |\n| `hide_suggested_prompts` | `true`, `false` | Hide suggested prompts in the chat input |\n| `hide_sidebar` | `true`, `false` | Don't render the left sidebar at all, with no way to reopen it |\n\nAt least one of chat, dashboards, insights, automations, or models stays visible; Basedash falls back to chat if all are hidden.\n\nWith `hide_sidebar=true` your application owns navigation. Breadcrumbs and search remain, but lists that only live in the sidebar (all dashboards and folders, chat history) are not shown, so pair it with a single visible feature and, for dashboards, an initial page. Hiding the sidebar is presentation only, not access control: use Basedash permissions to restrict what a user can open.\n\n**Initial page** parameters choose the page the embed opens on. Set at most one:\n\n| Parameter | Opens |\n| --- | --- |\n| `dashboard_id` | A dashboard (combine with `tab` to open a dashboard tab) |\n| `automation_id` | An automation |\n| `insight_id` | An insight |\n| `model_id` | A model |\n| `chat_id` | A chat |\n\nThe initial page is only where the embed opens; users can still navigate elsewhere. It is ignored when its feature is hidden or disabled, and the embed opens on the default page instead. An unknown or inaccessible ID shows a not-found page.\n\n```html\n<iframe\n  src=\"https://charts.basedash.com/api/sso/jwt?jwt=YOUR_JWT_TOKEN&hide_chat=true&hide_insights=true&hide_automations=true&hide_models=true&hide_sidebar=true&dashboard_id=DASHBOARD_ID\"\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- **Organization-scoped access** - JWT sessions cannot access the user's other Basedash organizations\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"},{"schema":{"type":"string","enum":["light","dark","auto"],"description":"Override the theme"},"required":false,"description":"Override the theme","name":"theme","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Hide the organization name in the sidebar. Persists for the iframe session."},"required":false,"description":"Hide the organization name in the sidebar. Persists for the iframe session.","name":"hide_org_name","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Hide the Chat page and chat panel. Persists for the iframe session."},"required":false,"description":"Hide the Chat page and chat panel. Persists for the iframe session.","name":"hide_chat","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Hide dashboards. Persists for the iframe session."},"required":false,"description":"Hide dashboards. Persists for the iframe session.","name":"hide_dashboards","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Hide insights. Persists for the iframe session."},"required":false,"description":"Hide insights. Persists for the iframe session.","name":"hide_insights","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Hide automations. Persists for the iframe session."},"required":false,"description":"Hide automations. Persists for the iframe session.","name":"hide_automations","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Hide models. Persists for the iframe session."},"required":false,"description":"Hide models. Persists for the iframe session.","name":"hide_models","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Hide suggested prompts in the chat input. Persists for the iframe session."},"required":false,"description":"Hide suggested prompts in the chat input. Persists for the iframe session.","name":"hide_suggested_prompts","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Do not render the left sidebar, with no way to reopen it. Persists for the iframe session."},"required":false,"description":"Do not render the left sidebar, with no way to reopen it. Persists for the iframe session.","name":"hide_sidebar","in":"query"},{"schema":{"type":"string","description":"Open the embed on this dashboard"},"required":false,"description":"Open the embed on this dashboard","name":"dashboard_id","in":"query"},{"schema":{"type":"string","description":"With dashboard_id, the dashboard tab to open"},"required":false,"description":"With dashboard_id, the dashboard tab to open","name":"tab","in":"query"},{"schema":{"type":"string","description":"Open the embed on this automation"},"required":false,"description":"Open the embed on this automation","name":"automation_id","in":"query"},{"schema":{"type":"string","description":"Open the embed on this insight"},"required":false,"description":"Open the embed on this insight","name":"insight_id","in":"query"},{"schema":{"type":"string","description":"Open the embed on this model"},"required":false,"description":"Open the embed on this model","name":"model_id","in":"query"},{"schema":{"type":"string","description":"Open the embed on this chat"},"required":false,"description":"Open the embed on this chat","name":"chat_id","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"}}}},"429":{"description":"Too many requests - per-IP rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"string","description":"Seconds to wait before retrying"},"required":true,"description":"Seconds to wait before retrying"}},"content":{"text/html":{"schema":{"type":"string","description":"HTML error page"}}}},"500":{"description":"Internal server error, including a failure to apply the groups claim","content":{"text/html":{"schema":{"type":"string","description":"HTML error page"}}}}}}}},"webhooks":{}}