# Basedash Documentation: API reference

## API reference

### Overview

- [Overview](https://basedash.com/docs/api-reference/overview.md): Programmatic access to Basedash features

### Endpoints

#### Billing accounts

- [List billing accounts](https://basedash.com/docs/api-reference/billing-accounts/list-billing-accounts.md): 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.
- [Get a billing account](https://basedash.com/docs/api-reference/billing-accounts/get-a-billing-account.md): Gets a billing account. Requires admin access to the account's owner organization.
- [List attached organizations](https://basedash.com/docs/api-reference/billing-accounts/list-attached-organizations.md): Lists organizations attached to the billing account. Requires admin access to the account's owner organization.
- [Attach an organization](https://basedash.com/docs/api-reference/billing-accounts/attach-an-organization.md): 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.
- [Detach an organization](https://basedash.com/docs/api-reference/billing-accounts/detach-an-organization.md): 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.
- [Get pooled AI usage](https://basedash.com/docs/api-reference/billing-accounts/get-pooled-ai-usage.md): 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.

#### Organizations

- [List organizations](https://basedash.com/docs/api-reference/organizations/list-organizations.md): Lists all organizations where the authenticated user is a member. Results are paginated and ordered by creation date (newest first).
- [Create an organization](https://basedash.com/docs/api-reference/organizations/create-an-organization.md): Creates a new organization. The authenticated user becomes an admin.
- [List audit log events](https://basedash.com/docs/api-reference/organizations/list-audit-log-events.md): Returns immutable organization audit events in reverse chronological order for SIEM ingestion. Requires an Enterprise organization and an administrator API key.
- [Get AI usage](https://basedash.com/docs/api-reference/organizations/get-ai-usage.md): Gets total billable AI usage and member usage for the current billing period. Requires admin access to the organization.
- [Get an organization](https://basedash.com/docs/api-reference/organizations/get-an-organization.md): Retrieves an organization by ID. Requires membership in the organization.
- [Delete an organization](https://basedash.com/docs/api-reference/organizations/delete-an-organization.md): 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.
- [Update an organization](https://basedash.com/docs/api-reference/organizations/update-an-organization.md): Updates an existing organization. Requires admin access.
- [Upload organization icon](https://basedash.com/docs/api-reference/organizations/upload-organization-icon.md): Uploads an icon image for an organization. The image is stored and the organization is updated with the new icon URL. Requires admin access.

#### Embedding

- [Upload embedded user avatar](https://basedash.com/docs/api-reference/embedding/upload-embedded-user-avatar.md): 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.
- [JWT authentication](https://basedash.com/docs/api-reference/embedding/jwt-authentication.md): 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.

#### Data Sources

- [Get a data source](https://basedash.com/docs/api-reference/data-sources/get-a-data-source.md): Retrieves a data source by ID. Requires admin access to the organization. Returns extended connection information excluding sensitive fields like passwords and private keys.
- [Delete a data source](https://basedash.com/docs/api-reference/data-sources/delete-a-data-source.md): 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.
- [Update a data source](https://basedash.com/docs/api-reference/data-sources/update-a-data-source.md): Updates an existing data source connection settings. Requires admin access to the organization.
- [List data sources](https://basedash.com/docs/api-reference/data-sources/list-data-sources.md): Lists all data sources for an organization. Requires admin access to the organization. Results are paginated and ordered by creation date (newest first).
- [Create a data source](https://basedash.com/docs/api-reference/data-sources/create-a-data-source.md): Creates a new data source connection for an organization. Requires admin access to the organization. Currently only direct database connections are supported.
- [Verify data source credentials](https://basedash.com/docs/api-reference/data-sources/verify-data-source-credentials.md): Tests database connection credentials without creating a data source. Use this endpoint to validate credentials before creating or updating a data source.
- [Get data source access](https://basedash.com/docs/api-reference/data-sources/get-data-source-access.md): Retrieves the access policy for a data source. Requires admin access to the organization.
- [Update data source access](https://basedash.com/docs/api-reference/data-sources/update-data-source-access.md): Replaces the access policy for a data source. Use mode "everyone" to allow all organization members to view or edit it, or mode "restricted" with groupAccess/memberAccess to limit access. Legacy groupIds/memberIds grant view access. Requires admin access to the organization.

#### Automations

- [List automations](https://basedash.com/docs/api-reference/automations/list-automations.md): Lists automations for an organization. Requires admin access to the organization. Results are paginated and ordered by creation date (newest first).
- [Create an automation](https://basedash.com/docs/api-reference/automations/create-an-automation.md): Creates an automation for an organization. Requires admin access to the organization.
- [Get an automation](https://basedash.com/docs/api-reference/automations/get-an-automation.md): Retrieves an automation by ID. Requires admin access to the organization.
- [Archive an automation](https://basedash.com/docs/api-reference/automations/archive-an-automation.md): Archives an automation by ID. Requires admin access to the organization.
- [Update an automation](https://basedash.com/docs/api-reference/automations/update-an-automation.md): Updates an automation by ID. Requires admin access to the organization.
- [List automation runs](https://basedash.com/docs/api-reference/automations/list-automation-runs.md): Lists runs for an automation. Requires admin access to the organization. Results are paginated and ordered by creation date (newest first).
- [Start an automation run](https://basedash.com/docs/api-reference/automations/start-an-automation-run.md): Starts a manual run for a scheduled or manual automation. Requires admin access to the organization. Run generation happens asynchronously.
- [Get an automation run](https://basedash.com/docs/api-reference/automations/get-an-automation-run.md): 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.

#### Models

- [List models](https://basedash.com/docs/api-reference/models/list-models.md): Lists models for an organization. Requires admin access to the organization. Results are paginated and ordered by creation date (newest first).
- [Create a model](https://basedash.com/docs/api-reference/models/create-a-model.md): Creates a new model within an organization. Requires admin access to the organization.
- [List models](https://basedash.com/docs/api-reference/models/list-models-1.md): Lists models for an organization. Requires admin access to the organization. Results are paginated and ordered by creation date (newest first).
- [Create a model](https://basedash.com/docs/api-reference/models/create-a-model-1.md): Creates a new model within an organization. Requires admin access to the organization.
- [Get a model](https://basedash.com/docs/api-reference/models/get-a-model.md): Retrieves a model by ID. Requires admin access to the organization.
- [Delete a model](https://basedash.com/docs/api-reference/models/delete-a-model.md): Archives a model by ID. Requires admin access to the organization.
- [Update a model](https://basedash.com/docs/api-reference/models/update-a-model.md): Updates an existing model. Requires admin access to the organization.
- [Get a model](https://basedash.com/docs/api-reference/models/get-a-model-1.md): Retrieves a model by ID. Requires admin access to the organization.
- [Delete a model](https://basedash.com/docs/api-reference/models/delete-a-model-1.md): Archives a model by ID. Requires admin access to the organization.
- [Update a model](https://basedash.com/docs/api-reference/models/update-a-model-1.md): Updates an existing model. Requires admin access to the organization.

#### MCP servers

- [Get an MCP server](https://basedash.com/docs/api-reference/mcp-servers/get-an-mcp-server.md): Retrieves an MCP server by ID. Requires admin access to the organization. Returns server status and synced tools, excluding configured headers and OAuth tokens.
- [Delete an MCP server](https://basedash.com/docs/api-reference/mcp-servers/delete-an-mcp-server.md): Deletes an MCP server by ID. Requires admin access to the organization.
- [Update an MCP server](https://basedash.com/docs/api-reference/mcp-servers/update-an-mcp-server.md): Updates an MCP server display name, URL, static headers, or synced tool access modes. Requires admin access to the organization.
- [List MCP servers](https://basedash.com/docs/api-reference/mcp-servers/list-mcp-servers.md): Lists all MCP servers for an organization. Requires admin access to the organization. Results are paginated and ordered by creation date (newest first).
- [Create an MCP server](https://basedash.com/docs/api-reference/mcp-servers/create-an-mcp-server.md): 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.

#### Dashboards

- [List dashboards](https://basedash.com/docs/api-reference/dashboards/list-dashboards.md): 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).
- [Create a dashboard](https://basedash.com/docs/api-reference/dashboards/create-a-dashboard.md): Creates a new dashboard within an organization, including a default "Main" tab. Requires admin access to the organization.
- [List charts on a dashboard](https://basedash.com/docs/api-reference/dashboards/list-charts-on-a-dashboard.md): 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).
- [Create a dashboard tab](https://basedash.com/docs/api-reference/dashboards/create-a-dashboard-tab.md): Creates a new tab on a dashboard. Requires admin access to the organization.
- [Delete a dashboard tab](https://basedash.com/docs/api-reference/dashboards/delete-a-dashboard-tab.md): 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.
- [Update a dashboard tab](https://basedash.com/docs/api-reference/dashboards/update-a-dashboard-tab.md): Updates a dashboard tab (name and sort order). Requires admin access to the organization.
- [Get a dashboard](https://basedash.com/docs/api-reference/dashboards/get-a-dashboard.md): Retrieves a dashboard by ID, including its tabs. Requires admin access to the organization.
- [Delete a dashboard](https://basedash.com/docs/api-reference/dashboards/delete-a-dashboard.md): Archives a dashboard by ID, along with the charts on it. Requires admin access to the organization.
- [Update a dashboard](https://basedash.com/docs/api-reference/dashboards/update-a-dashboard.md): Updates dashboard metadata (name, description, icon, color, folder, width, and default date range settings). Requires admin access to the organization.

#### Charts

- [Create a chart](https://basedash.com/docs/api-reference/charts/create-a-chart.md): 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.
- [Get a chart](https://basedash.com/docs/api-reference/charts/get-a-chart.md): 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.
- [Delete a chart](https://basedash.com/docs/api-reference/charts/delete-a-chart.md): Archives a chart by ID and removes it from its dashboard. Requires admin access to the organization.
- [Update a chart](https://basedash.com/docs/api-reference/charts/update-a-chart.md): 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 organ…
- [Get a chart image](https://basedash.com/docs/api-reference/charts/get-a-chart-image.md): 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 ren…

#### Insights

- [List insights](https://basedash.com/docs/api-reference/insights/list-insights.md): Lists insight summaries for an organization. Requires admin access to the organization. Results are paginated and ordered by creation date (newest first).
- [Generate an insight](https://basedash.com/docs/api-reference/insights/generate-an-insight.md): Queues generation of a new insight for an organization. Requires admin access to the organization. Generation runs asynchronously.
- [Get an insight](https://basedash.com/docs/api-reference/insights/get-an-insight.md): 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.
- [Delete an insight](https://basedash.com/docs/api-reference/insights/delete-an-insight.md): Deletes an insight by ID. Requires admin access to the organization.

#### Members

- [List members](https://basedash.com/docs/api-reference/members/list-members.md): 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).
- [Invite a member](https://basedash.com/docs/api-reference/members/invite-a-member.md): 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.
- [Get a member](https://basedash.com/docs/api-reference/members/get-a-member.md): Retrieves a member by ID, including their user information. Requires admin access to the organization.
- [Deactivate a member](https://basedash.com/docs/api-reference/members/deactivate-a-member.md): Deactivates a member in the organization. Requires admin access to the organization. Cannot deactivate the last active admin.
- [Update a member](https://basedash.com/docs/api-reference/members/update-a-member.md): Updates a member role and supported user profile fields. Requires admin access to the organization. Cannot demote the last verified admin.

#### Groups

- [List groups](https://basedash.com/docs/api-reference/groups/list-groups.md): Lists all groups for an organization. Requires admin access to the organization. Results are paginated and ordered by creation date (newest first).
- [Create a group](https://basedash.com/docs/api-reference/groups/create-a-group.md): Creates a new group within an organization. Requires admin access to the organization.
- [Get a group](https://basedash.com/docs/api-reference/groups/get-a-group.md): Retrieves a group by ID. Requires admin access to the organization.
- [Delete a group](https://basedash.com/docs/api-reference/groups/delete-a-group.md): Deletes a group by ID. Requires admin access to the organization.
- [Update a group](https://basedash.com/docs/api-reference/groups/update-a-group.md): Updates an existing group. Requires admin access to the organization.
- [Add a member to a group](https://basedash.com/docs/api-reference/groups/add-a-member-to-a-group.md): Adds an active organization member or pending invite to a group. Requires admin access to the organization.

#### Skills

- [List skills](https://basedash.com/docs/api-reference/skills/list-skills.md): Lists all skills for an organization. Requires admin access to the organization. Results are paginated and ordered by creation date (newest first).
- [Create a skill](https://basedash.com/docs/api-reference/skills/create-a-skill.md): Creates a new skill within an organization. Requires admin access to the organization.
- [Get a skill](https://basedash.com/docs/api-reference/skills/get-a-skill.md): Retrieves a skill by ID. Requires admin access to the organization.
- [Delete a skill](https://basedash.com/docs/api-reference/skills/delete-a-skill.md): Deletes a skill by ID. Requires admin access to the organization.
- [Update a skill](https://basedash.com/docs/api-reference/skills/update-a-skill.md): Updates an existing skill. Requires admin access to the organization.

#### Chats

- [List chats](https://basedash.com/docs/api-reference/chats/list-chats.md): Lists chats created through the API, newest first. Only chats the API key owner has access to are returned.
- [Start a chat](https://basedash.com/docs/api-reference/chats/start-a-chat.md): 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 ass…
- [Get a chat](https://basedash.com/docs/api-reference/chats/get-a-chat.md): Retrieves a single chat, including its name and whether the assistant is currently responding.
- [Delete a chat](https://basedash.com/docs/api-reference/chats/delete-a-chat.md): Permanently deletes a chat and all of its messages, canceling any response that is still generating.
- [List messages in a chat](https://basedash.com/docs/api-reference/chats/list-messages-in-a-chat.md): Lists the messages in a chat, newest first. Each message includes its plain-text content plus structured parts (reasoning, tool activity, and referenced charts).
- [Send a follow-up message](https://basedash.com/docs/api-reference/chats/send-a-follow-up-message.md): 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 tim…
- [Get a message](https://basedash.com/docs/api-reference/chats/get-a-message.md): 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.
- [Cancel a response](https://basedash.com/docs/api-reference/chats/cancel-a-response.md): 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.
- [Stream an assistant message](https://basedash.com/docs/api-reference/chats/stream-an-assistant-message.md): 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…

## OpenAPI Specs

- [openapi](https://charts.basedash.com/api/public/openapi)