{"openapi":"3.2.0","info":{"title":"Databrain API","version":"2.0.0","description":"REST API for Databrain: guest tokens, datasources, datamarts, semantic layers, workspaces, embeds, data apps and self-hosted admin.\n\nSend your token as `Authorization: Bearer <token>`. See [Authentication](/developer-docs/helpers/api-reference/authentication).","contact":{"name":"Databrain support","url":"https://docs.usedatabrain.com"}},"servers":[{"url":"https://api.usedatabrain.com","description":"Databrain cloud"}],"security":[{"ApiToken":[]}],"tags":[{"name":"Authentication","description":"Send a service token or a data app API token with every request to the Databrain API. See [the overview](/developer-docs/helpers/api-reference/authentication)."},{"name":"Datasource APIs","description":"The Datasource APIs endpoints, in the order of the API Reference menu."},{"name":"Datamart APIs","description":"Create, list, update and delete datamarts: the tables, columns, joins and tenancy that metrics query. See [the overview](/developer-docs/helpers/api-reference/datamart-api)."},{"name":"Semantic Layer APIs","description":"Add descriptions, synonyms and column types to a datamart so Bryn and metric builders understand your data. See [the overview](/developer-docs/helpers/api-reference/semantic-layer-api)."},{"name":"Workspace APIs","description":"The Workspace APIs endpoints, in the order of the API Reference menu."},{"name":"Workspace APIs / Embedding API","description":"Find the dashboards and metrics of a workspace, so you can embed them. See [the overview](/developer-docs/helpers/api-reference/embedding-apis)."},{"name":"Embeds","description":"Create, change and remove the dashboards and metrics that a data app embeds. See [the overview](/developer-docs/helpers/api-reference/embed-data-app-crud)."},{"name":"Data App APIs / Data App CRUD","description":"The Data App APIs / Data App CRUD endpoints, in the order of the API Reference menu."},{"name":"Data App APIs / API Tokens","description":"The Data App APIs / API Tokens endpoints, in the order of the API Reference menu."},{"name":"Data App APIs / Data Retrieval","description":"The Data App APIs / Data Retrieval endpoints, in the order of the API Reference menu."},{"name":"Metric APIs","description":"The Metric APIs endpoints, in the order of the API Reference menu."},{"name":"Self-Hosted APIs","description":"The Self-Hosted APIs endpoints, in the order of the API Reference menu."}],"paths":{"/api/v2/guest-token/create":{"post":{"operationId":"token","summary":"Guest token","description":"Your backend calls this endpoint when a customer opens a page with an embed. Pass the returned `token` to the Databrain web component.\n\n```bash\ncurl --request POST https://api.usedatabrain.com/api/v2/guest-token/create \\\n  --header \"Authorization: Bearer $DATABRAIN_API_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\n    \"clientId\": \"acme\",\n    \"dataAppName\": \"Customer analytics\",\n    \"expiryTime\": 3600000,\n    \"params\": { \"userIdentifier\": \"jane@acme.com\" }\n  }'\n```\n\n## Before you start\n\n- You have a data app API token for the data app. A service token does not work here. See [Authentication](/developer-docs/helpers/api-reference/authentication).\n- Your plan includes embedding (Enterprise, a trial, or self-hosted).","tags":["Authentication"],"x-mint-page":"/developer-docs/helpers/api-reference/token","x-title":"Create a guest token","security":[{"DataAppApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"clientId":{"type":"string","description":"The tenant whose rows this viewer sees. It is not a person's id: every user of the same customer gets the same `clientId`. See the table below."},"dataAppName":{"type":"string","description":"The data app's name exactly as saved, with its spaces and capital letters. Must belong to the data app of your API token."},"expiryTime":{"anyOf":[{"type":"number"},{"type":"string"}],"description":"Lifetime in milliseconds from now, for example `3600000` for one hour. Must be positive. Default: 24 hours.","type":"number","default":86400000},"datasourceName":{"type":"string","description":"Multi-datasource workspaces: the datasource this viewer queries."},"datamartName":{"type":"string","description":"Multi-datamart workspaces: the datamart this viewer queries. Ignored when `datasourceName` is set."},"params":{"type":"object","properties":{"userIdentifier":{"type":"string","description":"The person viewing, for example an email. Their private metrics and saved views follow this value."},"timezone":{"type":"string","description":"IANA time zone for date filters and date grouping, for example `America/New_York`"},"allowedEmbeds":{"type":"array","items":{"type":"string"},"description":"Embed ids this token may open. Other embeds of the data app are refused."},"appFilters":{"type":"array","items":{"type":"object","properties":{"metricId":{"type":"string","x-mint-extra":true},"values":{"type":"object","x-mint-extra":true}},"required":["metricId","values"],"additionalProperties":false},"description":"Fixed filter values per metric: `{ \"metricId\": \"...\", \"values\": { \"<filter name>\": <value> } }`"},"dashboardAppFilters":{"type":"array","items":{"type":"object","properties":{"dashboardId":{"type":"string","x-mint-extra":true},"values":{"type":"object","x-mint-extra":true},"isShowOnUrl":{"type":"boolean","x-mint-extra":true}},"required":["dashboardId","values"],"additionalProperties":false},"description":"Fixed dashboard filter values: `{ \"dashboardId\": \"...\", \"values\": { ... }, \"isShowOnUrl\": false }`"},"rlsSettings":{"type":"array","items":{"type":"object","properties":{"metricId":{"type":"string","x-mint-extra":true},"values":{"type":"object","x-mint-extra":true}},"required":["metricId","values"],"additionalProperties":false},"description":"Row-level security values per metric: `{ \"metricId\": \"...\", \"values\": { ... } }`"},"tableAppFilters":{"type":"array","maxItems":50,"uniqueItems":true,"items":{"type":"object","properties":{"tableName":{"type":"string","maxLength":256,"pattern":"^[^\\s\"'`\\[\\];.\\\\]+(\\.[^\\s\"'`\\[\\];.\\\\]+)+$","x-mint-extra":true},"columnName":{"type":"string","maxLength":128,"pattern":"^[^\"'`\\[\\];.\\\\]+$","x-mint-extra":true},"values":{"type":"array","minItems":1,"maxItems":1000,"items":{"anyOf":[{"type":"string","maxLength":10000,"pattern":"^\\P{Cc}*$/u"},{"type":"number"}]},"x-mint-extra":true}},"required":["tableName","columnName","values"],"additionalProperties":false},"description":"A filter on one table column for every query: `{ \"tableName\": \"schema.table\", \"columnName\": \"region\", \"values\": [\"EU\"] }`. Up to 50 entries, 1 to 1,000 values each, one entry per column."},"hideDashboardMetrics":{"type":"array","items":{"type":"object","properties":{"dashboardId":{"type":"string","x-mint-extra":true},"metricIds":{"type":"array","items":{"type":"string"},"x-mint-extra":true}},"required":["dashboardId","metricIds"],"additionalProperties":false},"description":"Metrics to hide on a dashboard: `{ \"dashboardId\": \"...\", \"metricIds\": [\"...\"] }`"},"hideDashboardFilters":{"type":"array","items":{"type":"string"},"description":"Dashboard filter names to hide."},"accessPermissions":{"type":"object","properties":{"isAllowEndUserDashboardFilter":{"type":"boolean","description":"The viewer can add dashboard filters."},"isAllowEndUserMetricFilter":{"type":"boolean","description":"The viewer can add metric filters."},"isAllowDashboardFilterNameChange":{"type":"boolean","description":"The viewer can rename dashboard filters."},"isAllowMetricFilterNameChange":{"type":"boolean","description":"The viewer can rename metric filters."},"dashboardFilterColumns":{"type":"array","items":{"type":"object","properties":{"tableName":{"type":"string","x-mint-extra":true},"columns":{"type":"array","items":{"type":"string"},"x-mint-extra":true}},"required":["tableName","columns"],"additionalProperties":false},"description":"Columns the viewer can filter dashboards on: `{ \"tableName\": \"...\", \"columns\": [\"...\"] }`"},"metricFilterColumns":{"type":"array","items":{"type":"object","properties":{"tableName":{"type":"string","x-mint-extra":true},"columns":{"type":"array","items":{"type":"string"},"x-mint-extra":true}},"required":["tableName","columns"],"additionalProperties":false},"description":"Columns the viewer can filter metrics on, same shape."},"isAllowAutoClientScope":{"type":"boolean","description":"Table tenancy: add the tenant filter to every table that has the tenant column."}},"additionalProperties":false,"description":"Filter controls."}},"additionalProperties":false,"description":"Filters, visibility and viewer settings."},"permissions":{"type":"object","properties":{"isEnableArchiveMetrics":{"type":"boolean","description":"The viewer can archive metrics."},"isEnableManageMetrics":{"type":"boolean","description":"The viewer can manage metrics."},"isEnableCreateDashboardView":{"type":"boolean","description":"The viewer can create dashboard views."},"isEnableMetricUpdation":{"type":"boolean","description":"The viewer can edit metrics."},"isEnableCustomizeLayout":{"type":"boolean","description":"The viewer can change the dashboard layout."},"isEnableUnderlyingData":{"type":"boolean","description":"The viewer can see the underlying data."},"isEnableDownloadMetrics":{"type":"boolean","description":"The viewer can download metrics."},"isShowSideBar":{"type":"boolean","description":"The viewer can see the sidebar."},"isShowDashboardName":{"type":"boolean","description":"The viewer can see the dashboard name."},"isDisableMetricCreation":{"type":"boolean","description":"When `true`, the viewer cannot create metrics."}},"additionalProperties":false,"description":"What the viewer can do in the embed."}},"required":["clientId","dataAppName"],"additionalProperties":false},"example":{"clientId":"acme","dataAppName":"Customer analytics","expiryTime":3600000,"params":{"userIdentifier":"jane@acme.com"}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"token":"5b0c8e3a-2f1d-4c6b-9e7a-8d4f2a1b3c5d","expireAt":"2026-11-20T10:00:00.000Z"}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: A field is missing, unknown, or of the wrong type. `expiryTime` is not a positive number. `timezone` is not a valid time zone\n- `INVALID_DATA_APP_NAME`: No data app has this name\n- `AUTHENTICATION_ERROR`: The API token does not belong to this data app, or it is a service token\n- `DATASOURCE_NAME_ERROR`: No datasource has this `datasourceName`\n- `DATAMART_NAME_ERROR`: No datamart has this `datamartName`\n- `APP_FILTER_PARAM_ERROR`: An `appFilters` entry is not valid\n- `RLS_SETTINGS_PARAM_ERROR`: An `rlsSettings` entry is not valid\n- `DASHBOARD_PARAM_ERROR`: A `hideDashboardMetrics` entry names a dashboard or metric outside this data app\n- `INVALID_METRIC_ID`: A `hideDashboardMetrics` entry names a dashboard or metric outside this data app\n- `CLIENT_ID_ERROR`: The `clientId` matches no tenant. `hint` says what the tenancy expects\n- `LICENSE_EXPIRED`: Self-hosted only: the licence key expired. Renew the licence key\n- `UNSUBSCRIBED_ACCOUNT_ERROR`: The trial ended. Choose a plan in **Settings > Billing**","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"A field is missing, unknown, or of the wrong type. `expiryTime` is not a positive number. `timezone` is not a valid time zone"}}}}},"401":{"description":"- `AUTHENTICATION_ERROR`: The API token does not belong to this data app, or it is a service token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"The API token does not belong to this data app, or it is a service token"}}}}},"403":{"description":"- `entitlement_required`: Your plan does not include embedding\n- `ACCOUNT_DISABLED`: The organization is disabled or locked for deletion. Contact Databrain support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"entitlement_required","message":"Your plan does not include embedding"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: Databrain failed. Try again. If it fails again, contact support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"Databrain failed. Try again. If it fails again, contact support"}}}}},"503":{"description":"- `entitlement_check_unavailable`: Databrain could not check your plan. Try again\n- `CLIENT_ID_ERROR`: Databrain could not check the `clientId` right now. No token was made. Try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"entitlement_check_unavailable","message":"Databrain could not check your plan. Try again"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body","intro":"Only `clientId` and `dataAppName` are required. The body is validated strictly: an unknown field returns `400 INVALID_REQUEST_BODY`. `dataAppId`, `client_id`, `tenant_id`, `workspaceName` and `permissions.dashboards` are not fields.","after":"### What to send as `clientId`\n\n| Tenancy of the datamart | `clientId` |\n| --- | --- |\n| Row per tenant (a tenant column) | The tenant column value for this customer, exactly as stored, for example `\"104\"` |\n| Schema or database per tenant | The tenant's schema or database name, as mapped in the datamart |\n| Datasource per tenant | The tenant name mapped to that customer's datasource |\n| No tenancy | Any non-empty string, for example `\"None\"`. It is not used |\n\nTake the value from your server session, never from the browser. `\"104\"` and `\"0104\"` are different tenants. A value that matches no tenant returns `400 CLIENT_ID_ERROR`; it never widens access.\n\n### Expiry\n\n- A company on the current plans gets a token that lives at most 24 hours. A longer `expiryTime` is not refused: the token gets 24 hours, and `expireAt` in the response shows the real expiry.\n- Legacy contracts and self-hosted installs get the `expiryTime` you send. Self-hosted can change the default with `GUEST_TOKEN_DEFAULT_EXPIRY_MS`."}],"x-mint-rest":"## Response\n\n```json\n{\n  \"token\": \"5b0c8e3a-2f1d-4c6b-9e7a-8d4f2a1b3c5d\",\n  \"expireAt\": \"2026-11-20T10:00:00.000Z\"\n}\n```\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `token` | string | The guest token. Pass it to the web component |\n| `expireAt` | string or null | When the token expires (ISO 8601). It can be earlier than you asked |\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | A field is missing, unknown, or of the wrong type. `expiryTime` is not a positive number. `timezone` is not a valid time zone |\n| 400 | `INVALID_DATA_APP_NAME` | No data app has this name |\n| 400 | `AUTHENTICATION_ERROR` | The API token does not belong to this data app, or it is a service token |\n| 400 | `CLIENT_ID_ERROR` | The `clientId` matches no tenant. `hint` says what the tenancy expects |\n| 400 | `DATASOURCE_NAME_ERROR` | No datasource has this `datasourceName` |\n| 400 | `DATAMART_NAME_ERROR` | No datamart has this `datamartName` |\n| 400 | `APP_FILTER_PARAM_ERROR` | An `appFilters` entry is not valid |\n| 400 | `RLS_SETTINGS_PARAM_ERROR` | An `rlsSettings` entry is not valid |\n| 400 | `DASHBOARD_PARAM_ERROR` or `INVALID_METRIC_ID` | A `hideDashboardMetrics` entry names a dashboard or metric outside this data app |\n| 403 | `entitlement_required` | Your plan does not include embedding |\n| 503 | `CLIENT_ID_ERROR` | Databrain could not check the `clientId` right now. No token was made. Try again |\n| 503 | `entitlement_check_unavailable` | Databrain could not check your plan. Try again |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint).\n\n## Older version\n\n`POST /api/v1/guest-token/create` still works for older integrations. It takes `workspaceName` instead of `dataAppName` and refuses a data app API token. It also needs embedding on your plan. Use v2 for new code. See the [API migration guide](/developer-docs/api-migration-guide).\n\nNext, [embed the dashboard with the token](/developer-docs/how-to-embed)."}},"/api/v2/data-app/embed-access":{"get":{"operationId":"checkEmbedAccess","summary":"Check embed access","description":"Call this before you create a data app, an embed or a guest token. It changes nothing.\n\n```bash\ncurl https://api.usedatabrain.com/api/v2/data-app/embed-access \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\"\n```\n\n## Auth\n\nA service token or a data app API token. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Authentication"],"x-mint-page":"/developer-docs/helpers/api-reference/check-embed-access","x-title":"Check embed access","security":[{"ApiToken":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"embed":true}}}},"403":{"description":"- `entitlement_required`: Your plan does not include embedding","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"entitlement_required","message":"Embedding needs the Enterprise plan. This workspace is on Team.","capability":"embed","currentPlan":"team","requiredPlan":"enterprise"}}}}},"503":{"description":"- `entitlement_check_unavailable`: Databrain could not check your plan. Try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"entitlement_check_unavailable","message":"Databrain could not check your plan. Try again"}}}}}},"x-mint-rest":"## Response\n\nYour plan includes embedding:\n\n```json\n{ \"embed\": true }\n```\n\nYour plan does not include embedding. The status is `403`:\n\n```json\n{\n  \"error\": {\n    \"code\": \"entitlement_required\",\n    \"message\": \"Embedding needs the Enterprise plan. This workspace is on Team.\",\n    \"capability\": \"embed\",\n    \"currentPlan\": \"team\",\n    \"requiredPlan\": \"enterprise\"\n  }\n}\n```\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `capability` | string | Always `embed` |\n| `currentPlan` | string or null | Your plan: `solo`, `team`, `business` or `enterprise` |\n| `requiredPlan` | string or null | The plan that includes embedding. `null` means no plan includes it and Databrain must turn it on for you |\n\nEmbedding is on the Enterprise plan, on a trial, and on self-hosted. Databrain can also turn it on for your organization.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 403 | `entitlement_required` | Your plan does not include embedding |\n| 503 | `entitlement_check_unavailable` | Databrain could not check your plan. Try again |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/datasource":{"post":{"operationId":"createDatasource","summary":"Create datasource","description":"Databrain tests the connection, saves the datasource and reads its schema. The call returns when the schema is cached.\n\n```bash\ncurl --request POST https://api.usedatabrain.com/api/v2/datasource \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\n    \"datasourceType\": \"postgres\",\n    \"credentials\": {\n      \"name\": \"Sales warehouse\",\n      \"host\": \"db.example.com\",\n      \"port\": 5432,\n      \"username\": \"databrain_reader\",\n      \"password\": \"<password>\",\n      \"database\": \"analytics\",\n      \"schema\": \"public\",\n      \"sslMode\": \"require\"\n    }\n  }'\n```\n\n## Auth\n\nA service token. See [Authentication](/developer-docs/helpers/api-reference/authentication).\n\n## Limits\n\n- 10 requests in 5 minutes per organization, shared with update, sync and schema discovery. Over the limit you get `429` with a plain-text body.\n- The host must be a public address. Databrain cloud can refuse loopback, private, link-local and metadata addresses.","tags":["Datasource APIs"],"x-mint-page":"/developer-docs/helpers/api-reference/create-datasource","x-title":"Create a datasource","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datasourceType":{"type":"string","enum":["snowflake","postgres","cockroachdb","redshift","mysql","mongodb","clickhouse","singlestore","bigquery","databricks","elasticsearch","opensearch","mssql","awss3","csv","firebolt","athena","trino"],"description":"One of the types in the table below, in lower case."},"credentials":{"type":"object","properties":{"name":{"type":"string","description":"The datasource name, unique in your organization."},"host":{"type":"string","description":"For `postgres`, `mysql`, `mongodb`, `clickhouse`, `singlestore`, `snowflake`, `trino`. See [Credentials by type](#credentials-by-type)."},"port":{"type":"integer","description":"For `postgres`, `mysql`, `mongodb`, `clickhouse`, `singlestore`, `mssql`, `trino`. See [Credentials by type](#credentials-by-type)."},"username":{"type":"string","description":"For `postgres`, `snowflake`, `trino`. See [Credentials by type](#credentials-by-type)."},"password":{"type":"string","description":"For `postgres`, `mysql`, `mongodb`, `clickhouse`, `singlestore`, `mssql`, `snowflake`, `elasticsearch`, `opensearch`, `trino`. See [Credentials by type](#credentials-by-type)."},"database":{"type":"string","description":"For `postgres`, `singlestore`, `mssql`, `snowflake`, `athena`, `firebolt`. See [Credentials by type](#credentials-by-type)."},"schema":{"type":"string","description":"For `postgres`, `snowflake`, `firebolt`, `trino`. See [Credentials by type](#credentials-by-type)."},"sslMode":{"type":"string","description":"For `postgres`. See [Credentials by type](#credentials-by-type)."},"sshTunnel":{"type":"string","description":"For `postgres`, `mssql`, `trino`. See [Credentials by type](#credentials-by-type).","enum":["enable","disable"]},"sshHost":{"type":"string","description":"For `postgres`, `mssql`, `trino`. See [Credentials by type](#credentials-by-type)."},"sshPort":{"type":"integer","description":"For `postgres`, `mssql`, `trino`. See [Credentials by type](#credentials-by-type)."},"sshUsername":{"type":"string","description":"For `postgres`, `mssql`, `trino`. See [Credentials by type](#credentials-by-type)."},"sshPrivateKey":{"type":"string","description":"For `postgres`, `mssql`, `trino`. See [Credentials by type](#credentials-by-type)."},"user":{"type":"string","description":"For `mysql`, `mongodb`, `clickhouse`, `singlestore`, `mssql`. See [Credentials by type](#credentials-by-type)."},"server":{"type":"string","description":"For `mssql`. See [Credentials by type](#credentials-by-type)."},"isDisableDatabase":{"type":"boolean","description":"For `mssql`. See [Credentials by type](#credentials-by-type)."},"readOnlyIntent":{"type":"boolean","description":"For `mssql`. See [Credentials by type](#credentials-by-type)."},"role":{"type":"string","description":"For `snowflake`. See [Credentials by type](#credentials-by-type)."},"warehouse":{"type":"string","description":"For `snowflake`. See [Credentials by type](#credentials-by-type)."},"credentials":{"type":"string","description":"For `snowflake`, `databricks`. See [Credentials by type](#credentials-by-type)."},"privateKey":{"type":"string","description":"For `snowflake`. See [Credentials by type](#credentials-by-type)."},"privateKeyPass":{"type":"string","description":"For `snowflake`. See [Credentials by type](#credentials-by-type)."},"credentials_json":{"type":"string","description":"For `bigquery`. See [Credentials by type](#credentials-by-type)."},"project_id":{"type":"string","description":"For `bigquery`. See [Credentials by type](#credentials-by-type)."},"dataset_location":{"type":"string","description":"For `bigquery`. See [Credentials by type](#credentials-by-type)."},"dataset_id":{"type":"string","description":"For `bigquery`. See [Credentials by type](#credentials-by-type)."},"serverHostname":{"type":"string","description":"For `databricks`. See [Credentials by type](#credentials-by-type)."},"httpPath":{"type":"string","description":"For `databricks`. See [Credentials by type](#credentials-by-type)."},"token":{"type":"string","description":"For `databricks`. See [Credentials by type](#credentials-by-type)."},"clientSecret":{"type":"string","description":"For `databricks`. See [Credentials by type](#credentials-by-type)."},"queryTags":{"type":"string","description":"For `databricks`. See [Credentials by type](#credentials-by-type)."},"server_type":{"type":"string","description":"For `elasticsearch`, `opensearch`. See [Credentials by type](#credentials-by-type).","enum":["elastic-cloud","open-cloud","self-managed"]},"cloud_id":{"type":"string","description":"For `elasticsearch`, `opensearch`. See [Credentials by type](#credentials-by-type)."},"server_url":{"type":"string","description":"For `elasticsearch`, `opensearch`. See [Credentials by type](#credentials-by-type)."},"isIgnoreVerifyCert":{"type":"boolean","description":"For `elasticsearch`, `opensearch`. See [Credentials by type](#credentials-by-type)."},"isIgnoreSsl":{"type":"boolean","description":"For `elasticsearch`, `opensearch`. See [Credentials by type](#credentials-by-type)."},"bucketName":{"type":"string","description":"For `awss3`. See [Credentials by type](#credentials-by-type)."},"datasetPath":{"type":"string","description":"For `awss3`. See [Credentials by type](#credentials-by-type)."},"tableLevel":{"type":"string","description":"For `awss3`. See [Credentials by type](#credentials-by-type).","enum":["File","Folder"]},"outputBucket":{"type":"string","description":"For `athena`. See [Credentials by type](#credentials-by-type)."},"client_id":{"type":"string","description":"For `firebolt`. See [Credentials by type](#credentials-by-type)."},"client_secret":{"type":"string","description":"For `firebolt`. See [Credentials by type](#credentials-by-type)."},"account":{"type":"string","description":"For `firebolt`. See [Credentials by type](#credentials-by-type)."},"engineName":{"type":"string","description":"For `firebolt`. See [Credentials by type](#credentials-by-type)."},"catalog":{"type":"string","description":"For `trino`. See [Credentials by type](#credentials-by-type)."},"clientId":{"type":"string","description":"`databricks` with OAuth service principal, and `microsoft fabric`: the app's client id.","x-mint-extra":true},"tenantId":{"type":"string","description":"`microsoft fabric`: the Microsoft Entra tenant id. Can be empty.","x-mint-extra":true},"disableAuth":{"type":"boolean","default":false,"description":"`elasticsearch` and `opensearch`, self-managed only: `true` connects without a username and password.","x-mint-extra":true},"s3Region":{"type":"string","description":"AWS region of the bucket. Required for `awss3` and `athena`.","x-mint-extra":true},"s3AccessKeyId":{"type":"string","description":"AWS access key id. Required for `awss3` and `athena`.","x-mint-extra":true},"s3SecretAccessKey":{"type":"string","description":"AWS secret access key. Required for `awss3` and `athena`.","x-mint-extra":true},"datasourceId":{"type":"string","description":"`athena` only. Optional.","x-mint-extra":true}},"additionalProperties":true,"description":"Connection fields for the type. `credentials.name` is the datasource name and must be unique in your organization.","required":["name"]},"tenancySettings":{"type":"object","properties":{"tenancyLevel":{"type":"string","enum":["TABLE","DATABASE"],"description":"`TABLE` (a tenant column) or `DATABASE` (a schema or database per tenant)"},"schemaName":{"type":"string","description":"Required for `TABLE`. Schema of the table that lists your tenants."},"tableName":{"type":"string","description":"Required for `TABLE`. Table that lists your tenants."},"tableClientNameColumn":{"type":"string","description":"Required for `TABLE`. Column with the tenant name."},"tablePrimaryKeyColumn":{"type":"string","description":"Required for `TABLE`. Column with the tenant id, the value you send as `clientId`"},"clientColumnType":{"type":"string","enum":["NUMBER","STRING"],"description":"Required for `TABLE`. `STRING` or `NUMBER`","default":"STRING"}},"additionalProperties":false,"description":"Tenancy for this datasource."}},"required":["datasourceType","credentials"],"additionalProperties":false},"example":{"datasourceType":"postgres","credentials":{"name":"Sales warehouse","host":"db.example.com","port":5432,"username":"databrain_reader","password":"<password>","database":"analytics","schema":"public","sslMode":"require"}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"name":"Sales warehouse","warnings":[{"code":"TENANCY_CLIENT_NAME_NOT_UNIQUE","message":"120 client ids share 118 names in company_name. Pick a name column with one name per client, or a table with one row per client.","keyCount":120,"nameCount":118}]}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: A field is missing, unknown or wrong. The message names it, for example `Invalid credentials for postgres: \"host\" is required`. Also a refused host, or an unsupported type\n- `AUTHENTICATION_ERROR`: No `Authorization: Bearer` header, or the token is not a UUID. Send `Authorization: Bearer <token>`\n- `DATASOURCE_NAME_ERROR`: The name is already used\n- `CREDENTIAL_TEST_FAILED`: Databrain could not connect. `hint` says what to check. `retryable` says if a retry can help\n- `CREATE_DATASOURCE_FAILED`: The datasource could not be saved\n- `SCHEMA_CACHE_FAILED`: The datasource was saved, but its schema could not be read. Do not create it again: run [sync](/developer-docs/helpers/api-reference/sync-datasource)\n- `LICENSE_EXPIRED`: Self-hosted only: the licence key expired. Renew the licence key\n- `UNSUBSCRIBED_ACCOUNT_ERROR`: The trial ended. Choose a plan in **Settings > Billing**","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"A field is missing, unknown or wrong. The message names it, for example `Invalid credentials for postgres: \"host\" is required`. Also a refused host, or an unsupported type"}}}}},"401":{"description":"- `AUTHENTICATION_ERROR`: The token is unknown, revoked or expired. Use a current token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"The token is unknown, revoked or expired. Use a current token"}}}}},"403":{"description":"- `DATABRICKS_OAUTH_NOT_ENABLED`: Databricks OAuth is not on for your organization\n- `AUTHENTICATION_ERROR`: A data app API token on a service-token endpoint. Use a service token\n- `TRIAL_ENDED`: The trial ended. Choose a plan in **Settings > Billing**\n- `ACCOUNT_DISABLED`: The organization is disabled or locked for deletion. Contact Databrain support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"DATABRICKS_OAUTH_NOT_ENABLED","message":"Databricks OAuth is not on for your organization"}}}}},"429":{"description":"- Too many datasource changes: at most 10 every 5 minutes. The body is plain text.\n- Rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Too many datasource changes: at most 10 every 5 minutes. The body is plain text."}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: Databrain failed. Try again. If it fails again, contact support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"Databrain failed. Try again. If it fails again, contact support"}}}}},"503":{"description":"- `COMMERCIAL_UNAVAILABLE`: Databrain could not check your plan. Try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"COMMERCIAL_UNAVAILABLE","message":"Databrain could not check your plan. Try again"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body","after":"Unknown fields are refused, in the body and in `credentials`.\n\n### Credentials by type\n\nEvery type also needs `name`. R = required, O = optional.\n\n| `datasourceType` | Fields |\n| --- | --- |\n| `postgres` | `host` R, `port` R, `username` R, `password` R, `database` R, `schema` R, `sslMode` O (`true`, `false`, `disable`, `prefer`, `require`, `verify-ca` or `verify-full`), SSH fields O |\n| `redshift`, `cockroachdb` | As `postgres`, but `sslMode` is `true` or `false` |\n| `mysql`, `mongodb`, `clickhouse` | `host` R, `port` R, `user` R, `password` R |\n| `singlestore` | `host` R, `port` R, `user` R, `password` R, `database` R |\n| `mssql` | `server` R, `port` R, `user` R, `password` R, `database` O, `isDisableDatabase` O, `readOnlyIntent` O, SSH fields O |\n| `snowflake` | `host` R, `username` R, `role` R, `warehouse` R, `database` R, `schema` R, `credentials` R (`username/password` or `Key-pair authentication`), `password` R for username/password, `privateKey` R for key pair, `privateKeyPass` O |\n| `bigquery` | `credentials_json` R (the service account JSON as a string), `project_id` R, `dataset_location` R, `dataset_id` O |\n| `databricks` | `serverHostname` R, `httpPath` R, `credentials` O (`Personal access token`, the default, or `OAuth service principal`), `token` R for a personal access token, `clientId` and `clientSecret` R for a service principal, `queryTags` O (`key:value,key:value`, up to 10 pairs) |\n| `elasticsearch`, `opensearch` | `server_type` R (`elastic-cloud`, `open-cloud` or `self-managed`), `cloud_id` R for a cloud type, `server_url` R for self-managed, `username` and `password` R unless `disableAuth` is `true` (self-managed only), `isIgnoreVerifyCert` O, `isIgnoreSsl` O |\n| `awss3` | `bucketName` R, `s3Region` R, `s3AccessKeyId` R, `s3SecretAccessKey` R, `datasetPath` O, `tableLevel` O (`File` or `Folder`) |\n| `athena` | `database` R, `outputBucket` R, `s3Region` R, `s3AccessKeyId` R, `s3SecretAccessKey` R |\n| `firebolt` | `client_id` R, `client_secret` R, `account` R, `database` R, `engineName` R, `schema` O |\n| `trino` | `host` R, `port` R, `catalog` R, `schema` R, `username` R, `password` R, SSH fields O |\n| `csv` | `name` only |\n\n`port` is a whole number from 1 to 65535.\n\nSSH fields: `sshTunnel` (`enable` or `disable`). With `enable`, also send `sshHost`, `sshPort`, `sshUsername` and `sshPrivateKey`.\n\nMicrosoft Fabric cannot be created with this endpoint. Connect it in the app.\n\nDatabricks OAuth service principal must be turned on for your organization. If it is not, you get `403 DATABRICKS_OAUTH_NOT_ENABLED`."}],"x-mint-rest":"## Response\n\n```json\n{\n  \"name\": \"Sales warehouse\",\n  \"warnings\": [\n    {\n      \"code\": \"TENANCY_CLIENT_NAME_NOT_UNIQUE\",\n      \"message\": \"120 client ids share 118 names in company_name. Pick a name column with one name per client, or a table with one row per client.\",\n      \"keyCount\": 120,\n      \"nameCount\": 118\n    }\n  ]\n}\n```\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `name` | string | The datasource name |\n| `warnings` | object[] | Only with `TABLE` tenancy. `TENANCY_CLIENT_TABLE_EMPTY`: the tenant table has no rows. `TENANCY_CLIENT_NAME_NOT_UNIQUE`: two tenant ids share a name |\n\nThe response has no id. To get it, [list datasources](/developer-docs/helpers/api-reference/list-datasources).\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | A field is missing, unknown or wrong. The message names it, for example `Invalid credentials for postgres: \"host\" is required`. Also a refused host, or an unsupported type |\n| 400 | `DATASOURCE_NAME_ERROR` | The name is already used |\n| 400 | `CREDENTIAL_TEST_FAILED` | Databrain could not connect. `hint` says what to check. `retryable` says if a retry can help |\n| 400 | `CREATE_DATASOURCE_FAILED` | The datasource could not be saved |\n| 400 | `SCHEMA_CACHE_FAILED` | The datasource was saved, but its schema could not be read. Do not create it again: run [sync](/developer-docs/helpers/api-reference/sync-datasource) |\n| 403 | `DATABRICKS_OAUTH_NOT_ENABLED` | Databricks OAuth is not on for your organization |\n| 429 | | Rate limit |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint).\n\nNext, [create a datamart](/developer-docs/helpers/api-reference/create-datamart) on the datasource."},"get":{"operationId":"listDatasources","summary":"List datasources","description":"Use the `id` to [sync a datasource](/developer-docs/helpers/api-reference/sync-datasource) and the `name` in every other datasource call. Credentials are never returned.\n\n```bash\ncurl \"https://api.usedatabrain.com/api/v2/datasource?isPagination=true&pageNumber=1\" \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\"\n```\n\n## Auth\n\nA service token. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Datasource APIs"],"x-mint-page":"/developer-docs/helpers/api-reference/list-datasources","x-title":"List datasources","security":[{"ApiToken":[]}],"parameters":[{"name":"isPagination","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]},"description":"`true` returns 10 datasources per page. Without it you get all of them."},{"name":"pageNumber","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Page to return, from `1`. Used only with `isPagination=true`"}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"6f1c2b9e-4d3a-4f8e-9b7c-2a1d0e5f6c7b","name":"Sales warehouse","isAuthenticated":true,"isDisabled":false}]}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: `pageNumber` is not a whole number from 1\n- `AUTHENTICATION_ERROR`: No `Authorization: Bearer` header, or the token is not a UUID. Send `Authorization: Bearer <token>`\n- `LICENSE_EXPIRED`: Self-hosted only: the licence key expired. Renew the licence key\n- `UNSUBSCRIBED_ACCOUNT_ERROR`: The trial ended. Choose a plan in **Settings > Billing**","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"`pageNumber` is not a whole number from 1"}}}}},"401":{"description":"- `AUTHENTICATION_ERROR`: The token is unknown, revoked or expired. Use a current token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"The token is unknown, revoked or expired. Use a current token"}}}}},"403":{"description":"- `AUTHENTICATION_ERROR`: A data app API token on a service-token endpoint. Use a service token\n- `ACCOUNT_DISABLED`: The organization is disabled or locked for deletion. Contact Databrain support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"A data app API token on a service-token endpoint. Use a service token"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: Databrain failed. Try again. If it fails again, contact support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"Databrain failed. Try again. If it fails again, contact support"}}}}}},"x-mint-sections":[{"in":"parameters","heading":"Query","after":"The order is not fixed, and there is no total count. Without pagination you get the full list in one response."}],"x-mint-rest":"## Response\n\n```json\n{\n  \"data\": [\n    {\n      \"id\": \"6f1c2b9e-4d3a-4f8e-9b7c-2a1d0e5f6c7b\",\n      \"name\": \"Sales warehouse\",\n      \"isAuthenticated\": true,\n      \"isDisabled\": false\n    }\n  ]\n}\n```\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `id` | string | The datasource id |\n| `name` | string | The datasource name |\n| `isAuthenticated` | boolean | The last connection test passed |\n| `isDisabled` | boolean | The datasource is turned off |\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | `pageNumber` is not a whole number from 1 |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."},"put":{"operationId":"updateDatasource","summary":"Update datasource","description":"Use it to change a password, a host, or the tenancy setup. Databrain tests the new credentials and reads the schema again.\n\n```bash\ncurl --request PUT https://api.usedatabrain.com/api/v2/datasource \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\n    \"datasourceType\": \"postgres\",\n    \"credentials\": {\n      \"name\": \"Sales warehouse\",\n      \"host\": \"db.example.com\",\n      \"port\": 5432,\n      \"username\": \"databrain_reader\",\n      \"password\": \"<new password>\",\n      \"database\": \"analytics\",\n      \"schema\": \"public\"\n    }\n  }'\n```\n\n## Auth\n\nA service token. See [Authentication](/developer-docs/helpers/api-reference/authentication).\n\n## Limits\n\n10 requests in 5 minutes per organization, shared with create, sync and schema discovery.","tags":["Datasource APIs"],"x-mint-page":"/developer-docs/helpers/api-reference/update-datasource","x-title":"Update a datasource","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datasourceType":{"type":"string","enum":["snowflake","postgres","postgresql","cockroachdb","redshift","mysql","mongodb","clickhouse","singlestore","bigquery","databricks","elasticsearch","opensearch","mssql","awss3","csv","firebolt","athena","trino","microsoft fabric"],"description":"One of the types in the table below, in lower case."},"credentials":{"type":"object","properties":{"name":{"type":"string","description":"The datasource name, unique in your organization."},"host":{"type":"string","description":"For `postgres`, `mysql`, `mongodb`, `clickhouse`, `singlestore`, `snowflake`, `trino`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"port":{"type":"integer","description":"For `postgres`, `mysql`, `mongodb`, `clickhouse`, `singlestore`, `mssql`, `trino`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"username":{"type":"string","description":"For `postgres`, `snowflake`, `trino`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"password":{"type":"string","description":"For `postgres`, `mysql`, `mongodb`, `clickhouse`, `singlestore`, `mssql`, `snowflake`, `elasticsearch`, `opensearch`, `trino`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"database":{"type":"string","description":"For `postgres`, `singlestore`, `mssql`, `snowflake`, `athena`, `firebolt`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"schema":{"type":"string","description":"For `postgres`, `snowflake`, `firebolt`, `trino`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"sslMode":{"type":"string","description":"For `postgres`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"sshTunnel":{"type":"string","description":"For `postgres`, `mssql`, `trino`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type).","enum":["enable","disable"]},"sshHost":{"type":"string","description":"For `postgres`, `mssql`, `trino`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"sshPort":{"type":"integer","description":"For `postgres`, `mssql`, `trino`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"sshUsername":{"type":"string","description":"For `postgres`, `mssql`, `trino`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"sshPrivateKey":{"type":"string","description":"For `postgres`, `mssql`, `trino`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"user":{"type":"string","description":"For `mysql`, `mongodb`, `clickhouse`, `singlestore`, `mssql`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"server":{"type":"string","description":"For `mssql`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"isDisableDatabase":{"type":"boolean","description":"For `mssql`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"readOnlyIntent":{"type":"boolean","description":"For `mssql`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"role":{"type":"string","description":"For `snowflake`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"warehouse":{"type":"string","description":"For `snowflake`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"credentials":{"type":"string","description":"For `snowflake`, `databricks`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"privateKey":{"type":"string","description":"For `snowflake`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"privateKeyPass":{"type":"string","description":"For `snowflake`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"credentials_json":{"type":"string","description":"For `bigquery`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"project_id":{"type":"string","description":"For `bigquery`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"dataset_location":{"type":"string","description":"For `bigquery`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"dataset_id":{"type":"string","description":"For `bigquery`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"serverHostname":{"type":"string","description":"For `databricks`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"httpPath":{"type":"string","description":"For `databricks`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"token":{"type":"string","description":"For `databricks`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"clientSecret":{"type":"string","description":"For `databricks`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"queryTags":{"type":"string","description":"For `databricks`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"server_type":{"type":"string","description":"For `elasticsearch`, `opensearch`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type).","enum":["elastic-cloud","open-cloud","self-managed"]},"cloud_id":{"type":"string","description":"For `elasticsearch`, `opensearch`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"server_url":{"type":"string","description":"For `elasticsearch`, `opensearch`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"isIgnoreVerifyCert":{"type":"boolean","description":"For `elasticsearch`, `opensearch`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"isIgnoreSsl":{"type":"boolean","description":"For `elasticsearch`, `opensearch`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"bucketName":{"type":"string","description":"For `awss3`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"datasetPath":{"type":"string","description":"For `awss3`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"tableLevel":{"type":"string","description":"For `awss3`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type).","enum":["File","Folder"]},"outputBucket":{"type":"string","description":"For `athena`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"client_id":{"type":"string","description":"For `firebolt`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"client_secret":{"type":"string","description":"For `firebolt`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"account":{"type":"string","description":"For `firebolt`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"engineName":{"type":"string","description":"For `firebolt`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"catalog":{"type":"string","description":"For `trino`. See [Credentials by type](/developer-docs/helpers/api-reference/create-datasource#credentials-by-type)."},"clientId":{"type":"string","description":"`databricks` with OAuth service principal, and `microsoft fabric`: the app's client id.","x-mint-extra":true},"tenantId":{"type":"string","description":"`microsoft fabric`: the Microsoft Entra tenant id. Can be empty.","x-mint-extra":true},"disableAuth":{"type":"boolean","default":false,"description":"`elasticsearch` and `opensearch`, self-managed only: `true` connects without a username and password.","x-mint-extra":true},"s3Region":{"type":"string","description":"AWS region of the bucket. Required for `awss3` and `athena`.","x-mint-extra":true},"s3AccessKeyId":{"type":"string","description":"AWS access key id. Required for `awss3` and `athena`.","x-mint-extra":true},"s3SecretAccessKey":{"type":"string","description":"AWS secret access key. Required for `awss3` and `athena`.","x-mint-extra":true},"datasourceId":{"type":"string","description":"`athena` only. Optional.","x-mint-extra":true}},"additionalProperties":true,"description":"Connection fields for the type. `credentials.name` is the datasource name and must be unique in your organization.","required":["name"]},"tenancySettings":{"type":"object","properties":{"tenancyLevel":{"type":"string","enum":["TABLE","DATABASE"],"description":"`TABLE` (a tenant column) or `DATABASE` (a schema or database per tenant)"},"schemaName":{"type":"string","description":"Required for `TABLE`. Schema of the table that lists your tenants."},"tableName":{"type":"string","description":"Required for `TABLE`. Table that lists your tenants."},"tableClientNameColumn":{"type":"string","description":"Required for `TABLE`. Column with the tenant name."},"tablePrimaryKeyColumn":{"type":"string","description":"Required for `TABLE`. Column with the tenant id, the value you send as `clientId`"},"clientColumnType":{"type":"string","enum":["NUMBER","STRING"],"description":"Required for `TABLE`. `STRING` or `NUMBER`","default":"STRING"}},"additionalProperties":false,"description":"Tenancy for this datasource."}},"required":["datasourceType","credentials"],"additionalProperties":false},"example":{"datasourceType":"postgres","credentials":{"name":"Sales warehouse","host":"db.example.com","port":5432,"username":"databrain_reader","password":"<new password>","database":"analytics","schema":"public"}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"name":"Sales warehouse"}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: A field is missing, unknown or wrong, or the host is refused\n- `AUTHENTICATION_ERROR`: No `Authorization: Bearer` header, or the token is not a UUID. Send `Authorization: Bearer <token>`\n- `DATASOURCE_NAME_ERROR`: No datasource has this `credentials.name`\n- `CREDENTIAL_TEST_FAILED`: Databrain could not connect with the new credentials. Nothing was changed\n- `DATASOURCE_NOT_FOUND`: The datasource was removed while you updated it\n- `TENANCY_SETTINGS_CREATE_FAILED`: The credentials were saved, the tenancy was not\n- `TENANCY_SETTINGS_UPDATE_FAILED`: The credentials were saved, the tenancy was not\n- `SCHEMA_CACHE_FAILED`: Credentials and tenancy were saved, the schema was not read. Run [sync](/developer-docs/helpers/api-reference/sync-datasource)\n- `LICENSE_EXPIRED`: Self-hosted only: the licence key expired. Renew the licence key\n- `UNSUBSCRIBED_ACCOUNT_ERROR`: The trial ended. Choose a plan in **Settings > Billing**","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"A field is missing, unknown or wrong, or the host is refused"}}}}},"401":{"description":"- `AUTHENTICATION_ERROR`: The token is unknown, revoked or expired. Use a current token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"The token is unknown, revoked or expired. Use a current token"}}}}},"403":{"description":"- `DATABRICKS_OAUTH_NOT_ENABLED`: Databricks OAuth is not on for your organization\n- `AUTHENTICATION_ERROR`: A data app API token on a service-token endpoint. Use a service token\n- `TRIAL_ENDED`: The trial ended. Choose a plan in **Settings > Billing**\n- `ACCOUNT_DISABLED`: The organization is disabled or locked for deletion. Contact Databrain support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"DATABRICKS_OAUTH_NOT_ENABLED","message":"Databricks OAuth is not on for your organization"}}}}},"429":{"description":"- Too many datasource changes: at most 10 every 5 minutes. The body is plain text.\n- Rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Too many datasource changes: at most 10 every 5 minutes. The body is plain text."}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: Databrain failed. Try again. If it fails again, contact support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"Databrain failed. Try again. If it fails again, contact support"}}}}},"503":{"description":"- `COMMERCIAL_UNAVAILABLE`: Databrain could not check your plan. Try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"COMMERCIAL_UNAVAILABLE","message":"Databrain could not check your plan. Try again"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body","intro":"The body is the same as [Create a datasource](/developer-docs/helpers/api-reference/create-datasource#body), with the same credential fields per type. These rules are different:\n\n- `credentials.name` picks the datasource to update. You cannot rename a datasource with this call.\n- `credentials` replaces all stored credentials. Send every required field again, not only the ones that change.\n- `datasourceType` is used only to check and test the credentials. It does not change the type of the datasource. Send the type it already has.\n- `tenancySettings` is optional. If you leave out `tenancyLevel`, the stored level stays.\n- Microsoft Fabric (`microsoft fabric`) can be updated here, with `server`, `port`, `database`, `clientId`, and `user` and `password` or `clientSecret`."}],"x-mint-rest":"## Response\n\n```json\n{\n  \"name\": \"Sales warehouse\"\n}\n```\n\nThe response can also have `warnings`, as on create.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | A field is missing, unknown or wrong, or the host is refused |\n| 400 | `DATASOURCE_NAME_ERROR` | No datasource has this `credentials.name` |\n| 400 | `DATASOURCE_NOT_FOUND` | The datasource was removed while you updated it |\n| 400 | `CREDENTIAL_TEST_FAILED` | Databrain could not connect with the new credentials. Nothing was changed |\n| 400 | `TENANCY_SETTINGS_CREATE_FAILED` or `TENANCY_SETTINGS_UPDATE_FAILED` | The credentials were saved, the tenancy was not |\n| 400 | `SCHEMA_CACHE_FAILED` | Credentials and tenancy were saved, the schema was not read. Run [sync](/developer-docs/helpers/api-reference/sync-datasource) |\n| 403 | `DATABRICKS_OAUTH_NOT_ENABLED` | Databricks OAuth is not on for your organization |\n| 429 | | Rate limit |\n\nThe steps are not one transaction. A later step can fail after an earlier one is saved.\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."},"delete":{"operationId":"deleteDatasource","summary":"Delete datasource","description":"Databrain removes the datasource and its tenancy settings. A datasource that a workspace or a datamart uses cannot be deleted.\n\n```bash\ncurl --request DELETE \\\n  \"https://api.usedatabrain.com/api/v2/datasource?datasourceName=Sales%20warehouse\" \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\"\n```\n\n> [!WARNING]\n> You cannot undo this. Metrics that used the datasource lose their link to it.\n\n## Auth\n\nA service token. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Datasource APIs"],"x-mint-page":"/developer-docs/helpers/api-reference/delete-datasource","x-title":"Delete a datasource","security":[{"ApiToken":[]}],"parameters":[{"name":"datasourceName","in":"query","required":true,"schema":{"type":"string"},"description":"The datasource name, exactly as saved. Encode spaces in the URL."}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"message":"Datasource deleted successfully"}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: `datasourceName` is missing\n- `DATASOURCE_NAME_ERROR`: No datasource has this name\n- `DATASOURCE_IN_USE`: A workspace or a datamart uses the datasource. Remove it from them first\n- `AUTHENTICATION_ERROR`: No `Authorization: Bearer` header, or the token is not a UUID. Send `Authorization: Bearer <token>`\n- `LICENSE_EXPIRED`: Self-hosted only: the licence key expired. Renew the licence key\n- `UNSUBSCRIBED_ACCOUNT_ERROR`: The trial ended. Choose a plan in **Settings > Billing**","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"`datasourceName` is missing"}}}}},"401":{"description":"- `AUTHENTICATION_ERROR`: The token is unknown, revoked or expired. Use a current token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"The token is unknown, revoked or expired. Use a current token"}}}}},"403":{"description":"- `AUTHENTICATION_ERROR`: A data app API token on a service-token endpoint. Use a service token\n- `TRIAL_ENDED`: The trial ended. Choose a plan in **Settings > Billing**\n- `ACCOUNT_DISABLED`: The organization is disabled or locked for deletion. Contact Databrain support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"A data app API token on a service-token endpoint. Use a service token"}}}}},"404":{"description":"- `DATASOURCE_NOT_FOUND`: The datasource was already removed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"DATASOURCE_NOT_FOUND","message":"The datasource was already removed"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: Databrain failed. Try again. If it fails again, contact support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"Databrain failed. Try again. If it fails again, contact support"}}}}},"503":{"description":"- `COMMERCIAL_UNAVAILABLE`: Databrain could not check your plan. Try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"COMMERCIAL_UNAVAILABLE","message":"Databrain could not check your plan. Try again"}}}}}},"x-mint-sections":[{"in":"parameters","heading":"Query"}],"x-mint-rest":"## Response\n\n```json\n{\n  \"message\": \"Datasource deleted successfully\"\n}\n```\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | `datasourceName` is missing |\n| 400 | `DATASOURCE_NAME_ERROR` | No datasource has this name |\n| 400 | `DATASOURCE_IN_USE` | A workspace or a datamart uses the datasource. Remove it from them first |\n| 404 | `DATASOURCE_NOT_FOUND` | The datasource was already removed |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/datasource/sync":{"post":{"operationId":"syncDatasource","summary":"Sync datasource","description":"Run it after you add tables or columns in your warehouse. For most types the call waits until the sync is done. For Amazon S3 it returns at once and you poll [the sync status](/developer-docs/helpers/api-reference/get-awss3-sync-progress-status).\n\n```bash\ncurl --request POST https://api.usedatabrain.com/api/v2/datasource/sync \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{ \"input\": { \"datasourceId\": \"6f1c2b9e-4d3a-4f8e-9b7c-2a1d0e5f6c7b\" } }'\n```\n\n## Auth\n\nA service token. See [Authentication](/developer-docs/helpers/api-reference/authentication).\n\n## Limits\n\n10 requests in 5 minutes per organization, shared with create, update and schema discovery. A large warehouse can take minutes; set a long HTTP timeout.","tags":["Datasource APIs"],"x-mint-page":"/developer-docs/helpers/api-reference/sync-datasource","x-title":"Sync a datasource","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"type":"object","properties":{"datasourceId":{"type":"string","format":"uuid","description":"The datasource `id` from [List datasources](/developer-docs/helpers/api-reference/list-datasources). Send it inside `input`"}},"required":["datasourceId"],"additionalProperties":false,"description":"Holds `datasourceId`."}},"required":["input"],"additionalProperties":false},"example":{"input":{"datasourceId":"6f1c2b9e-4d3a-4f8e-9b7c-2a1d0e5f6c7b"}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":{"error":"Schema sync already active"}}}}},"400":{"description":"- `INVALID_DATASOURCE_ID`: `input.datasourceId` is missing or not a UUID\n- `INVALID_REQUEST_BODY`: The sync failed in an unexpected way\n- `AUTHENTICATION_ERROR`: No `Authorization: Bearer` header, or the token is not a UUID. Send `Authorization: Bearer <token>`\n- `LICENSE_EXPIRED`: Self-hosted only: the licence key expired. Renew the licence key\n- `UNSUBSCRIBED_ACCOUNT_ERROR`: The trial ended. Choose a plan in **Settings > Billing**","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_DATASOURCE_ID","message":"`input.datasourceId` is missing or not a UUID"}}}}},"401":{"description":"- `AUTHENTICATION_ERROR`: The token is unknown, revoked or expired. Use a current token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"The token is unknown, revoked or expired. Use a current token"}}}}},"403":{"description":"- `AUTHENTICATION_ERROR`: A data app API token on a service-token endpoint. Use a service token\n- `TRIAL_ENDED`: The trial ended. Choose a plan in **Settings > Billing**\n- `ACCOUNT_DISABLED`: The organization is disabled or locked for deletion. Contact Databrain support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"A data app API token on a service-token endpoint. Use a service token"}}}}},"404":{"description":"- `INVALID_DATASOURCE_ID`: No datasource in your organization has this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_DATASOURCE_ID","message":"No datasource in your organization has this id"}}}}},"429":{"description":"- Too many datasource changes: at most 10 every 5 minutes. The body is plain text.\n- Rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Too many datasource changes: at most 10 every 5 minutes. The body is plain text."}}}}},"503":{"description":"- `COMMERCIAL_UNAVAILABLE`: Databrain could not check your plan. Try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"COMMERCIAL_UNAVAILABLE","message":"Databrain could not check your plan. Try again"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body"}],"x-mint-rest":"## Response\n\nThe sync is done:\n\n```json\n{ \"data\": { \"message\": \"Sync completed\" } }\n```\n\nAmazon S3, the sync started:\n\n```json\n{ \"message\": \"AWSS3 sync started..., please check the status on /api/v2/datasource/getDatasourceProgress\" }\n```\n\nThe sync failed. The status is still `200`:\n\n```json\n{ \"data\": { \"error\": \"Schema sync already active\" } }\n```\n\n## Errors\n\nThis endpoint has its own error shape:\n\n```json\n{ \"data\": { \"error\": { \"code\": \"INVALID_DATASOURCE_ID\", \"message\": \"Datasource not found\", \"status\": 404 } } }\n```\n\n| Status | `code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_DATASOURCE_ID` | `input.datasourceId` is missing or not a UUID |\n| 404 | `INVALID_DATASOURCE_ID` | No datasource in your organization has this id |\n| 400 | `INVALID_REQUEST_BODY` | The sync failed in an unexpected way |\n| 429 | | Rate limit |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/datasource/getDatasourceProgress":{"post":{"operationId":"getAwss3SyncProgressStatus","summary":"Get sync status","description":"Call it every few seconds after you [start a sync](/developer-docs/helpers/api-reference/sync-datasource) on an Amazon S3 datasource. Large syncs of other types report here too.\n\n```bash\ncurl --request POST https://api.usedatabrain.com/api/v2/datasource/getDatasourceProgress \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{ \"input\": { \"datasourceId\": \"6f1c2b9e-4d3a-4f8e-9b7c-2a1d0e5f6c7b\" } }'\n```\n\n## Auth\n\nA service token. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Datasource APIs"],"x-mint-page":"/developer-docs/helpers/api-reference/get-awss3-sync-progress-status","x-title":"Get the sync status","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"type":"object","properties":{"datasourceId":{"type":"string","description":"The datasource `id` from [List datasources](/developer-docs/helpers/api-reference/list-datasources)"}},"required":["datasourceId"],"description":"Holds `datasourceId`."}},"required":["input"]},"example":{"input":{"datasourceId":"6f1c2b9e-4d3a-4f8e-9b7c-2a1d0e5f6c7b"}}}}},"responses":{"200":{"description":"Success, or an error. This endpoint answers errors with HTTP 200 and an `error` object:\n- The id is not valid (for example, not a UUID). The answer is HTTP 200 with `error: \"something went wrong\"`.\n- `{ \"progress\": \"0/...\", \"error\": \"something went wrong\" }`: The status could not be read, for example because the id is not a UUID","content":{"application/json":{"examples":{"success":{"summary":"Success","value":{"status":{"progress":"12/40","error":""}}},"error":{"summary":"Error","value":{"error":{"code":"","message":"The id is not valid (for example, not a UUID). The answer is HTTP 200 with `error: \"something went wrong\"`."}}}}}}},"400":{"description":"- `AUTHENTICATION_ERROR`: No `Authorization: Bearer` header, or the token is not a UUID. Send `Authorization: Bearer <token>`\n- `LICENSE_EXPIRED`: Self-hosted only: the licence key expired. Renew the licence key\n- `UNSUBSCRIBED_ACCOUNT_ERROR`: The trial ended. Choose a plan in **Settings > Billing**","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"No `Authorization: Bearer` header, or the token is not a UUID. Send `Authorization: Bearer <token>`"}}}}},"401":{"description":"- `AUTHENTICATION_ERROR`: The token is unknown, revoked or expired. Use a current token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"The token is unknown, revoked or expired. Use a current token"}}}}},"403":{"description":"- `AUTHENTICATION_ERROR`: A data app API token on a service-token endpoint. Use a service token\n- `ACCOUNT_DISABLED`: The organization is disabled or locked for deletion. Contact Databrain support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"A data app API token on a service-token endpoint. Use a service token"}}}}},"404":{"description":"- `INVALID_DATASOURCE_ID`: No datasource in your organization has this id. The error is inside `data`: `{ \"data\": { \"error\": { ... } } }`.\n- `{ \"data\": { \"error\": { \"code\": \"INVALID_DATASOURCE_ID\", \"message\": \"Datasource not found\", \"status\": 404 } } }`: No datasource in your organization has this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_DATASOURCE_ID","message":"No datasource in your organization has this id. The error is inside `data`: `{ \"data\": { \"error\": { ... } } }`."}}}}}},"x-mint-sections":[{"in":"body","heading":"Body"}],"x-mint-rest":"## Response\n\n```json\n{\n  \"status\": {\n    \"progress\": \"12/40\",\n    \"error\": \"\"\n  }\n}\n```\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `status.progress` | string | Done and total, as `done/total`. `0/-1` means the sync is starting |\n| `status.error` | string | Empty while the sync runs. A message when it failed |\n\nThe status is cleared about 1 second after a sync finishes and about 5 seconds after it fails. A poll after that returns `progress` `0/...` and an empty `error`. Keep the last status you read.\n\n`status` can also have other fields, used by Databrain. Ignore them.\n\n## Errors\n\n| Status | Body | Why |\n| --- | --- | --- |\n| 404 | `{ \"data\": { \"error\": { \"code\": \"INVALID_DATASOURCE_ID\", \"message\": \"Datasource not found\", \"status\": 404 } } }` | No datasource in your organization has this id |\n| 200 | `{ \"progress\": \"0/...\", \"error\": \"something went wrong\" }` | The status could not be read, for example because the id is not a UUID |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/datasource/schema":{"get":{"operationId":"getDatasourceSchema","summary":"Get datasource schema","description":"Use it to pick the tables and columns for a [datamart](/developer-docs/helpers/api-reference/create-datamart). It reads the schema from the datasource and changes nothing.\n\n```bash\ncurl \"https://api.usedatabrain.com/api/v2/datasource/schema?datasourceName=Sales%20warehouse\" \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\"\n```\n\n## Auth\n\nA service token only. A data app API token gets `403`. See [Authentication](/developer-docs/helpers/api-reference/authentication).\n\n## Limits\n\n10 requests in 5 minutes per organization, shared with create, update and sync. The whole schema comes in one response, with no pages.","tags":["Datasource APIs"],"x-mint-page":"/developer-docs/helpers/api-reference/get-datasource-schema","x-title":"Get a datasource schema","security":[{"ServiceToken":[]}],"parameters":[{"name":"datasourceName","in":"query","required":true,"schema":{"type":"string"},"description":"The datasource name, exactly as saved."}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":{"datasourceName":"Sales warehouse","datasourceId":"6f1c2b9e-4d3a-4f8e-9b7c-2a1d0e5f6c7b","tables":[{"name":"orders","schema":"public","columns":[{"name":"id","dataType":"integer"},{"name":"created_at","dataType":"timestamp"}]}],"tableCount":1,"columnCount":2}}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: `datasourceName` is missing\n- `DATASOURCE_NAME_ERROR`: No datasource has this name, it is turned off, or its connection test failed\n- `AUTHENTICATION_ERROR`: You used a data app API token\n- `LICENSE_EXPIRED`: Self-hosted only: the licence key expired. Renew the licence key\n- `UNSUBSCRIBED_ACCOUNT_ERROR`: The trial ended. Choose a plan in **Settings > Billing**","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"`datasourceName` is missing"}}}}},"401":{"description":"- `AUTHENTICATION_ERROR`: You used a data app API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"You used a data app API token"}}}}},"403":{"description":"- `AUTHENTICATION_ERROR`: You used a data app API token\n- `ACCOUNT_DISABLED`: The organization is disabled or locked for deletion. Contact Databrain support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"You used a data app API token"}}}}},"429":{"description":"- Too many datasource requests: at most 10 every 5 minutes. The body is plain text.\n- Rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"Too many datasource requests: at most 10 every 5 minutes. The body is plain text."}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: Databrain could not read the schema","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"Databrain could not read the schema"}}}}}},"x-mint-sections":[{"in":"parameters","heading":"Query"}],"x-mint-rest":"## Response\n\n```json\n{\n  \"data\": {\n    \"datasourceName\": \"Sales warehouse\",\n    \"datasourceId\": \"6f1c2b9e-4d3a-4f8e-9b7c-2a1d0e5f6c7b\",\n    \"tables\": [\n      {\n        \"name\": \"orders\",\n        \"schema\": \"public\",\n        \"columns\": [\n          { \"name\": \"id\", \"dataType\": \"integer\" },\n          { \"name\": \"created_at\", \"dataType\": \"timestamp\" }\n        ]\n      }\n    ],\n    \"tableCount\": 1,\n    \"columnCount\": 2\n  }\n}\n```\n\nSystem schemas (`information_schema`, `pg_catalog`, `mysql`, `performance_schema`, `sys`, `system`) are left out. `dataType` is `unknown` when the datasource does not report a type. Relationships are not returned.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | `datasourceName` is missing |\n| 400 | `DATASOURCE_NAME_ERROR` | No datasource has this name, it is turned off, or its connection test failed |\n| 403 | `AUTHENTICATION_ERROR` | You used a data app API token |\n| 429 | | Rate limit |\n| 500 | `INTERNAL_SERVER_ERROR` | Databrain could not read the schema |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/data-app/datamarts":{"post":{"operationId":"createDatamart","summary":"Create datamart","description":"```bash\ncurl --request POST https://api.usedatabrain.com/api/v2/data-app/datamarts \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\n    \"name\": \"Sales\",\n    \"datasourceName\": \"Sales warehouse\",\n    \"tableList\": [\n      {\n        \"name\": \"orders\",\n        \"schemaName\": \"public\",\n        \"clientColumn\": \"customer_id\",\n        \"columns\": [\n          { \"name\": \"id\" },\n          { \"name\": \"amount\", \"allowAggregate\": true, \"defaultAggregation\": \"SUM\" },\n          { \"name\": \"created_at\", \"isApplyTimezone\": true }\n        ]\n      },\n      {\n        \"name\": \"customers\",\n        \"schemaName\": \"public\",\n        \"columns\": [{ \"name\": \"id\" }, { \"name\": \"name\" }]\n      }\n    ],\n    \"relationships\": [\n      {\n        \"relationshipName\": \"orders_customers\",\n        \"parentTableName\": \"orders\",\n        \"parentColumnName\": \"customer_id\",\n        \"childTableName\": \"customers\",\n        \"childColumnName\": \"id\",\n        \"cardinality\": \"ManyToOne\",\n        \"join\": \"LEFT JOIN\"\n      }\n    ],\n    \"tenancySettings\": {\n      \"tenancyLevel\": \"TABLE\",\n      \"clientColumnType\": \"STRING\",\n      \"schemaName\": \"public\",\n      \"tableName\": \"customers\",\n      \"tableClientNameColumn\": \"name\",\n      \"tablePrimaryKeyColumn\": \"id\"\n    }\n  }'\n```\n\n## Auth\n\nA service token. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Datamart APIs"],"x-mint-page":"/developer-docs/helpers/api-reference/create-datamart","x-title":"Create a datamart","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Datamart name, unique in your organization. Other endpoints call it `datamartName`"},"datasourceName":{"type":"string","description":"Name of a connected datasource."},"tableList":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Table name, as in the synced schema."},"schemaName":{"type":"string","description":"Schema of the table. Can be `database.schema`"},"columns":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Column name, as in the schema. Any name if `isCustomColumn` is `true`"},"alias":{"type":"string","description":"Alias."},"label":{"type":"string","description":"Display name."},"isHide":{"type":"boolean","description":"Hide the column. Default `false`"},"isCustomColumn":{"type":"boolean","description":"A calculated column. Default `false`"},"sql":{"type":"string","description":"Required with `isCustomColumn`. SQL expression of the calculated column."},"isAggregate":{"type":"boolean","description":"The expression is already an aggregate."},"isApplyTimezone":{"type":"boolean","description":"Convert this date column to the guest token's `timezone`. Default `false`"},"allowAggregate":{"type":"boolean","description":"Allow a default aggregation. A JSON boolean, not a string.","default":false},"defaultAggregation":{"type":["string","null"],"enum":["ALL","AVG","SUM","COUNT","COUNT_DISTINCT","MAX","MIN","MEDIAN","PERCENTILE_CONT","PERCENTILE_DISC","",null],"description":"`ALL`, `AVG`, `SUM`, `COUNT`, `COUNT_DISTINCT`, `MAX`, `MIN`, `MEDIAN`, `PERCENTILE_CONT` or `PERCENTILE_DISC`"},"defaultSort":{"type":["string","null"],"enum":["ASC","DESC","",null],"description":"`ASC` or `DESC`"}},"required":["name"],"additionalProperties":false},"description":"At least one column."},"clientColumn":{"type":"string","description":"The table's tenant column, for `TABLE` tenancy."},"label":{"type":"string","description":"Display name."},"isHide":{"type":"boolean","description":"Hide the table from metric builders. Default `false`"},"wildcard":{"type":"string","description":"Stored with the table."}},"required":["name","columns","schemaName"],"additionalProperties":false},"description":"At least one table."},"relationships":{"type":"array","items":{"type":"object","properties":{"relationshipName":{"type":"string","description":"Name of the join."},"parentTableName":{"type":"string","description":"One side of the join."},"parentColumnName":{"type":"string","description":"One side of the join."},"childTableName":{"type":"string","description":"The other side."},"childColumnName":{"type":"string","description":"The other side."},"cardinality":{"type":["string","null"],"enum":["ManyToMany","ManyToOne","OneToMany","OneToOne",null],"description":"`OneToOne`, `OneToMany`, `ManyToOne` or `ManyToMany`"},"join":{"type":["string","null"],"enum":["INNER JOIN","LEFT JOIN","RIGHT JOIN","FULL JOIN",null],"description":"`INNER JOIN`, `LEFT JOIN`, `RIGHT JOIN` or `FULL JOIN`"}},"required":["parentTableName","parentColumnName","childTableName","childColumnName","relationshipName"],"additionalProperties":false},"description":"Joins between the tables."},"tenancySettings":{"type":"object","properties":{"tenancyLevel":{"type":"string","enum":["TABLE","DATABASE","MULTI_DATABASE"],"description":"`TABLE` (a tenant column), `DATABASE` (a schema or database per tenant) or `MULTI_DATABASE`"},"clientColumnType":{"type":"string","enum":["NUMBER","STRING"],"description":"Required for `TABLE`. `STRING` or `NUMBER`","default":"STRING"},"schemaName":{"type":"string","description":"Required for `TABLE`. The table that lists your tenants."},"tableName":{"type":"string","description":"Required for `TABLE`. The table that lists your tenants."},"tableClientNameColumn":{"type":"string","description":"Required for `TABLE`. Column with the tenant name."},"tablePrimaryKeyColumn":{"type":"string","description":"Required for `TABLE`. Column with the tenant id, the value you send as `clientId`"},"primaryDatabase":{"type":["string","null"],"description":"Default database for `DATABASE` and `MULTI_DATABASE`"}},"required":["tenancyLevel"],"additionalProperties":false,"description":"How each customer's rows are scoped."}},"required":["name","datasourceName","tableList"],"additionalProperties":false},"example":{"name":"Sales","datasourceName":"Sales warehouse","tableList":[{"name":"orders","schemaName":"public","clientColumn":"customer_id","columns":[{"name":"id"},{"name":"amount","allowAggregate":true,"defaultAggregation":"SUM"},{"name":"created_at","isApplyTimezone":true}]},{"name":"customers","schemaName":"public","columns":[{"name":"id"},{"name":"name"}]}],"relationships":[{"relationshipName":"orders_customers","parentTableName":"orders","parentColumnName":"customer_id","childTableName":"customers","childColumnName":"id","cardinality":"ManyToOne","join":"LEFT JOIN"}],"tenancySettings":{"tenancyLevel":"TABLE","clientColumnType":"STRING","schemaName":"public","tableName":"customers","tableClientNameColumn":"name","tablePrimaryKeyColumn":"id"}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"Sales"}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: A field is missing, unknown or wrong. The name is taken. `tableList` or `columns` is empty\n- `DATASOURCE_NAME_ERROR`: No datasource has this name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"A field is missing, unknown or wrong. The name is taken. `tableList` or `columns` is empty"}}}}},"403":{"description":"- `AUTHENTICATION_ERROR`: A data app API token on a service-token endpoint. Use a service token\n- `TRIAL_ENDED`: The trial ended. Choose a plan in **Settings > Billing**","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"A data app API token on a service-token endpoint. Use a service token"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: The datamart could not be saved. Leaving out `schemaName` also ends here","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"The datamart could not be saved. Leaving out `schemaName` also ends here"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body","intro":"Unknown fields are refused. Names are case-sensitive.","after":"### tableList\n\nThe data type comes from the schema. You do not send it.\n\n### relationships\n\nRelationships are not checked against `tableList`. Check the names yourself."}],"x-mint-rest":"## Response\n\n```json\n{ \"id\": \"Sales\" }\n```\n\n`id` is the datamart name. To get its UUID, [list datamarts](/developer-docs/helpers/api-reference/list-datamarts).\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | A field is missing, unknown or wrong. The name is taken. `tableList` or `columns` is empty |\n| 400 | `INVALID_REQUEST_BODY` | A table is not in the schema. `hint` and `details.reason: \"SCHEMA_TABLE_NOT_FOUND\"` say which. Grant access to it, then [sync](/developer-docs/helpers/api-reference/sync-datasource) |\n| 400 | `INVALID_REQUEST_BODY` | A column is not in the table: `Invalid column names in table. Please verify all column names match the schema.` |\n| 400 | `DATASOURCE_NAME_ERROR` | No datasource has this name |\n| 500 | `INTERNAL_SERVER_ERROR` | The datamart could not be saved. Leaving out `schemaName` also ends here |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint).\n\nNext, [add a semantic layer](/developer-docs/helpers/api-reference/create-semantic-layer)."},"get":{"operationId":"listDatamarts","summary":"List datamarts","description":"```bash\ncurl \"https://api.usedatabrain.com/api/v2/data-app/datamarts?isPagination=true&pageNumber=1&expandDetails=false\" \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\"\n```\n\n## Auth\n\nA service token. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Datamart APIs"],"x-mint-page":"/developer-docs/helpers/api-reference/list-datamarts","x-title":"List datamarts","security":[{"ApiToken":[]}],"parameters":[{"name":"isPagination","in":"query","required":false,"schema":{"type":"string","default":"false"},"description":"`true` returns 10 datamarts per page. Without it you get all."},{"name":"pageNumber","in":"query","required":false,"schema":{"type":"integer","default":1},"description":"Page, from `1`. Used only with `isPagination=true`"},{"name":"expandDetails","in":"query","required":false,"schema":{"type":"string","default":"true"},"description":"`true` (the default) adds tables, columns and joins. Any other value leaves them out."}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"0d2e7a3c-5b1f-4c9e-8a6d-3f4b2c1e0a9d","name":"Sales","createdAt":"2026-11-02T09:14:00.000Z","updatedAt":"2026-11-18T16:40:00.000Z","companyIntegration":{"id":"6f1c2b9e-4d3a-4f8e-9b7c-2a1d0e5f6c7b","name":"Postgres"},"datamartOrganization":{"tenancyLevel":"TABLE","clientColumnType":"STRING","schemaName":"public","tableName":"customers","tableClientNameColumn":"name","tablePrimaryKeyColumn":"id","primaryDatabase":null},"datamartRelationships":[{"relationshipName":"orders_customers","parentTableName":"orders","parentColumnName":"customer_id","childTableName":"customers","childColumnName":"id","cardinality":"ManyToOne","join":"LEFT JOIN"}],"datamartTables":[{"schemaName":"public","tableName":"orders","label":"","clientColumn":"customer_id","isHide":false,"datamartTableColumns":[{"columnName":"amount","datatype":"numeric","alias":null,"label":"","isHide":false,"isCustomColumn":false,"sql":null,"isApplyTimezone":false,"allowAggregate":true,"defaultAggregation":"SUM","defaultSort":null}]}]}]}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: `pageNumber` is not a number","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"`pageNumber` is not a number"}}}}},"403":{"description":"- `AUTHENTICATION_ERROR`: A data app API token on a service-token endpoint. Use a service token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"A data app API token on a service-token endpoint. Use a service token"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: The list could not be read, for example a negative `pageNumber`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"The list could not be read, for example a negative `pageNumber`"}}}}}},"x-mint-sections":[{"in":"parameters","heading":"Query","after":"The order is not fixed and there is no total count."}],"x-mint-rest":"## Response\n\n```json\n{\n  \"data\": [\n    {\n      \"id\": \"0d2e7a3c-5b1f-4c9e-8a6d-3f4b2c1e0a9d\",\n      \"name\": \"Sales\",\n      \"createdAt\": \"2026-11-02T09:14:00.000Z\",\n      \"updatedAt\": \"2026-11-18T16:40:00.000Z\",\n      \"companyIntegration\": { \"id\": \"6f1c2b9e-4d3a-4f8e-9b7c-2a1d0e5f6c7b\", \"name\": \"Postgres\" },\n      \"datamartOrganization\": {\n        \"tenancyLevel\": \"TABLE\",\n        \"clientColumnType\": \"STRING\",\n        \"schemaName\": \"public\",\n        \"tableName\": \"customers\",\n        \"tableClientNameColumn\": \"name\",\n        \"tablePrimaryKeyColumn\": \"id\",\n        \"primaryDatabase\": null\n      },\n      \"datamartRelationships\": [\n        {\n          \"relationshipName\": \"orders_customers\",\n          \"parentTableName\": \"orders\",\n          \"parentColumnName\": \"customer_id\",\n          \"childTableName\": \"customers\",\n          \"childColumnName\": \"id\",\n          \"cardinality\": \"ManyToOne\",\n          \"join\": \"LEFT JOIN\"\n        }\n      ],\n      \"datamartTables\": [\n        {\n          \"schemaName\": \"public\",\n          \"tableName\": \"orders\",\n          \"label\": \"\",\n          \"clientColumn\": \"customer_id\",\n          \"isHide\": false,\n          \"datamartTableColumns\": [\n            {\n              \"columnName\": \"amount\",\n              \"datatype\": \"numeric\",\n              \"alias\": null,\n              \"label\": \"\",\n              \"isHide\": false,\n              \"isCustomColumn\": false,\n              \"sql\": null,\n              \"isApplyTimezone\": false,\n              \"allowAggregate\": true,\n              \"defaultAggregation\": \"SUM\",\n              \"defaultSort\": null\n            }\n          ]\n        }\n      ]\n    }\n  ]\n}\n```\n\n| Field | Description |\n| --- | --- |\n| `id` | The datamart UUID |\n| `name` | The datamart name. Use it as `datamartName` |\n| `companyIntegration.id` | The datasource id |\n| `companyIntegration.name` | The datasource type, for example `Postgres`. Not your datasource name |\n| `datamartOrganization` | The tenancy, or `null` when the datamart has none |\n| `datamartRelationships`, `datamartTables` | Only with `expandDetails` on. Same fields as [create](/developer-docs/helpers/api-reference/create-datamart) |\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | `pageNumber` is not a number |\n| 500 | `INTERNAL_SERVER_ERROR` | The list could not be read, for example a negative `pageNumber` |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."},"put":{"operationId":"updateDatamart","summary":"Update datamart","description":"```bash\ncurl --request PUT https://api.usedatabrain.com/api/v2/data-app/datamarts \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\n    \"datamartName\": \"Sales\",\n    \"tenancySettings\": { \"tenancyLevel\": \"DATABASE\", \"primaryDatabase\": \"tenant_default\" }\n  }'\n```\n\n## Auth\n\nA service token. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Datamart APIs"],"x-mint-page":"/developer-docs/helpers/api-reference/update-datamart","x-title":"Update a datamart","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datamartName":{"type":"string","description":"Picks the datamart. You cannot rename it."},"tableList":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Table name, as in the synced schema."},"schemaName":{"type":"string","description":"Schema of the table. Can be `database.schema`"},"columns":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Column name, as in the schema. Any name if `isCustomColumn` is `true`"},"alias":{"type":"string","description":"Alias."},"label":{"type":"string","description":"Display name."},"isHide":{"type":"boolean","description":"Hide the column. Default `false`"},"isCustomColumn":{"type":"boolean","description":"A calculated column. Default `false`"},"sql":{"type":"string","description":"Required with `isCustomColumn`. SQL expression of the calculated column."},"isAggregate":{"type":"boolean","description":"The expression is already an aggregate."},"isApplyTimezone":{"type":"boolean","description":"Convert this date column to the guest token's `timezone`. Default `false`"},"allowAggregate":{"type":["boolean","null"],"description":"Allow a default aggregation. A JSON boolean, not a string."},"defaultAggregation":{"type":["string","null"],"enum":["ALL","AVG","SUM","COUNT","COUNT_DISTINCT","MAX","MIN","MEDIAN","PERCENTILE_CONT","PERCENTILE_DISC","",null],"description":"`ALL`, `AVG`, `SUM`, `COUNT`, `COUNT_DISTINCT`, `MAX`, `MIN`, `MEDIAN`, `PERCENTILE_CONT` or `PERCENTILE_DISC`"},"defaultSort":{"type":["string","null"],"enum":["ASC","DESC","",null],"description":"`ASC` or `DESC`"}},"required":["name"],"additionalProperties":false},"description":"At least one column."},"clientColumn":{"type":"string","description":"The table's tenant column, for `TABLE` tenancy."},"label":{"type":"string","description":"Display name."},"isHide":{"type":"boolean","description":"Hide the table from metric builders. Default `false`"},"wildcard":{"type":"string","description":"Stored with the table."}},"required":["name","columns","schemaName"],"additionalProperties":false},"description":"Replaces all tables and columns. Leave it out to keep them. `[]` removes them all."},"relationships":{"type":"array","items":{"type":"object","properties":{"relationshipName":{"type":"string","description":"Name of the join."},"parentTableName":{"type":"string","description":"One side of the join."},"parentColumnName":{"type":"string","description":"One side of the join."},"childTableName":{"type":"string","description":"The other side."},"childColumnName":{"type":"string","description":"The other side."},"cardinality":{"type":["string","null"],"enum":["ManyToMany","ManyToOne","OneToMany","OneToOne",null],"description":"`OneToOne`, `OneToMany`, `ManyToOne` or `ManyToMany`"},"join":{"type":["string","null"],"enum":["INNER JOIN","LEFT JOIN","RIGHT JOIN","FULL JOIN",null],"description":"`INNER JOIN`, `LEFT JOIN`, `RIGHT JOIN` or `FULL JOIN`"}},"required":["parentTableName","parentColumnName","childTableName","childColumnName","relationshipName"],"additionalProperties":false},"description":"A non-empty list replaces all joins. Leave it out or send `[]` to keep them."},"tenancySettings":{"type":"object","properties":{"tenancyLevel":{"type":"string","enum":["TABLE","DATABASE","MULTI_DATABASE"],"description":"`TABLE` (a tenant column), `DATABASE` (a schema or database per tenant) or `MULTI_DATABASE`"},"clientColumnType":{"type":"string","enum":["NUMBER","STRING"],"description":"Required for `TABLE`. `STRING` or `NUMBER`"},"schemaName":{"type":"string","description":"Required for `TABLE`. The table that lists your tenants."},"tableName":{"type":"string","description":"Required for `TABLE`. The table that lists your tenants."},"tableClientNameColumn":{"type":"string","description":"Required for `TABLE`. Column with the tenant name."},"tablePrimaryKeyColumn":{"type":"string","description":"Required for `TABLE`. Column with the tenant id, the value you send as `clientId`"},"primaryDatabase":{"type":"string","description":"Default database for `DATABASE` and `MULTI_DATABASE`"}},"additionalProperties":false,"description":"Changes the fields you send."}},"required":["datamartName"],"additionalProperties":false},"example":{"datamartName":"Sales","tenancySettings":{"tenancyLevel":"DATABASE","primaryDatabase":"tenant_default"}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"Sales","warnings":["Kept the client column of 2 embed or data app setting(s) (orders): the datamart table has no client column, so it is their live client filter."]}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: A field is missing, unknown or wrong, or a table or column is not in the schema\n- `INVALID_DATAMART`: No datamart has this name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"A field is missing, unknown or wrong, or a table or column is not in the schema"}}}}},"403":{"description":"- `AUTHENTICATION_ERROR`: A data app API token on a service-token endpoint. Use a service token\n- `TRIAL_ENDED`: The trial ended. Choose a plan in **Settings > Billing**","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"A data app API token on a service-token endpoint. Use a service token"}}}}},"409":{"description":"- `LAYER_MANAGED_BY_V2`: The joins of this datamart belong to its semantic model. Edit them in the app","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"LAYER_MANAGED_BY_V2","message":"The joins of this datamart belong to its semantic model. Edit them in the app"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: The datamart could not be updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"The datamart could not be updated"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body","intro":"The fields have the same shape and values as [Create a datamart](/developer-docs/helpers/api-reference/create-datamart#body).","after":"> [!WARNING]\n> On a datamart without a semantic model, sending `tableList` deletes the semantic layer text (descriptions, synonyms, column types) of every table. Send it again with [Update a semantic layer](/developer-docs/helpers/api-reference/update-semantic-layer).\n\nTenancy rules:\n\n- A field you leave out, or send as `\"\"` or `null`, keeps its saved value.\n- With `tenancyLevel` `TABLE`, also send `clientColumnType`, `schemaName`, `tableName`, `tableClientNameColumn` and `tablePrimaryKeyColumn`.\n- `primaryDatabase` is kept only when this request sets `tenancyLevel` to `DATABASE` or `MULTI_DATABASE`. Otherwise it is cleared.\n\nWhen a table loses its tenant column, Databrain keeps that column on the data apps and embeds that use it, and says so in `warnings`."}],"x-mint-rest":"## Response\n\n```json\n{\n  \"id\": \"Sales\",\n  \"warnings\": [\n    \"Kept the client column of 2 embed or data app setting(s) (orders): the datamart table has no client column, so it is their live client filter.\"\n  ]\n}\n```\n\n`id` is the datamart name. `warnings` is there only when it has items.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | A field is missing, unknown or wrong, or a table or column is not in the schema |\n| 400 | `INVALID_DATAMART` | No datamart has this name |\n| 409 | `LAYER_MANAGED_BY_V2` | The joins of this datamart belong to its semantic model. Edit them in the app |\n| 500 | `INTERNAL_SERVER_ERROR` | The datamart could not be updated |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/data-app/datamart":{"delete":{"operationId":"deleteDatamart","summary":"Delete datamart","description":"Databrain refuses the delete while a workspace, embed, data app, metric or dashboard uses the datamart. It never deletes those for you. The path is singular: `/datamart`.\n\n```bash\ncurl --request DELETE \\\n  \"https://api.usedatabrain.com/api/v2/data-app/datamart?datamartName=Sales\" \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\"\n```\n\n> [!WARNING]\n> You cannot undo this.\n\n## Auth\n\nA service token. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Datamart APIs"],"x-mint-page":"/developer-docs/helpers/api-reference/delete-datamart","x-title":"Delete a datamart","security":[{"ApiToken":[]}],"parameters":[{"name":"datamartName","in":"query","required":true,"schema":{"type":"string"},"description":"The datamart name."}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"Sales"}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: `datamartName` is missing\n- `INVALID_DATAMART`: No datamart has this name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"`datamartName` is missing"}}}}},"403":{"description":"- `AUTHENTICATION_ERROR`: A data app API token on a service-token endpoint. Use a service token\n- `TRIAL_ENDED`: The trial ended. Choose a plan in **Settings > Billing**","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"A data app API token on a service-token endpoint. Use a service token"}}}}},"404":{"description":"- `INVALID_REQUEST_BODY`: `datamartName` is missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"`datamartName` is missing"}}}}},"409":{"description":"- `INVALID_REQUEST_BODY`: Something else uses it: `This model is still referenced. Remove its references before deleting it.` Or it changed during the check: try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"Something else uses it: `This model is still referenced. Remove its references before deleting it.` Or it changed during the check: try again"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: Databrain failed. Try again. If it fails again, contact support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"Databrain failed. Try again. If it fails again, contact support"}}}}},"504":{"description":"- `INVALID_REQUEST_BODY`: The check took too long. Nothing was deleted. Try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"The check took too long. Nothing was deleted. Try again"}}}}}},"x-mint-sections":[{"in":"parameters","heading":"Query"}],"x-mint-rest":"## Response\n\n```json\n{ \"id\": \"Sales\" }\n```\n\n`id` is the name of the deleted datamart.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | `datamartName` is missing |\n| 400 | `INVALID_DATAMART` | No datamart has this name |\n| 400 | `INVALID_REQUEST_BODY` | A workspace or embed uses it. The message names them: `datamart is connected with following workspace(...) or embed(...) please disconnect to proceed` |\n| 409 | `INVALID_REQUEST_BODY` | Something else uses it: `This model is still referenced. Remove its references before deleting it.` Or it changed during the check: try again |\n| 504 | `INVALID_REQUEST_BODY` | The check took too long. Nothing was deleted. Try again |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/data-app/datamarts/semantic-layer":{"get":{"operationId":"getSemanticLayer","summary":"Get semantic layer","description":"```bash\ncurl \"https://api.usedatabrain.com/api/v2/data-app/datamarts/semantic-layer?datamartName=Sales\" \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\"\n```\n\n## Auth\n\nA service token only. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Semantic Layer APIs"],"x-mint-page":"/developer-docs/helpers/api-reference/get-semantic-layer","x-title":"Get a semantic layer","security":[{"ServiceToken":[]}],"parameters":[{"name":"datamartName","in":"query","required":true,"schema":{"type":"string"},"description":"The datamart."}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":{"datamartName":"Sales","tables":[{"name":"orders","schemaName":"public","description":"One row per order.","synonyms":["purchases","sales"],"miscellaneousInfo":null,"columns":[{"name":"status","datatype":"varchar","description":null,"synonyms":[],"miscellaneousInfo":null,"columnType":"ENUM","columnTypeConfig":{"paid":"Payment received"},"isIdentifier":false,"isNotIndexed":false}]}],"feedback":"Revenue means the sum of paid orders.","completionScore":40,"lastUpdated":"2026-11-18T16:40:00.000Z"}}}}},"400":{"description":"- `INVALID_DATAMART`: `datamartName` is missing, or no datamart has this name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_DATAMART","message":"`datamartName` is missing, or no datamart has this name"}}}}},"403":{"description":"- `AUTHENTICATION_ERROR`: You used a data app API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"You used a data app API token"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: Databrain failed. Try again. If it fails again, contact support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"Databrain failed. Try again. If it fails again, contact support"}}}}}},"x-mint-sections":[{"in":"parameters","heading":"Query"}],"x-mint-rest":"## Response\n\n```json\n{\n  \"data\": {\n    \"datamartName\": \"Sales\",\n    \"tables\": [\n      {\n        \"name\": \"orders\",\n        \"schemaName\": \"public\",\n        \"description\": \"One row per order.\",\n        \"synonyms\": [\"purchases\", \"sales\"],\n        \"miscellaneousInfo\": null,\n        \"columns\": [\n          {\n            \"name\": \"status\",\n            \"datatype\": \"varchar\",\n            \"description\": null,\n            \"synonyms\": [],\n            \"miscellaneousInfo\": null,\n            \"columnType\": \"ENUM\",\n            \"columnTypeConfig\": { \"paid\": \"Payment received\" },\n            \"isIdentifier\": false,\n            \"isNotIndexed\": false\n          }\n        ]\n      }\n    ],\n    \"feedback\": \"Revenue means the sum of paid orders.\",\n    \"completionScore\": 40,\n    \"lastUpdated\": \"2026-11-18T16:40:00.000Z\"\n  }\n}\n```\n\n| Field | Description |\n| --- | --- |\n| `tables` | Every table of the datamart, also those with no text yet |\n| `feedback` | The note on the datamart, or `null` |\n| `completionScore` | 0 to 100: how many tables and columns have a description, synonyms and a column type |\n| `lastUpdated` | When the layer last changed, or `null` |\n\nThe fields of a table and a column are the ones on [create](/developer-docs/helpers/api-reference/create-semantic-layer#body), plus the column's `datatype`.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_DATAMART` | `datamartName` is missing, or no datamart has this name |\n| 403 | `AUTHENTICATION_ERROR` | You used a data app API token |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."},"post":{"operationId":"createSemanticLayer","summary":"Create semantic layer","description":"Use it once per datamart. To change it later, use [Update a semantic layer](/developer-docs/helpers/api-reference/update-semantic-layer).\n\n```bash\ncurl --request POST https://api.usedatabrain.com/api/v2/data-app/datamarts/semantic-layer \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\n    \"datamartName\": \"Sales\",\n    \"tables\": [\n      {\n        \"name\": \"orders\",\n        \"description\": \"One row per order.\",\n        \"synonyms\": [\"purchases\", \"sales\"],\n        \"columns\": [\n          { \"name\": \"amount\", \"description\": \"Order total in USD.\", \"columnType\": \"Number\" },\n          {\n            \"name\": \"status\",\n            \"columnType\": \"ENUM\",\n            \"columnTypeConfig\": { \"paid\": \"Payment received\", \"refunded\": \"Money returned\" }\n          },\n          { \"name\": \"id\", \"columnType\": \"Identifier\", \"isIdentifier\": true }\n        ]\n      }\n    ],\n    \"feedback\": \"Revenue means the sum of paid orders.\"\n  }'\n```\n\n## Auth\n\nA service token only. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Semantic Layer APIs"],"x-mint-page":"/developer-docs/helpers/api-reference/create-semantic-layer","x-title":"Create a semantic layer","security":[{"ServiceToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datamartName":{"type":"string","description":"The datamart."},"tables":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"A table of the datamart."},"description":{"type":["string","null"],"maxLength":500,"description":"Limit: 500 characters. What the table holds."},"synonyms":{"type":"array","maxItems":10,"items":{"type":"string","maxLength":100},"description":"Limit: 10 items, 100 characters each, no duplicates. Other words for the table."},"miscellaneousInfo":{"type":["string","null"],"maxLength":1000,"description":"Limit: 1,000 characters. Other notes."},"columns":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"A column of that table."},"description":{"type":["string","null"],"maxLength":500,"description":"Limit: 500 characters. What the column holds."},"synonyms":{"type":"array","maxItems":10,"items":{"type":"string","maxLength":100},"description":"Limit: 10 items, 100 characters each, no duplicates. Other words for the column."},"miscellaneousInfo":{"type":["string","null"],"maxLength":1000,"description":"Limit: 1,000 characters. Other notes."},"columnType":{"type":"string","enum":["String","Long String","String (Custom)","ENUM","Mapper","Range","Expression","Identifier","Number","JSON"],"description":"Limit: See below. The kind of value."},"columnTypeConfig":{"description":"Limit: See below. Values for the column type. Send `columnType` with it.","type":"object"},"isIdentifier":{"type":"boolean","description":"The column identifies a row."},"isNotIndexed":{"type":"boolean","description":"Do not give this column's `ENUM` values to Bryn."}},"required":["name"],"additionalProperties":false},"description":"Text per column."},"schemaName":{"type":["string","null"],"description":"Accepted and ignored. Tables are matched by name."}},"required":["name"],"additionalProperties":false},"description":"Send this or the other one of the pair. Text per table."},"feedback":{"type":["string","null"],"maxLength":2000,"description":"Send this or the other one of the pair. Limit: 2,000 characters. A note on the whole datamart."}},"required":["datamartName"],"additionalProperties":false,"anyOf":[{"required":["tables"]},{"required":["feedback"]}]},"example":{"datamartName":"Sales","tables":[{"name":"orders","description":"One row per order.","synonyms":["purchases","sales"],"columns":[{"name":"amount","description":"Order total in USD.","columnType":"Number"},{"name":"status","columnType":"ENUM","columnTypeConfig":{"paid":"Payment received","refunded":"Money returned"}},{"name":"id","columnType":"Identifier","isIdentifier":true}]}],"feedback":"Revenue means the sum of paid orders."}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"Sales"}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: A field is missing, unknown or too long, or neither `tables` nor `feedback` was sent\n- `INVALID_DATAMART`: No datamart has this name\n- `INVALID_TABLE`: `Table '<table>' not found in datamart '<datamart>'`\n- `INVALID_COLUMN`: `Column '<column>' not found in table '<table>'`\n- `INVALID_COLUMN_TYPE`: The column type does not fit the column's data type\n- `INVALID_COLUMN_TYPE_CONFIG`: `columnTypeConfig` has the wrong shape, or `columnType` is missing\n- `DUPLICATE_SYNONYM`: The same synonym is in a list twice, in any letter case","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"A field is missing, unknown or too long, or neither `tables` nor `feedback` was sent"}}}}},"403":{"description":"- `AUTHENTICATION_ERROR`: You used a data app API token\n- `TRIAL_ENDED`: The trial ended. Choose a plan in **Settings > Billing**","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"You used a data app API token"}}}}},"409":{"description":"- `LAYER_MANAGED_BY_V2`: The datamart belongs to a semantic model. Edit it in the app\n- `SEMANTIC_LAYER_ALREADY_EXISTS`: The datamart already has a semantic layer. Use PUT","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"LAYER_MANAGED_BY_V2","message":"The datamart belongs to a semantic model. Edit it in the app"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: Databrain failed. Try again. If it fails again, contact support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"Databrain failed. Try again. If it fails again, contact support"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body","intro":"Send `datamartName` and at least one of `tables` or `feedback`. Unknown fields are refused.","after":"### Column types\n\n| `columnType` | Column data type | `columnTypeConfig` |\n| --- | --- | --- |\n| `String`, `Long String`, `String (Custom)`, `ENUM`, `Mapper` | Text (`varchar`, `text`, `char`, `string`, `nvarchar` and the like) | `String`, `String (Custom)`, `ENUM`, `Mapper`: an object of value to description, for example `{ \"paid\": \"Payment received\" }`. `Long String`: none |\n| `Number` | Numeric (`int`, `bigint`, `decimal`, `numeric`, `float`, `double` and the like) | None |\n| `Range` | Numeric | `{ \"lowerLimit\": 0, \"upperLimit\": 100 }` |\n| `JSON` | `json` or `jsonb` | A sample JSON as a string |\n| `Expression` | Any | A string template |\n| `Identifier` | Any | None |"}],"x-mint-rest":"## Response\n\n```json\n{ \"id\": \"Sales\" }\n```\n\n`id` is the datamart name. Databrain also updates the datamart's completion score. See [Get a semantic layer](/developer-docs/helpers/api-reference/get-semantic-layer).\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | A field is missing, unknown or too long, or neither `tables` nor `feedback` was sent |\n| 400 | `INVALID_DATAMART` | No datamart has this name |\n| 400 | `INVALID_TABLE` | `Table '<table>' not found in datamart '<datamart>'` |\n| 400 | `INVALID_COLUMN` | `Column '<column>' not found in table '<table>'` |\n| 400 | `INVALID_COLUMN_TYPE` | The column type does not fit the column's data type |\n| 400 | `INVALID_COLUMN_TYPE_CONFIG` | `columnTypeConfig` has the wrong shape, or `columnType` is missing |\n| 400 | `DUPLICATE_SYNONYM` | The same synonym is in a list twice, in any letter case |\n| 403 | `AUTHENTICATION_ERROR` | You used a data app API token |\n| 409 | `SEMANTIC_LAYER_ALREADY_EXISTS` | The datamart already has a semantic layer. Use PUT |\n| 409 | `LAYER_MANAGED_BY_V2` | The datamart belongs to a semantic model. Edit it in the app |\n\nTables and columns are saved one at a time. If a call fails part way, read the layer with GET before you try again.\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."},"put":{"operationId":"updateSemanticLayer","summary":"Update semantic layer","description":"Only the fields you send change. Everything else stays.\n\n```bash\ncurl --request PUT https://api.usedatabrain.com/api/v2/data-app/datamarts/semantic-layer \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\n    \"datamartName\": \"Sales\",\n    \"tables\": [\n      {\n        \"name\": \"orders\",\n        \"synonyms\": [],\n        \"columns\": [{ \"name\": \"amount\", \"description\": \"Order total in USD, after discounts.\" }]\n      }\n    ]\n  }'\n```\n\n## Auth\n\nA service token only. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Semantic Layer APIs"],"x-mint-page":"/developer-docs/helpers/api-reference/update-semantic-layer","x-title":"Update a semantic layer","security":[{"ServiceToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datamartName":{"type":"string","description":"The datamart."},"tables":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"A table of the datamart."},"description":{"type":["string","null"],"maxLength":500,"description":"Limit: 500 characters. What the table holds."},"synonyms":{"type":"array","maxItems":10,"items":{"type":"string","maxLength":100},"description":"Limit: 10 items, 100 characters each, no duplicates. Other words for the table."},"miscellaneousInfo":{"type":["string","null"],"maxLength":1000,"description":"Limit: 1,000 characters. Other notes."},"columns":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"A column of that table."},"description":{"type":["string","null"],"maxLength":500,"description":"Limit: 500 characters. What the column holds."},"synonyms":{"type":"array","maxItems":10,"items":{"type":"string","maxLength":100},"description":"Limit: 10 items, 100 characters each, no duplicates. Other words for the column."},"miscellaneousInfo":{"type":["string","null"],"maxLength":1000,"description":"Limit: 1,000 characters. Other notes."},"columnType":{"type":"string","enum":["String","Long String","String (Custom)","ENUM","Mapper","Range","Expression","Identifier","Number","JSON"],"description":"Limit: See below. The kind of value."},"columnTypeConfig":{"description":"Limit: See below. Values for the column type. Send `columnType` with it.","type":"object"},"isIdentifier":{"type":"boolean","description":"The column identifies a row."},"isNotIndexed":{"type":"boolean","description":"Do not give this column's `ENUM` values to Bryn."}},"required":["name"],"additionalProperties":false},"description":"Text per column."},"schemaName":{"type":["string","null"],"description":"Accepted and ignored. Tables are matched by name."}},"required":["name"],"additionalProperties":false},"description":"Send this or the other one of the pair. Text per table."},"feedback":{"type":"string","maxLength":2000,"description":"Send this or the other one of the pair. Limit: 2,000 characters. A note on the whole datamart."}},"required":["datamartName"],"additionalProperties":false,"anyOf":[{"required":["tables"]},{"required":["feedback"]}]},"example":{"datamartName":"Sales","tables":[{"name":"orders","synonyms":[],"columns":[{"name":"amount","description":"Order total in USD, after discounts."}]}]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"Sales"}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: A field is wrong, or you sent neither `tables` nor `feedback`.\n- `INVALID_DATAMART`: No datamart has this name.\n- `INVALID_TABLE`: The table is not in the datamart.\n- `INVALID_COLUMN`: The column is not in that table.\n- `INVALID_COLUMN_TYPE`: The `columnType` does not fit the column's data type.\n- `INVALID_COLUMN_TYPE_CONFIG`: `columnTypeConfig` has the wrong shape, or `columnType` is missing.\n- `DUPLICATE_SYNONYM`: The same synonym is in one list twice (case does not matter).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"A field is wrong, or you sent neither `tables` nor `feedback`."}}}}},"403":{"description":"- `AUTHENTICATION_ERROR`: A data app API token on a service-token endpoint. Use a service token\n- `TRIAL_ENDED`: The trial ended. Choose a plan in **Settings > Billing**","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"A data app API token on a service-token endpoint. Use a service token"}}}}},"404":{"description":"- `SEMANTIC_LAYER_NOT_FOUND`: `No semantic layer found for datamart '<name>'. Use POST to create first.`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"SEMANTIC_LAYER_NOT_FOUND","message":"`No semantic layer found for datamart '<name>'. Use POST to create first.`"}}}}},"409":{"description":"- `LAYER_MANAGED_BY_V2`: The datamart's semantic layer is edited in the new semantic model editor, not with this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"LAYER_MANAGED_BY_V2","message":"The datamart's semantic layer is edited in the new semantic model editor, not with this API."}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: Databrain failed. Try again. If it fails again, contact support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"Databrain failed. Try again. If it fails again, contact support"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body","intro":"The fields, limits and column types are the same as [Create a semantic layer](/developer-docs/helpers/api-reference/create-semantic-layer#body). Send `datamartName` and at least one of `tables` or `feedback`.\n\n| You send | It does |\n| --- | --- |\n| A field with a value | Replaces that field |\n| A field as `null` or `\"\"` | Clears it |\n| `synonyms: []` | Clears the synonyms |\n| `feedback` | Replaces the note. `null` or `\"\"` removes it |\n| A field left out | Keeps it |\n| `tables: []` or `columns: []` | Changes nothing |"}],"x-mint-rest":"## Response\n\n```json\n{ \"id\": \"Sales\" }\n```\n\n## Errors\n\nThe errors are the same as on [create](/developer-docs/helpers/api-reference/create-semantic-layer#errors), but instead of `SEMANTIC_LAYER_ALREADY_EXISTS`:\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 404 | `SEMANTIC_LAYER_NOT_FOUND` | `No semantic layer found for datamart '<name>'. Use POST to create first.` |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."},"delete":{"operationId":"deleteSemanticLayer","summary":"Delete semantic layer","description":"The datamart, its tables, columns and joins stay. Only the semantic text goes, and the completion score becomes `0`.\n\n```bash\ncurl --request DELETE \\\n  \"https://api.usedatabrain.com/api/v2/data-app/datamarts/semantic-layer?datamartName=Sales\" \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\"\n```\n\n> [!WARNING]\n> You cannot undo this. Read the layer with [GET](/developer-docs/helpers/api-reference/get-semantic-layer) first if you want to keep a copy.\n\n## Auth\n\nA service token only. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Semantic Layer APIs"],"x-mint-page":"/developer-docs/helpers/api-reference/delete-semantic-layer","x-title":"Delete a semantic layer","security":[{"ServiceToken":[]}],"parameters":[{"name":"datamartName","in":"query","required":true,"schema":{"type":"string"},"description":"The datamart."}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"Sales"}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: `datamartName` is missing\n- `INVALID_DATAMART`: No datamart has this name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"`datamartName` is missing"}}}}},"403":{"description":"- `AUTHENTICATION_ERROR`: You used a data app API token\n- `TRIAL_ENDED`: The trial ended. Choose a plan in **Settings > Billing**","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"You used a data app API token"}}}}},"404":{"description":"- `SEMANTIC_LAYER_NOT_FOUND`: The datamart has no semantic layer, or you already deleted it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"SEMANTIC_LAYER_NOT_FOUND","message":"The datamart has no semantic layer, or you already deleted it"}}}}},"409":{"description":"- `LAYER_MANAGED_BY_V2`: The datamart belongs to a semantic model. Edit it in the app","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"LAYER_MANAGED_BY_V2","message":"The datamart belongs to a semantic model. Edit it in the app"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: Databrain failed. Try again. If it fails again, contact support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"Databrain failed. Try again. If it fails again, contact support"}}}}}},"x-mint-sections":[{"in":"parameters","heading":"Query"}],"x-mint-rest":"## Response\n\n```json\n{ \"id\": \"Sales\" }\n```\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | `datamartName` is missing |\n| 400 | `INVALID_DATAMART` | No datamart has this name |\n| 403 | `AUTHENTICATION_ERROR` | You used a data app API token |\n| 404 | `SEMANTIC_LAYER_NOT_FOUND` | The datamart has no semantic layer, or you already deleted it |\n| 409 | `LAYER_MANAGED_BY_V2` | The datamart belongs to a semantic model. Edit it in the app |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/workspace":{"post":{"operationId":"createWorkspace","summary":"Create workspace","description":"```bash\ncurl --request POST https://api.usedatabrain.com/api/v2/workspace \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\n    \"name\": \"Customer analytics\",\n    \"connectionType\": \"DATAMART\",\n    \"datamartName\": \"Sales\"\n  }'\n```\n\n## Auth\n\nA service token. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Workspace APIs"],"x-mint-page":"/developer-docs/helpers/api-reference/create-workspace","x-title":"Create a workspace","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Up to 100 characters, unique in your organization. You cannot rename it with the API."},"connectionType":{"type":"string","enum":["DATAMART","DATASOURCE","MULTI_DATASOURCE","MULTI_DATAMART"],"description":"`DATASOURCE`, `DATAMART`, `MULTI_DATASOURCE` or `MULTI_DATAMART`"},"datasourceName":{"type":"string","description":"Required for `DATASOURCE`. The datasource name. Ignored for other types."},"datamartName":{"type":"string","description":"Required for `DATAMART`. The datamart name. Ignored for other types."},"llmName":{"type":"string","description":"Name of an LLM in **Settings > LLMs**."},"aiCopilotLlms":{"type":"array","items":{"type":"string"},"description":"Names of the LLMs for the AI copilot."},"isEnableMetricSuggestions":{"type":"boolean","description":"Suggest metrics. Default `false`","default":false},"isEnableMetricSummary":{"type":"boolean","description":"AI summaries on metrics. Default `false`","default":false},"summaryType":{"type":"string","enum":["technicalAndInsightSummary","forecastAndTrendAnalysis","comparativeAndAnomalyDetection","custom"],"description":"Required with `isEnableMetricSummary`. `technicalAndInsightSummary`, `forecastAndTrendAnalysis`, `comparativeAndAnomalyDetection` or `custom`"},"customSummaryPrompt":{"type":"string","description":"Required with `summaryType: custom`. Your summary prompt.","default":""},"themeName":{"type":"string","description":"Name of a theme in **Settings > UI Theming**."}},"required":["name","connectionType"],"additionalProperties":false},"example":{"name":"Customer analytics","connectionType":"DATAMART","datamartName":"Sales"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":{"name":"Customer analytics"}}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: A field is missing, unknown or wrong\n- `WORKSPACE_NAME_ALREADY_EXISTS`: The name is taken\n- `INVALID_DATASOURCE_NAME`: No datasource has this name\n- `INVALID_DATAMART_NAME`: No datamart has this name\n- `INVALID_LLM_NAME`: No LLM has this name\n- `INVALID_AI_COPILOT_LLMS`: One of the `aiCopilotLlms` names is unknown\n- `WORKSPACE_NAME_TOO_LONG`: The name is over 100 characters\n- `INVALID_THEME_NAME`: No theme has this name. The workspace was still created: set the theme with [update](/developer-docs/helpers/api-reference/update-workspace)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"A field is missing, unknown or wrong"}}}}},"403":{"description":"- `AUTHENTICATION_ERROR`: A data app API token on a service-token endpoint. Use a service token\n- `TRIAL_ENDED`: The trial ended. Choose a plan in **Settings > Billing**","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"A data app API token on a service-token endpoint. Use a service token"}}}}},"409":{"description":"- `limit_reached`: Your plan's workspace limit is used. The body has `limit`, `used`, `max`, `currentPlan` and `requiredPlan`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"limit_reached","message":"Your plan's workspace limit is used. The body has `limit`, `used`, `max`, `currentPlan` and `requiredPlan`"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: Databrain failed. Try again. If it fails again, contact support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"Databrain failed. Try again. If it fails again, contact support"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body","intro":"Unknown fields are refused. Names are matched exactly, with capital letters.","after":"`MULTI_DATASOURCE` and `MULTI_DATAMART` workspaces have no fixed connection. Each guest token picks one with `datasourceName` or `datamartName`."}],"x-mint-rest":"## Response\n\n```json\n{ \"data\": { \"name\": \"Customer analytics\" } }\n```\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | A field is missing, unknown or wrong |\n| 400 | `WORKSPACE_NAME_ALREADY_EXISTS` | The name is taken |\n| 400 | `WORKSPACE_NAME_TOO_LONG` | The name is over 100 characters |\n| 400 | `INVALID_DATASOURCE_NAME` | No datasource has this name |\n| 400 | `INVALID_DATAMART_NAME` | No datamart has this name |\n| 400 | `INVALID_LLM_NAME` | No LLM has this name |\n| 400 | `INVALID_AI_COPILOT_LLMS` | One of the `aiCopilotLlms` names is unknown |\n| 400 | `INVALID_THEME_NAME` | No theme has this name. The workspace was still created: set the theme with [update](/developer-docs/helpers/api-reference/update-workspace) |\n| 409 | `limit_reached` | Your plan's workspace limit is used. The body has `limit`, `used`, `max`, `currentPlan` and `requiredPlan` |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint).\n\nNext, [create a data app](/developer-docs/helpers/api-reference/create-data-app)."},"get":{"operationId":"listWorkspaces","summary":"List workspaces","description":"The list has every workspace of your organization, also private ones made in the app.\n\n```bash\ncurl \"https://api.usedatabrain.com/api/v2/workspace?isPagination=true&pageNumber=1\" \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\"\n```\n\n## Auth\n\nA service token. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Workspace APIs"],"x-mint-page":"/developer-docs/helpers/api-reference/list-workspaces","x-title":"List workspaces","security":[{"ApiToken":[]}],"parameters":[{"name":"isPagination","in":"query","required":false,"schema":{"type":"string"},"description":"`true` returns 10 workspaces per page. Without it you get all."},{"name":"pageNumber","in":"query","required":false,"schema":{"type":"integer"},"description":"Page, from `1`. Used only with `isPagination=true`"}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"name":"Customer analytics","id":"9a7c1e2b-3d4f-4a5b-8c6d-7e8f9a0b1c2d","dataMartId":"0d2e7a3c-5b1f-4c9e-8a6d-3f4b2c1e0a9d","isMultiDatasource":false,"isMultiDatamart":false,"companyIntegration":null,"datamart":{"id":"0d2e7a3c-5b1f-4c9e-8a6d-3f4b2c1e0a9d","name":"Sales"}}]}}}},"403":{"description":"- `AUTHENTICATION_ERROR`: A data app API token on a service-token endpoint. Use a service token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"A data app API token on a service-token endpoint. Use a service token"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: The list could not be read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"The list could not be read"}}}}}},"x-mint-sections":[{"in":"parameters","heading":"Query","after":"The order is not fixed and there is no total count."}],"x-mint-rest":"## Response\n\n```json\n{\n  \"data\": [\n    {\n      \"id\": \"9a7c1e2b-3d4f-4a5b-8c6d-7e8f9a0b1c2d\",\n      \"name\": \"Customer analytics\",\n      \"dataMartId\": \"0d2e7a3c-5b1f-4c9e-8a6d-3f4b2c1e0a9d\",\n      \"isMultiDatasource\": false,\n      \"isMultiDatamart\": false,\n      \"companyIntegration\": null,\n      \"datamart\": { \"id\": \"0d2e7a3c-5b1f-4c9e-8a6d-3f4b2c1e0a9d\", \"name\": \"Sales\" }\n    }\n  ]\n}\n```\n\n| Field | Description |\n| --- | --- |\n| `name` | The workspace name. Other endpoints take it as `name` or `workspaceName` |\n| `companyIntegration` | The datasource of a `DATASOURCE` workspace, or `null` |\n| `datamart` | The datamart of a `DATAMART` workspace, or `null` |\n| `isMultiDatasource`, `isMultiDatamart` | `true` for a multi workspace |\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 500 | `INTERNAL_SERVER_ERROR` | The list could not be read |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."},"put":{"operationId":"updateWorkspace","summary":"Update workspace","description":"```bash\ncurl --request PUT https://api.usedatabrain.com/api/v2/workspace \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\n    \"name\": \"Customer analytics\",\n    \"connectionType\": \"DATAMART\",\n    \"datamartName\": \"Sales v2\",\n    \"themeName\": \"Acme light\"\n  }'\n```\n\n## Auth\n\nA service token. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Workspace APIs"],"x-mint-page":"/developer-docs/helpers/api-reference/update-workspace","x-title":"Update a workspace","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Up to 100 characters, unique in your organization. You cannot rename it with the API."},"connectionType":{"type":"string","enum":["DATAMART","DATASOURCE","MULTI_DATASOURCE","MULTI_DATAMART"],"description":"`DATASOURCE`, `DATAMART`, `MULTI_DATASOURCE` or `MULTI_DATAMART`"},"datasourceName":{"type":"string","description":"Required for `DATASOURCE`. The datasource name. Ignored for other types."},"datamartName":{"type":"string","description":"Required for `DATAMART`. The datamart name. Ignored for other types."},"llmName":{"type":"string","description":"Name of an LLM in **Settings > LLMs**."},"aiCopilotLlms":{"type":"array","items":{"type":"string"},"description":"Names of the LLMs for the AI copilot."},"isEnableMetricSuggestions":{"type":"boolean","description":"Suggest metrics. Default `false`"},"isEnableMetricSummary":{"type":"boolean","description":"AI summaries on metrics. Default `false`"},"summaryType":{"type":"string","enum":["technicalAndInsightSummary","forecastAndTrendAnalysis","comparativeAndAnomalyDetection","custom"],"description":"Required with `isEnableMetricSummary`. `technicalAndInsightSummary`, `forecastAndTrendAnalysis`, `comparativeAndAnomalyDetection` or `custom`"},"customSummaryPrompt":{"type":"string","description":"Required with `summaryType: custom`. Your summary prompt."},"themeName":{"type":"string","description":"Name of a theme in **Settings > UI Theming**."}},"required":["name","connectionType"],"additionalProperties":false},"example":{"name":"Customer analytics","connectionType":"DATAMART","datamartName":"Sales v2","themeName":"Acme light"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":{"name":"Customer analytics"}}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: A field is missing, unknown or wrong\n- `WORKSPACE_DOES_NOT_EXIST`: No workspace has this name\n- `INVALID_DATASOURCE_NAME`: The connection name is unknown\n- `INVALID_DATAMART_NAME`: The connection name is unknown\n- `INVALID_LLM_NAME`: An LLM name is unknown\n- `INVALID_AI_COPILOT_LLMS`: An LLM name is unknown\n- `INVALID_THEME_NAME`: No theme has this name. The other changes were saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"A field is missing, unknown or wrong"}}}}},"403":{"description":"- `AUTHENTICATION_ERROR`: A data app API token on a service-token endpoint. Use a service token\n- `TRIAL_ENDED`: The trial ended. Choose a plan in **Settings > Billing**","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"A data app API token on a service-token endpoint. Use a service token"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: The update failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"The update failed"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body","intro":"The fields are the same as [Create a workspace](/developer-docs/helpers/api-reference/create-workspace#body). These rules are different:\n\n- `name` picks the workspace. You cannot rename it.\n- `connectionType` is required on every call, and the connection is set again each time. To keep it, send the same type and name.\n- A change to a `DATASOURCE` or `DATAMART` connection also moves the metrics on the workspace's dashboards to the new connection. Metrics on no dashboard are not moved. Multi workspaces move no metrics.\n- A new `llmName` clears the chosen model of the old LLM.\n- `aiCopilotLlms: []` changes nothing.\n- The other fields change only when you send them."}],"x-mint-rest":"## Response\n\n```json\n{ \"data\": { \"name\": \"Customer analytics\" } }\n```\n\nIf `name` is `\"\"`, the update was not saved. List the workspace and try again.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | A field is missing, unknown or wrong |\n| 400 | `WORKSPACE_DOES_NOT_EXIST` | No workspace has this name |\n| 400 | `INVALID_DATASOURCE_NAME` or `INVALID_DATAMART_NAME` | The connection name is unknown |\n| 400 | `INVALID_LLM_NAME` or `INVALID_AI_COPILOT_LLMS` | An LLM name is unknown |\n| 400 | `INVALID_THEME_NAME` | No theme has this name. The other changes were saved |\n| 500 | `INTERNAL_SERVER_ERROR` | The update failed |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."},"delete":{"operationId":"deleteWorkspace","summary":"Delete workspace","description":"Databrain deletes the workspace, its dashboards and its metrics. A workspace with a dashboard embedded in a data app cannot be deleted: remove the embed first.\n\n```bash\ncurl --request DELETE \\\n  \"https://api.usedatabrain.com/api/v2/workspace?name=Customer%20analytics\" \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\"\n```\n\n> [!WARNING]\n> You cannot undo this. The dashboards and metrics of the workspace are deleted with it.\n\n## Auth\n\nA service token. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Workspace APIs"],"x-mint-page":"/developer-docs/helpers/api-reference/delete-workspace","x-title":"Delete a workspace","security":[{"ApiToken":[]}],"parameters":[{"name":"name","in":"query","required":true,"schema":{"type":"string"},"description":"The workspace name. Encode spaces in the URL."}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":{"id":"Customer analytics","message":"Workspace deleted successfully"}}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: `name` is missing\n- `WORKSPACE_ID_ERROR`: No workspace has this name\n- `WORKSPACE_HAS_EMBEDDED_DASHBOARDS`: A dashboard of the workspace is embedded in a data app. [Delete the embed](/developer-docs/helpers/api-reference/delete-embed) first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"`name` is missing"}}}}},"403":{"description":"- `AUTHENTICATION_ERROR`: A data app API token on a service-token endpoint. Use a service token\n- `TRIAL_ENDED`: The trial ended. Choose a plan in **Settings > Billing**","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"A data app API token on a service-token endpoint. Use a service token"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: The delete failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"The delete failed"}}}}}},"x-mint-sections":[{"in":"parameters","heading":"Query"}],"x-mint-rest":"## Response\n\n```json\n{\n  \"data\": {\n    \"id\": \"Customer analytics\",\n    \"message\": \"Workspace deleted successfully\"\n  }\n}\n```\n\n`id` is the name you sent.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | `name` is missing |\n| 400 | `WORKSPACE_ID_ERROR` | No workspace has this name |\n| 400 | `WORKSPACE_HAS_EMBEDDED_DASHBOARDS` | A dashboard of the workspace is embedded in a data app. [Delete the embed](/developer-docs/helpers/api-reference/delete-embed) first |\n| 500 | `INTERNAL_SERVER_ERROR` | The delete failed |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/workspace/dashboards":{"put":{"operationId":"updateWorkspaceDashboards","summary":"Update dashboards","description":"Use it on many dashboards in one call. Each dashboard entry changes its filters, its metrics, or both.\n\n```bash\ncurl --request PUT https://api.usedatabrain.com/api/v2/workspace/dashboards \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\n    \"workspaceName\": \"Customer analytics\",\n    \"dashboards\": [\n      {\n        \"dashboardId\": \"sales-overview\",\n        \"filters\": [\n          {\n            \"name\": \"Region\",\n            \"applyOnTables\": [\n              { \"schemaName\": \"public\", \"tableName\": \"orders\", \"columnName\": \"region\", \"dataType\": \"string\" }\n            ]\n          }\n        ],\n        \"appendMetrics\": [{ \"metricId\": \"b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e\" }]\n      }\n    ]\n  }'\n```\n\n## Auth\n\nA service token. A data app API token can change filters only. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Workspace APIs"],"x-mint-page":"/developer-docs/helpers/api-reference/update-workspace-dashboards","x-title":"Update workspace dashboards","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"workspaceName":{"type":"string","description":"The workspace."},"dashboards":{"type":"array","uniqueItems":true,"items":{"type":"object","properties":{"dashboardId":{"type":"string","description":"The dashboard's `externalDashboardId`, from [Fetch dashboards by workspace](/developer-docs/helpers/api-reference/cloud-databrain-endpoint)"},"filters":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"The label of a filter that is already on the dashboard.","x-mint-extra":true},"applyOnTables":{"type":"array","items":{"type":"object","properties":{"dataType":{"type":"string","x-mint-extra":true},"tableName":{"type":"string","x-mint-extra":true},"columnName":{"type":"string","x-mint-extra":true},"schemaName":{"type":"string","x-mint-extra":true}},"required":["dataType","tableName","columnName","schemaName"],"additionalProperties":false},"description":"The tables and columns the filter applies to.","x-mint-extra":true}},"required":["name","applyOnTables"],"additionalProperties":false},"description":"Filters to point at other columns. `name` is the filter's label on the dashboard. `applyOnTables` replaces where it applies: `schemaName`, `tableName`, `columnName` and `dataType`, all required."},"appendMetrics":{"type":"array","uniqueItems":true,"items":{"type":"object","properties":{"metricId":{"type":"string","description":"The id of the metric to add.","x-mint-extra":true}},"required":["metricId"],"additionalProperties":false},"description":"Workspace metrics to add, as `{ \"metricId\": \"...\" }`"},"removedMetrics":{"type":"array","uniqueItems":true,"items":{"type":"string"},"description":"Metric ids to remove that were added with `appendMetrics`"}},"required":["dashboardId"],"additionalProperties":false,"anyOf":[{"required":["filters"]},{"required":["appendMetrics"]},{"required":["removedMetrics"]}]},"description":"One entry per dashboard. Each `dashboardId` once."}},"required":["workspaceName","dashboards"],"additionalProperties":false},"example":{"workspaceName":"Customer analytics","dashboards":[{"dashboardId":"sales-overview","filters":[{"name":"Region","applyOnTables":[{"schemaName":"public","tableName":"orders","columnName":"region","dataType":"string"}]}],"appendMetrics":[{"metricId":"b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e"}]}]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":{"success":true},"error":null}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: A field is missing or wrong. A metric is both added and removed. A filter name is not on the dashboard\n- `WORKSPACE_ID_ERROR`: No workspace has this name\n- `INVALID_DASHBOARD_ID`: No dashboard in the workspace has this id\n- `CLIENT_ID_ERROR`: You added or removed metrics on a dashboard that a customer did not make\n- `INVALID_METRIC_ID`: A metric id is unknown, or was not added to this dashboard","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"A field is missing or wrong. A metric is both added and removed. A filter name is not on the dashboard"}}}}},"403":{"description":"- `AUTHENTICATION_ERROR`: A data app API token tried to add or remove metrics\n- `TRIAL_ENDED`: The trial ended. Choose a plan in **Settings > Billing**","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"A data app API token tried to add or remove metrics"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: The update failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"The update failed"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body","after":"`appendMetrics` and `removedMetrics` work only on a dashboard that a customer made in the embed. Databrain adds a copy of each metric to that dashboard. The source metric must be live and in the workspace."}],"x-mint-rest":"## Response\n\n```json\n{ \"data\": { \"success\": true }, \"error\": null }\n```\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | A field is missing or wrong. A metric is both added and removed. A filter name is not on the dashboard |\n| 400 | `WORKSPACE_ID_ERROR` | No workspace has this name |\n| 400 | `INVALID_DASHBOARD_ID` | No dashboard in the workspace has this id |\n| 400 | `CLIENT_ID_ERROR` | You added or removed metrics on a dashboard that a customer did not make |\n| 400 | `INVALID_METRIC_ID` | A metric id is unknown, or was not added to this dashboard |\n| 403 | `AUTHENTICATION_ERROR` | A data app API token tried to add or remove metrics |\n| 500 | `INTERNAL_SERVER_ERROR` | The update failed |\n\nDashboards are saved one after the other. If one fails, the ones before it stay changed.\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."},"post":{"operationId":"cloudDatabrainEndpoint","summary":"Fetch dashboards","description":"```bash\ncurl --request POST https://api.usedatabrain.com/api/v2/workspace/dashboards \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{ \"workspaceName\": \"Customer analytics\", \"isPagination\": true, \"pageNumber\": 1 }'\n```\n\n## Auth\n\nA service token. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Workspace APIs / Embedding API"],"x-mint-page":"/developer-docs/helpers/api-reference/cloud-databrain-endpoint","x-title":"Fetch dashboards by workspace","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"workspaceName":{"type":"string","description":"The workspace."},"isPagination":{"type":"boolean","description":"`true` returns 10 dashboards per page. Send a JSON boolean: the string `\"false\"` turns paging on."},"pageNumber":{"type":"number","description":"Page, from `1`"}},"required":["workspaceName"],"additionalProperties":false},"example":{"workspaceName":"Customer analytics","isPagination":true,"pageNumber":1}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8","name":"Sales overview","externalDashboardId":"sales-overview"}]}}}},"400":{"description":"- `WORKSPACE_ID_ERROR`: No workspace has this name\n- `INVALID_REQUEST_BODY`: `workspaceName` is missing, or a field is unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"WORKSPACE_ID_ERROR","message":"No workspace has this name"}}}}},"403":{"description":"- `AUTHENTICATION_ERROR`: A data app API token on a service-token endpoint. Use a service token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"A data app API token on a service-token endpoint. Use a service token"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body"}],"x-mint-rest":"## Response\n\n```json\n{\n  \"data\": [\n    {\n      \"id\": \"4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8\",\n      \"name\": \"Sales overview\",\n      \"externalDashboardId\": \"sales-overview\"\n    }\n  ]\n}\n```\n\n| Field | Description |\n| --- | --- |\n| `externalDashboardId` | The id to use as `dashboardId` in embeds and other dashboard calls |\n| `id` | Internal id |\n| `name` | Dashboard name |\n\nThe list includes dashboards your customers made. The order is not fixed.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | `workspaceName` is missing, or a field is unknown |\n| 400 | `WORKSPACE_ID_ERROR` | No workspace has this name |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint).\n\nNext, [create an embed](/developer-docs/helpers/api-reference/create-embed) for a dashboard."}},"/api/v2/workspace/dashboard":{"post":{"operationId":"createWorkspaceDashboard","summary":"Create dashboard","description":"You describe the dashboard as a tile list. Databrain makes the dashboard and one metric per tile, and checks every tile.\n\n```bash\ncurl --request POST \"https://api.usedatabrain.com/api/v2/workspace/dashboard?workspaceName=Customer%20analytics\" \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --header \"Idempotency-Key: 6c1f0b7e-2d3a-4e5f-8a9b-0c1d2e3f4a5b\" \\\n  --data '{\n    \"schemaVersion\": 1,\n    \"title\": \"Sales overview\",\n    \"layout\": { \"columns\": 24 },\n    \"tiles\": [\n      {\n        \"id\": \"revenue-by-month\",\n        \"kind\": \"databrain-chart\",\n        \"title\": \"Revenue by month\",\n        \"position\": { \"x\": 0, \"y\": 0, \"w\": 12, \"h\": 8 },\n        \"chart\": { \"type\": \"line\", \"metricRef\": \"<metric id>\" }\n      }\n    ]\n  }'\n```\n\n## Auth\n\nA service token only. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Workspace APIs"],"x-mint-page":"/developer-docs/helpers/api-reference/create-workspace-dashboard","x-title":"Create a dashboard from tiles","security":[{"ServiceToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"schemaVersion":{"type":"integer","description":"`1`","enum":[1]},"title":{"type":"string","description":"Dashboard name, 1 to 200 characters."},"description":{"type":"string","description":"Up to 2,000 characters."},"layout":{"type":"object","properties":{"columns":{"type":"integer","description":"`12` or `24`. Default `24`","enum":[12,24],"default":24}},"description":"The grid. `columns` is the grid width, an integer."},"tiles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Your id for the tile: lower-case letters, numbers and `-`, up to 63 characters."},"kind":{"type":"string","description":"`databrain-chart`","enum":["databrain-chart"]},"title":{"type":"string","description":"Tile title, 1 to 200 characters."},"position":{"type":"object","description":"`x` 0 to 23, `y` from 0, `w` 1 to 24, `h` 1 to 40."},"chart":{"type":"object","properties":{"type":{"type":"string","description":"A chart type, or `custom:<key>` for a published custom chart."},"metricRef":{"type":"string","description":"An existing metric to show."},"query":{"type":"string","description":"A query for a new metric."},"chartOptions":{"type":"object","description":"Chart settings."},"companyIntegrationId":{"type":"string","description":"The datasource id the `query` runs on. Required with `query`.","x-mint-extra":true}},"description":"What the tile shows. Every tile needs it. `type` is required.","required":["type"]}},"required":["id","kind","title","position"]},"description":"1 to 50 tiles."}},"required":["schemaVersion","title","tiles"]},"example":{"schemaVersion":1,"title":"Sales overview","layout":{"columns":24},"tiles":[{"id":"revenue-by-month","kind":"databrain-chart","title":"Revenue by month","position":{"x":0,"y":0,"w":12,"h":8},"chart":{"type":"line","metricRef":"<metric id>"}}]}}}},"parameters":[{"name":"workspaceName","in":"query","required":true,"schema":{"type":"string"},"description":"The workspace, up to 200 characters."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"A UUID v4. A retry with the same key and body returns the first answer, with the header `Idempotency-Replay: true`"}],"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"dashboardId":"4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8","workspaceId":"9a7c1e2b-3d4f-4a5b-8c6d-7e8f9a0b1c2d","slugMap":{"revenue-by-month":"b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e"},"tileVerdicts":[{"id":"revenue-by-month","ok":true,"problems":[]}]}}}},"400":{"description":"- `workspaceName is required as a single query parameter.` (missing, empty, sent twice, or longer than 200 characters)\n- `Idempotency-Key must be a UUID v4.`\n- `A JSON body is required.`\n- `Body does not match the dashboard tile-list schema.`\n- `workspaceName`\n- `Idempotency-Key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"`workspaceName is required as a single query parameter.` (missing, empty, sent twice, or longer than 200 characters)"}}}}},"401":{"description":"- `AUTHENTICATION_ERROR`: The token is unknown, revoked or expired. Use a current token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"The token is unknown, revoked or expired. Use a current token"}}}}},"403":{"description":"- `AUTHENTICATION_ERROR`: A data app API token on a service-token endpoint. Use a service token\n- `You used a data app API token`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"A data app API token on a service-token endpoint. Use a service token"}}}}},"404":{"description":"- `Workspace not found.`\n- `Workspace not found.`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"`Workspace not found.`"}}}}},"409":{"description":"- `This key was used with a different body.` or `The original request is still in progress.`\n- `Idempotency-Key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"`This key was used with a different body.` or `The original request is still in progress.`"}}}}},"422":{"description":"- A tile is wrong. The body has `tileVerdicts`: `[{ id, ok, problems }]` (chart type, grid fit, duplicate id, overlap, `metricRef` or `query`, datasource, SELECT only, test query).\n- `tileVerdicts`\n- `problems`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"A tile is wrong. The body has `tileVerdicts`: `[{ id, ok, problems }]` (chart type, grid fit, duplicate id, overlap, `metricRef` or `query`, datasource, SELECT only, test query)."}}}}},"500":{"description":"- `Dashboard creation failed.` This also happens when the trial has ended.\n- `Dashboard creation failed.`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"`Dashboard creation failed.` This also happens when the trial has ended."}}}}},"503":{"description":"- `Idempotency storage is unavailable. Retry with the same key.`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"`Idempotency storage is unavailable. Retry with the same key.`"}}}}}},"x-mint-sections":[{"in":"parameters","heading":"Query and headers"},{"in":"body","heading":"Body","intro":"The body follows the tile-list schema `https://schemas.usedatabrain.com/agent/tile-list/v1.json`. Unknown fields are refused, except inside `chart`."}],"x-mint-rest":"## Response\n\nThe status is `201`.\n\n```json\n{\n  \"dashboardId\": \"4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8\",\n  \"workspaceId\": \"9a7c1e2b-3d4f-4a5b-8c6d-7e8f9a0b1c2d\",\n  \"slugMap\": { \"revenue-by-month\": \"b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e\" },\n  \"tileVerdicts\": [{ \"id\": \"revenue-by-month\", \"ok\": true, \"problems\": [] }]\n}\n```\n\n`slugMap` gives the metric id made for each tile id.\n\n## Errors\n\nErrors on this endpoint have only a message: `{ \"error\": { \"message\": \"...\" } }`.\n\n| Status | Why |\n| --- | --- |\n| 400 | The body does not match the schema, `workspaceName` is missing, or `Idempotency-Key` is not a UUID v4 |\n| 403 | You used a data app API token |\n| 404 | `Workspace not found.` |\n| 409 | The `Idempotency-Key` was used with a different body, or the first request is still running |\n| 422 | A tile is not valid. The body has `tileVerdicts` with each tile's `problems`. Nothing was made |\n| 500 | `Dashboard creation failed.` |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint).\n\nNext, [read the dashboard back](/developer-docs/helpers/api-reference/get-workspace-dashboard)."},"get":{"operationId":"getWorkspaceDashboard","summary":"Get dashboard","description":"```bash\ncurl \"https://api.usedatabrain.com/api/v2/workspace/dashboard?workspaceName=Customer%20analytics&dashboardId=sales-overview\" \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\"\n```\n\n## Auth\n\nA service token only. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Workspace APIs"],"x-mint-page":"/developer-docs/helpers/api-reference/get-workspace-dashboard","x-title":"Get a dashboard as tiles","security":[{"ServiceToken":[]}],"parameters":[{"name":"workspaceName","in":"query","required":true,"schema":{"type":"string"},"description":"The workspace, up to 200 characters."},{"name":"dashboardId","in":"query","required":true,"schema":{"type":"string"},"description":"The dashboard's `externalDashboardId` or its UUID."}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"schemaVersion":1,"title":"Sales overview","layout":{"columns":24},"tiles":[{"id":"revenue-by-month","kind":"databrain-chart","title":"Revenue by month","position":{"x":0,"y":0,"w":12,"h":8},"chart":{"type":"line","metricRef":"b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e","query":"SELECT month, SUM(amount) AS revenue FROM orders GROUP BY month","companyIntegrationId":"6f1c2b9e-4d3a-4f8e-9b7c-2a1d0e5f6c7b","chartOptions":{}}}],"dashboardId":"4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8","externalDashboardId":"sales-overview"}}}},"400":{"description":"- `workspaceName is required as a single query parameter.`\n- `dashboardId must be a dashboard UUID or slug.`\n- `dashboardId must be a dashboard UUID or slug.`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"`workspaceName is required as a single query parameter.`"}}}}},"401":{"description":"- `AUTHENTICATION_ERROR`: The token is unknown, revoked or expired. Use a current token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"The token is unknown, revoked or expired. Use a current token"}}}}},"403":{"description":"- `AUTHENTICATION_ERROR`: A data app API token on a service-token endpoint. Use a service token\n- `You used a data app API token`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"A data app API token on a service-token endpoint. Use a service token"}}}}},"404":{"description":"- `Workspace not found.`\n- `Dashboard not found or identifier is ambiguous.`\n- `Dashboard not found or identifier is ambiguous.`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"`Workspace not found.`"}}}}},"409":{"description":"- `This dashboard uses an unsupported schema version.` or `Stored dashboard cannot be represented by the current tile-list schema.`\n- `The dashboard cannot be shown as a tile list`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"`This dashboard uses an unsupported schema version.` or `Stored dashboard cannot be represented by the current tile-list schema.`"}}}}},"500":{"description":"- `Dashboard read failed.`\n- `Dashboard read failed.`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"`Dashboard read failed.`"}}}}}},"x-mint-sections":[{"in":"parameters","heading":"Query","after":"Dashboards that a customer made in an embed are not returned."}],"x-mint-rest":"## Response\n\n```json\n{\n  \"schemaVersion\": 1,\n  \"title\": \"Sales overview\",\n  \"layout\": { \"columns\": 24 },\n  \"dashboardId\": \"4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8\",\n  \"externalDashboardId\": \"sales-overview\",\n  \"tiles\": [\n    {\n      \"id\": \"revenue-by-month\",\n      \"kind\": \"databrain-chart\",\n      \"title\": \"Revenue by month\",\n      \"position\": { \"x\": 0, \"y\": 0, \"w\": 12, \"h\": 8 },\n      \"chart\": { \"type\": \"line\", \"metricRef\": \"b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e\", \"chartOptions\": {} }\n    }\n  ]\n}\n```\n\nThe fields are those of [Create a dashboard from tiles](/developer-docs/helpers/api-reference/create-workspace-dashboard#body). A tile whose metric or datasource is gone has `\"unavailable\": true` and a `reason`.\n\n## Errors\n\nErrors have only a message: `{ \"error\": { \"message\": \"...\" } }`.\n\n| Status | Why |\n| --- | --- |\n| 400 | `dashboardId must be a dashboard UUID or slug.` |\n| 403 | You used a data app API token |\n| 404 | `Dashboard not found or identifier is ambiguous.` |\n| 409 | The dashboard cannot be shown as a tile list |\n| 500 | `Dashboard read failed.` |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/workspace/metrics":{"post":{"operationId":"fetchMetricsByWorkspace","summary":"Fetch metrics","description":"The list has every live metric of the workspace and of its dashboards. Archived metrics, and the copies made for customer dashboards, are left out.\n\n```bash\ncurl --request POST https://api.usedatabrain.com/api/v2/workspace/metrics \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{ \"workspaceName\": \"Customer analytics\", \"isPagination\": true, \"pageNumber\": 1 }'\n```\n\n## Auth\n\nA service token. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Workspace APIs / Embedding API"],"x-mint-page":"/developer-docs/helpers/api-reference/fetch-metrics-by-workspace","x-title":"Fetch metrics by workspace","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"workspaceName":{"type":"string","description":"The workspace."},"isPagination":{"type":"boolean","description":"`true` returns up to 10 metrics per page. Send a JSON boolean."},"pageNumber":{"type":"number","description":"Page, from `1`"}},"required":["workspaceName"],"additionalProperties":false},"example":{"workspaceName":"Customer analytics","isPagination":true,"pageNumber":1}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"name":"Monthly revenue","metricId":"b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e"}]}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: `workspaceName` is missing, or a field is unknown\n- `WORKSPACE_ID_ERROR`: No workspace has this name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"`workspaceName` is missing, or a field is unknown"}}}}},"403":{"description":"- `AUTHENTICATION_ERROR`: A data app API token on a service-token endpoint. Use a service token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"A data app API token on a service-token endpoint. Use a service token"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body","after":"A page can have fewer than 10 metrics when there are more pages. Stop when a page is empty."}],"x-mint-rest":"## Response\n\n```json\n{\n  \"data\": [\n    { \"name\": \"Monthly revenue\", \"metricId\": \"b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e\" }\n  ]\n}\n```\n\nMetrics your customers made are in the list. The order is not fixed.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | `workspaceName` is missing, or a field is unknown |\n| 400 | `WORKSPACE_ID_ERROR` | No workspace has this name |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/workspace/dashboard/metrics":{"post":{"operationId":"fetchMetricsByDashboard","summary":"Fetch dashboard metrics","description":"```bash\ncurl --request POST https://api.usedatabrain.com/api/v2/workspace/dashboard/metrics \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{ \"workspaceName\": \"Customer analytics\", \"dashboardId\": \"sales-overview\" }'\n```\n\n## Auth\n\nA service token. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Workspace APIs / Embedding API"],"x-mint-page":"/developer-docs/helpers/api-reference/fetch-metrics-by-dashboard","x-title":"Fetch metrics by dashboard","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"workspaceName":{"type":"string","description":"The workspace."},"dashboardId":{"type":"string","description":"The dashboard's `externalDashboardId`, from [Fetch dashboards by workspace](/developer-docs/helpers/api-reference/cloud-databrain-endpoint)"},"isPagination":{"type":"boolean","description":"`true` returns 10 metrics per page. Send a JSON boolean."},"pageNumber":{"type":"number","description":"Page, from `1`"}},"required":["workspaceName","dashboardId"],"additionalProperties":false},"example":{"workspaceName":"Customer analytics","dashboardId":"sales-overview"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"name":"Monthly revenue","metricId":"b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e"}]}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: A field is missing or unknown\n- `WORKSPACE_ID_ERROR`: No workspace has this name\n- `DASHBOARD_PARAM_ERROR`: No dashboard in this workspace has this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"A field is missing or unknown"}}}}},"403":{"description":"- `AUTHENTICATION_ERROR`: A data app API token on a service-token endpoint. Use a service token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"A data app API token on a service-token endpoint. Use a service token"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body"}],"x-mint-rest":"## Response\n\n```json\n{\n  \"data\": [\n    { \"name\": \"Monthly revenue\", \"metricId\": \"b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e\" }\n  ]\n}\n```\n\nArchived and deleted metrics are left out. Metrics added to a customer dashboard are in the list. The order is not fixed.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | A field is missing or unknown |\n| 400 | `WORKSPACE_ID_ERROR` | No workspace has this name |\n| 400 | `DASHBOARD_PARAM_ERROR` | No dashboard in this workspace has this id |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/data-app/embeds":{"post":{"operationId":"createEmbed","summary":"Create embed","description":"```bash\ncurl --request POST https://api.usedatabrain.com/api/v2/data-app/embeds \\\n  --header \"Authorization: Bearer $DATABRAIN_API_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\n    \"workspaceName\": \"Customer analytics\",\n    \"dashboardId\": \"sales-overview\",\n    \"embedType\": \"dashboard\",\n    \"name\": \"Sales overview\",\n    \"accessSettings\": {\n      \"datamartName\": \"Sales\",\n      \"metricCreationMode\": \"DRAG_DROP\",\n      \"isAllowEmailReports\": true,\n      \"isAllowManageMetrics\": false,\n      \"isAllowCreateDashboardView\": true,\n      \"isAllowMetricCreation\": false,\n      \"isAllowMetricDeletion\": false,\n      \"isAllowMetricLayoutChange\": true,\n      \"isAllowMetricUpdate\": false,\n      \"isAllowUnderlyingData\": true\n    }\n  }'\n```\n\n## Before you start\n\n- You have a data app API token for the data app. A service token does not work here. See [Authentication](/developer-docs/helpers/api-reference/authentication).\n- Your plan includes embedding.\n- You have the dashboard's `externalDashboardId`. See [Fetch dashboards by workspace](/developer-docs/helpers/api-reference/cloud-databrain-endpoint).","tags":["Embeds"],"x-mint-page":"/developer-docs/helpers/api-reference/create-embed","x-title":"Embed a dashboard or metric","security":[{"DataAppApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"workspaceName":{"type":"string","description":"The workspace of the dashboard."},"dashboardId":{"type":"string","description":"The dashboard's `externalDashboardId`"},"embedType":{"type":"string","enum":["dashboard","metric"],"description":"`dashboard` or `metric`"},"metricId":{"type":"string","description":"Required for `metric`. A metric on that dashboard."},"accessSettings":{"type":"object","properties":{"datamartName":{"type":"string","description":"The datamart the embed queries. Its tenancy must match the workspace."},"metricCreationMode":{"type":"string","enum":["DRAG_DROP","CHAT"],"description":"Create metrics with `DRAG_DROP` or `CHAT`"},"isAllowEmailReports":{"type":"boolean","description":"Schedule email reports."},"isAllowManageMetrics":{"type":"boolean","description":"Manage metrics."},"isAllowCreateDashboardView":{"type":"boolean","description":"Save dashboard views."},"isAllowMetricCreation":{"type":"boolean","description":"Create metrics."},"isAllowMetricDeletion":{"type":"boolean","description":"Delete metrics."},"isAllowMetricLayoutChange":{"type":"boolean","description":"Move and resize metrics."},"isAllowMetricUpdate":{"type":"boolean","description":"Edit metrics."},"isAllowUnderlyingData":{"type":"boolean","description":"See the underlying data."},"isAllowAiPilot":{"type":"boolean","description":"Use AI features.","default":false},"isAllowEndUserDashboardFilter":{"type":"boolean","description":"Add dashboard filters.","default":false},"isAllowEndUserMetricFilter":{"type":"boolean","description":"Add metric filters.","default":false},"isAllowCrossTenantDashboardImport":{"type":"boolean","description":"Import a dashboard that uses another tenant's metrics, rebound to their own tenant.","default":false},"joinModel":{"type":"string","enum":["single","multi"],"description":"`multi` lets metrics join tables. `single` does not."},"isIncrementalJoin":{"type":"boolean","description":"Same as `joinModel: multi` (older field)","default":false},"tableTenancySettings":{"type":"array","items":{"type":"object","properties":{"clientColumn":{"type":"string","x-mint-extra":true},"name":{"type":"string","x-mint-extra":true}},"required":["clientColumn","name"],"additionalProperties":false},"description":"The tenant column per table: `{ \"name\": \"orders\", \"clientColumn\": \"customer_id\" }`. `name` has no schema.","default":"From the datamart"},"dashboardFilterColumns":{"type":"array","items":{"type":"object","properties":{"tableName":{"type":"string","x-mint-extra":true},"columns":{"type":"array","items":{"type":"string"},"x-mint-extra":true}},"required":["tableName","columns"],"additionalProperties":false},"description":"Columns they can filter dashboards on: `{ \"tableName\": \"public.orders\", \"columns\": [\"region\"] }`","default":"All columns"},"metricFilterColumns":{"type":"array","items":{"type":"object","properties":{"tableName":{"type":"string","x-mint-extra":true},"columns":{"type":"array","items":{"type":"string"},"x-mint-extra":true}},"required":["tableName","columns"],"additionalProperties":false},"description":"Columns they can filter metrics on, same shape.","default":"All columns"}},"required":["datamartName","isAllowEmailReports","isAllowManageMetrics","isAllowCreateDashboardView","isAllowMetricCreation","isAllowMetricDeletion","isAllowMetricLayoutChange","isAllowMetricUpdate","isAllowUnderlyingData","metricCreationMode"],"additionalProperties":false,"description":"Required for `dashboard`. What your customers can do. Metric embeds ignore it."},"name":{"type":"string","description":"Display name. Default: the embed id."},"embedDescription":{"type":"string","description":"Description."}},"required":["dashboardId","embedType","workspaceName"],"additionalProperties":false},"example":{"workspaceName":"Customer analytics","dashboardId":"sales-overview","embedType":"dashboard","name":"Sales overview","accessSettings":{"datamartName":"Sales","metricCreationMode":"DRAG_DROP","isAllowEmailReports":true,"isAllowManageMetrics":false,"isAllowCreateDashboardView":true,"isAllowMetricCreation":false,"isAllowMetricDeletion":false,"isAllowMetricLayoutChange":true,"isAllowMetricUpdate":false,"isAllowUnderlyingData":true}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"sales-overview","name":"Sales overview"}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: A field is missing, unknown or wrong\n- `WORKSPACE_ID_ERROR`: No workspace has this name\n- `INVALID_DATA_APP_API_KEY`: You used a service token, or the token has no data app\n- `INVALID_DASHBOARD_ID`: No dashboard in the workspace has this id\n- `INVALID_METRIC_ID`: The metric is not on that dashboard\n- `INVALID_DATAMART`: No datamart has this name, or its tenancy does not match the workspace\n- `DATAMART_TABLE_NOT_FOUND`: The datamart has table tenancy but no tables","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"A field is missing, unknown or wrong"}}}}},"403":{"description":"- `entitlement_required`: Your plan does not include embedding","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"entitlement_required","message":"Your plan does not include embedding"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: Databrain failed. Try again. If it fails again, contact support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"Databrain failed. Try again. If it fails again, contact support"}}}}},"503":{"description":"- `entitlement_check_unavailable`: Databrain could not check your plan. Try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"entitlement_check_unavailable","message":"Databrain could not check your plan. Try again"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body","intro":"Unknown fields are refused."}],"x-mint-rest":"## Response\n\n```json\n{ \"id\": \"sales-overview\", \"name\": \"Sales overview\" }\n```\n\n`id` is the embed id. Use it in the web component and in the other embed calls. If the data app already embeds this dashboard or metric, the new id gets a suffix, for example `sales-overview__a1B2c3D4`. Each call makes a new embed.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | A field is missing, unknown or wrong |\n| 400 | `INVALID_DATA_APP_API_KEY` | You used a service token, or the token has no data app |\n| 400 | `WORKSPACE_ID_ERROR` | No workspace has this name |\n| 400 | `INVALID_DASHBOARD_ID` | No dashboard in the workspace has this id |\n| 400 | `INVALID_METRIC_ID` | The metric is not on that dashboard |\n| 400 | `INVALID_DATAMART` | No datamart has this name, or its tenancy does not match the workspace |\n| 400 | `DATAMART_TABLE_NOT_FOUND` | The datamart has table tenancy but no tables |\n| 403 | `entitlement_required` | Your plan does not include embedding |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint).\n\nNext, [create a guest token](/developer-docs/helpers/api-reference/token) to show the embed."},"get":{"operationId":"listEmbed","summary":"List embeds","description":"```bash\ncurl \"https://api.usedatabrain.com/api/v2/data-app/embeds?isPagination=true&pageNumber=1\" \\\n  --header \"Authorization: Bearer $DATABRAIN_API_TOKEN\"\n```\n\n## Auth\n\nA data app API token. You see the embeds of its data app only. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Embeds"],"x-mint-page":"/developer-docs/helpers/api-reference/list-embed","x-title":"List embeds","security":[{"DataAppApiToken":[]}],"parameters":[{"name":"isPagination","in":"query","required":false,"schema":{"type":"string","enum":["true","false"],"default":"false"},"description":"`true` returns 10 embeds per page. Without it you get all."},{"name":"pageNumber","in":"query","required":false,"schema":{"type":"integer","default":1},"description":"Page, from `1`"},{"name":"clientId","in":"query","required":false,"schema":{"type":"string"},"description":"Only embeds of dashboards that this customer made."}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d","embedId":"sales-overview","embedType":"dashboard","name":"Sales overview","embedDescription":null,"createdAt":"2026-11-10T08:00:00.000Z","updatedAt":"2026-11-10T08:00:00.000Z","dashboardId":"sales-overview","dataAppId":"7c8d9e0f-1a2b-4c3d-8e4f-5a6b7c8d9e0f","externalDashboardId":"2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e","externalMetricId":null,"externalDashboard":{"externalDashboardId":"sales-overview","metadata":null,"name":"Sales overview"},"externalMetric":null,"embedMetadata":{"id":"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d","embedId":"sales-overview","name":"Sales overview","embedDescription":null,"embedType":"dashboard","dataAppName":"Customer analytics","metricId":null,"dashboardId":"sales-overview","externalDashboardId":"2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e","externalMetricId":null,"createdAt":"2026-11-10T08:00:00.000Z","updatedAt":"2026-11-10T08:00:00.000Z"}}]}}}},"400":{"description":"- `INVALID_DATA_APP_API_KEY`: You used a service token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_DATA_APP_API_KEY","message":"You used a service token"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: The list could not be read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"The list could not be read"}}}}}},"x-mint-sections":[{"in":"parameters","heading":"Query","after":"The order is not fixed and there is no total count."}],"x-mint-rest":"## Response\n\n```json\n{\n  \"data\": [\n    {\n      \"id\": \"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d\",\n      \"embedId\": \"sales-overview\",\n      \"embedType\": \"dashboard\",\n      \"name\": \"Sales overview\",\n      \"embedDescription\": null,\n      \"dashboardId\": \"sales-overview\",\n      \"dataAppId\": \"7c8d9e0f-1a2b-4c3d-8e4f-5a6b7c8d9e0f\",\n      \"createdAt\": \"2026-11-10T08:00:00.000Z\",\n      \"updatedAt\": \"2026-11-10T08:00:00.000Z\",\n      \"externalDashboard\": { \"externalDashboardId\": \"sales-overview\", \"name\": \"Sales overview\", \"metadata\": null },\n      \"externalMetric\": null,\n      \"embedMetadata\": {\n        \"embedId\": \"sales-overview\",\n        \"name\": \"Sales overview\",\n        \"embedType\": \"dashboard\",\n        \"dataAppName\": \"Customer analytics\",\n        \"dashboardId\": \"sales-overview\",\n        \"metricId\": null\n      }\n    }\n  ]\n}\n```\n\n| Field | Description |\n| --- | --- |\n| `embedId` | The embed id. Use it in the web component and in other embed calls |\n| `id` | Internal id of the embed |\n| `embedType` | `dashboard` or `metric` |\n| `externalDashboard.metadata` | The `metadata` you sent when you created a customer dashboard embed |\n| `externalMetric` | `{ \"metricId\", \"name\" }` for a metric embed |\n| `embedMetadata` | The same facts in one object, with the data app name |\n\nAccess settings are not in the list. `externalDashboardId` and `externalMetricId` at the top level are internal ids.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_DATA_APP_API_KEY` | You used a service token |\n| 500 | `INTERNAL_SERVER_ERROR` | The list could not be read |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."},"put":{"operationId":"updateEmbed","summary":"Update embed","description":"Only the fields you send change. Metric embeds have no access settings to change.\n\n```bash\ncurl --request PUT https://api.usedatabrain.com/api/v2/data-app/embeds \\\n  --header \"Authorization: Bearer $DATABRAIN_API_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\n    \"embedId\": \"sales-overview\",\n    \"accessSettings\": { \"isAllowUnderlyingData\": false, \"isAllowAiPilot\": true }\n  }'\n```\n\n## Before you start\n\n- You have a data app API token for the data app. See [Authentication](/developer-docs/helpers/api-reference/authentication).\n- Your plan includes embedding.","tags":["Embeds"],"x-mint-page":"/developer-docs/helpers/api-reference/update-embed","x-title":"Update embed access settings","security":[{"DataAppApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"embedId":{"type":"string","description":"A dashboard embed of the data app."},"accessSettings":{"type":"object","properties":{"datamartName":{"type":"string","description":"The datamart the embed queries. Its tenancy must match the workspace."},"metricCreationMode":{"type":"string","enum":["DRAG_DROP","CHAT"],"description":"Create metrics with `DRAG_DROP` or `CHAT`"},"isAllowEmailReports":{"type":"boolean","description":"Schedule email reports."},"isAllowManageMetrics":{"type":"boolean","description":"Manage metrics."},"isAllowCreateDashboardView":{"type":"boolean","description":"Save dashboard views."},"isAllowMetricCreation":{"type":"boolean","description":"Create metrics."},"isAllowMetricDeletion":{"type":"boolean","description":"Delete metrics."},"isAllowMetricLayoutChange":{"type":"boolean","description":"Move and resize metrics."},"isAllowMetricUpdate":{"type":"boolean","description":"Edit metrics."},"isAllowUnderlyingData":{"type":"boolean","description":"See the underlying data."},"isAllowAiPilot":{"type":"boolean","description":"Use AI features."},"isAllowEndUserDashboardFilter":{"type":"boolean","description":"Add dashboard filters."},"isAllowEndUserMetricFilter":{"type":"boolean","description":"Add metric filters."},"isAllowCrossTenantDashboardImport":{"type":"boolean","description":"Import a dashboard that uses another tenant's metrics, rebound to their own tenant."},"joinModel":{"type":"string","enum":["single","multi"],"description":"`multi` lets metrics join tables. `single` does not."},"isIncrementalJoin":{"type":"boolean","description":"Same as `joinModel: multi` (older field)"},"tableTenancySettings":{"type":"array","items":{"type":"object","properties":{"clientColumn":{"type":"string","x-mint-extra":true},"name":{"type":"string","x-mint-extra":true}},"required":["clientColumn","name"],"additionalProperties":false},"description":"The tenant column per table: `{ \"name\": \"orders\", \"clientColumn\": \"customer_id\" }`. `name` has no schema."},"dashboardFilterColumns":{"type":"array","items":{"type":"object","properties":{"tableName":{"type":"string","x-mint-extra":true},"columns":{"type":"array","items":{"type":"string"},"x-mint-extra":true}},"required":["tableName","columns"],"additionalProperties":false},"description":"Columns they can filter dashboards on: `{ \"tableName\": \"public.orders\", \"columns\": [\"region\"] }`"},"metricFilterColumns":{"type":"array","items":{"type":"object","properties":{"tableName":{"type":"string","x-mint-extra":true},"columns":{"type":"array","items":{"type":"string"},"x-mint-extra":true}},"required":["tableName","columns"],"additionalProperties":false},"description":"Columns they can filter metrics on, same shape."}},"additionalProperties":false,"description":"Any fields of [accessSettings](/developer-docs/helpers/api-reference/create-embed#param-access-settings). None is required."}},"required":["embedId","accessSettings"],"additionalProperties":false},"example":{"embedId":"sales-overview","accessSettings":{"isAllowUnderlyingData":false,"isAllowAiPilot":true}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"sales-overview"}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: A field is unknown or wrong, or nothing would change: `Access settings cannot be empty`\n- `INVALID_DATA_APP_API_KEY`: You used a service token\n- `INVALID_EMBED_ID`: No dashboard embed of this data app has this id\n- `INVALID_DATAMART`: The `datamartName` is wrong\n- `DATAMART_TABLE_NOT_FOUND`: The `datamartName` is wrong","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"A field is unknown or wrong, or nothing would change: `Access settings cannot be empty`"}}}}},"403":{"description":"- `entitlement_required`: Your plan does not include embedding","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"entitlement_required","message":"Your plan does not include embedding"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: The update failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"The update failed"}}}}},"503":{"description":"- `entitlement_check_unavailable`: Databrain could not check your plan. Try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"entitlement_check_unavailable","message":"Databrain could not check your plan. Try again"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body","after":"Send booleans as JSON `true` or `false`: the string `\"false\"` is saved as `true`.\n\nThese fields work differently on update:\n\n- `datamartName` does not move the embed to another datamart. It reloads the table list from that datamart.\n- `tableTenancySettings` works only with `datamartName` in the same call. Tables you leave out of it lose their tenant column, so list every table.\n- `joinModel` replaces `isIncrementalJoin`."}],"x-mint-rest":"## Response\n\n```json\n{ \"id\": \"sales-overview\" }\n```\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | A field is unknown or wrong, or nothing would change: `Access settings cannot be empty` |\n| 400 | `INVALID_DATA_APP_API_KEY` | You used a service token |\n| 400 | `INVALID_EMBED_ID` | No dashboard embed of this data app has this id |\n| 400 | `INVALID_DATAMART` or `DATAMART_TABLE_NOT_FOUND` | The `datamartName` is wrong |\n| 403 | `entitlement_required` | Your plan does not include embedding |\n| 500 | `INTERNAL_SERVER_ERROR` | The update failed |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."},"delete":{"operationId":"deleteEmbed","summary":"Delete embed","description":"```bash\ncurl --request DELETE \\\n  \"https://api.usedatabrain.com/api/v2/data-app/embeds?embedId=acme-sales&isDeleteDashboard=true\" \\\n  --header \"Authorization: Bearer $DATABRAIN_API_TOKEN\"\n```\n\n> [!WARNING]\n> You cannot undo this. Guest tokens you already gave out are not revoked; they stop working when they expire.\n\n## Auth\n\nA data app API token. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Embeds"],"x-mint-page":"/developer-docs/helpers/api-reference/delete-embed","x-title":"Delete an embed","security":[{"DataAppApiToken":[]}],"parameters":[{"name":"embedId","in":"query","required":true,"schema":{"type":"string"},"description":"A dashboard or metric embed of the data app."},{"name":"isDeleteDashboard","in":"query","required":false,"schema":{"type":"string","enum":["true","false"],"default":"false"},"description":"`true` also deletes the dashboard. Only a dashboard that a customer made, and that no other embed uses."}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"acme-sales"}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: `embedId` is missing\n- `INVALID_DATA_APP_API_KEY`: You used a service token\n- `INVALID_EMBED_ID`: No embed of this data app has this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"`embedId` is missing"}}}}},"409":{"description":"- `INVALID_REQUEST_BODY`: With `isDeleteDashboard`: `Deletion blocked: internal dashboards can't be removed.` or `Deletion blocked: this dashboard is referenced by multiple embeds.` Nothing was deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"With `isDeleteDashboard`: `Deletion blocked: internal dashboards can't be removed.` or `Deletion blocked: this dashboard is referenced by multiple embeds.` Nothing was deleted"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: The embed was deleted, the dashboard was not","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"The embed was deleted, the dashboard was not"}}}}}},"x-mint-sections":[{"in":"parameters","heading":"Query"}],"x-mint-rest":"## Response\n\n```json\n{ \"id\": \"acme-sales\" }\n```\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | `embedId` is missing |\n| 400 | `INVALID_DATA_APP_API_KEY` | You used a service token |\n| 400 | `INVALID_EMBED_ID` | No embed of this data app has this id |\n| 409 | `INVALID_REQUEST_BODY` | With `isDeleteDashboard`: `Deletion blocked: internal dashboards can't be removed.` or `Deletion blocked: this dashboard is referenced by multiple embeds.` Nothing was deleted |\n| 500 | `INTERNAL_SERVER_ERROR` | The embed was deleted, the dashboard was not |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/data-app/dashboard-embeds":{"post":{"operationId":"createDashboardEmbed","summary":"Create dashboard embed","description":"Databrain creates a dashboard owned by the customer in `clientId`, then embeds it in the data app.\n\n```bash\ncurl --request POST https://api.usedatabrain.com/api/v2/data-app/dashboard-embeds \\\n  --header \"Authorization: Bearer $DATABRAIN_API_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\n    \"workspaceName\": \"Customer analytics\",\n    \"dashboardId\": \"acme-sales\",\n    \"clientId\": \"acme\",\n    \"name\": \"Acme sales\",\n    \"templateDashboardId\": \"sales-overview\",\n    \"isImportMetrics\": true,\n    \"accessSettings\": {\n      \"datamartName\": \"Sales\",\n      \"metricCreationMode\": \"DRAG_DROP\",\n      \"isAllowEmailReports\": true,\n      \"isAllowManageMetrics\": true,\n      \"isAllowCreateDashboardView\": true,\n      \"isAllowMetricCreation\": true,\n      \"isAllowMetricDeletion\": true,\n      \"isAllowMetricLayoutChange\": true,\n      \"isAllowMetricUpdate\": true,\n      \"isAllowUnderlyingData\": true\n    }\n  }'\n```\n\n## Before you start\n\n- You have a data app API token for the data app. See [Authentication](/developer-docs/helpers/api-reference/authentication).\n- Your plan includes embedding.","tags":["Embeds"],"x-mint-page":"/developer-docs/helpers/api-reference/create-dashboard-embed","x-title":"Create a customer dashboard embed","security":[{"DataAppApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"workspaceName":{"type":"string","description":"The workspace for the new dashboard."},"dashboardId":{"type":"string","description":"Id of the new dashboard, also the embed id. No dashboard in the workspace may have it."},"clientId":{"type":"string","description":"The customer who owns the dashboard. Same value as the guest token's `clientId`"},"accessSettings":{"type":"object","properties":{"datamartName":{"type":"string","description":"The datamart the embed queries. Its tenancy must match the workspace."},"metricCreationMode":{"type":"string","enum":["DRAG_DROP","CHAT"],"description":"Create metrics with `DRAG_DROP` or `CHAT`"},"isAllowEmailReports":{"type":"boolean","description":"Schedule email reports."},"isAllowManageMetrics":{"type":"boolean","description":"Manage metrics."},"isAllowCreateDashboardView":{"type":"boolean","description":"Save dashboard views."},"isAllowMetricCreation":{"type":"boolean","description":"Create metrics."},"isAllowMetricDeletion":{"type":"boolean","description":"Delete metrics."},"isAllowMetricLayoutChange":{"type":"boolean","description":"Move and resize metrics."},"isAllowMetricUpdate":{"type":"boolean","description":"Edit metrics."},"isAllowUnderlyingData":{"type":"boolean","description":"See the underlying data."},"isAllowAiPilot":{"type":"boolean","description":"Use AI features.","default":false},"isAllowEndUserDashboardFilter":{"type":"boolean","description":"Add dashboard filters.","default":false},"isAllowEndUserMetricFilter":{"type":"boolean","description":"Add metric filters.","default":false},"isAllowCrossTenantDashboardImport":{"type":"boolean","description":"Import a dashboard that uses another tenant's metrics, rebound to their own tenant.","default":false},"joinModel":{"type":"string","enum":["single","multi"],"description":"`multi` lets metrics join tables. `single` does not."},"isIncrementalJoin":{"type":"boolean","description":"Same as `joinModel: multi` (older field)","default":false},"tableTenancySettings":{"type":"array","items":{"type":"object","properties":{"clientColumn":{"type":"string","x-mint-extra":true},"name":{"type":"string","x-mint-extra":true}},"required":["clientColumn","name"],"additionalProperties":false},"description":"The tenant column per table: `{ \"name\": \"orders\", \"clientColumn\": \"customer_id\" }`. `name` has no schema.","default":"From the datamart"},"dashboardFilterColumns":{"type":"array","items":{"type":"object","properties":{"tableName":{"type":"string","x-mint-extra":true},"columns":{"type":"array","items":{"type":"string"},"x-mint-extra":true}},"required":["tableName","columns"],"additionalProperties":false},"description":"Columns they can filter dashboards on: `{ \"tableName\": \"public.orders\", \"columns\": [\"region\"] }`","default":"All columns"},"metricFilterColumns":{"type":"array","items":{"type":"object","properties":{"tableName":{"type":"string","x-mint-extra":true},"columns":{"type":"array","items":{"type":"string"},"x-mint-extra":true}},"required":["tableName","columns"],"additionalProperties":false},"description":"Columns they can filter metrics on, same shape.","default":"All columns"}},"required":["datamartName","isAllowEmailReports","isAllowManageMetrics","isAllowCreateDashboardView","isAllowMetricCreation","isAllowMetricDeletion","isAllowMetricLayoutChange","isAllowMetricUpdate","isAllowUnderlyingData","metricCreationMode"],"additionalProperties":false,"description":"Same fields as [Embed a dashboard or metric](/developer-docs/helpers/api-reference/create-embed#param-access-settings)"},"name":{"type":"string","description":"Embed name. Default: `dashboardId`"},"embedDescription":{"type":"string","description":"Embed description."},"isRenameDashboard":{"type":"boolean","description":"Give the dashboard the `name` too. Otherwise it is named `<dashboardId>_<clientId>`","default":false},"templateDashboardId":{"type":"string","description":"A dashboard in the same workspace. Its filters and spacing are copied, not its layout."},"isImportMetrics":{"type":"boolean","description":"Also copy the template's metrics."},"metricImportMode":{"type":"string","enum":["GALLERY","METRIC"],"description":"`METRIC` or `GALLERY`"},"isAllowPrivateMetricsByDefault":{"type":"boolean","description":"New metrics are private to the user who makes them. Default `false`","default":false},"metadata":{"type":"object","description":"Your own data, stored on the dashboard and returned by [List embeds](/developer-docs/helpers/api-reference/list-embed)"},"importDashboardData":{"type":"object","description":"A dashboard export, from [Export an embedded dashboard](/developer-docs/helpers/api-reference/export-embed) or [Export a dashboard](/developer-docs/helpers/api-reference/export-dashboard). Overrides the template."},"schemaPairs":{"type":"array","items":{"type":"object","properties":{"replaceSchema":{"type":"string","x-mint-extra":true},"targetSchema":{"type":"string","x-mint-extra":true}},"required":["replaceSchema","targetSchema"],"additionalProperties":false},"description":"Schema names to swap in imported SQL: `{ \"replaceSchema\": \"staging\", \"targetSchema\": \"public\" }`"}},"required":["dashboardId","workspaceName","clientId","accessSettings"],"additionalProperties":false},"example":{"workspaceName":"Customer analytics","dashboardId":"acme-sales","clientId":"acme","name":"Acme sales","templateDashboardId":"sales-overview","isImportMetrics":true,"accessSettings":{"datamartName":"Sales","metricCreationMode":"DRAG_DROP","isAllowEmailReports":true,"isAllowManageMetrics":true,"isAllowCreateDashboardView":true,"isAllowMetricCreation":true,"isAllowMetricDeletion":true,"isAllowMetricLayoutChange":true,"isAllowMetricUpdate":true,"isAllowUnderlyingData":true}}},"multipart/form-data":{"schema":{"type":"object","properties":{"workspaceName":{"type":"string","description":"The workspace for the new dashboard."},"dashboardId":{"type":"string","description":"Id of the new dashboard, also the embed id. No dashboard in the workspace may have it."},"clientId":{"type":"string","description":"The customer who owns the dashboard. Same value as the guest token's `clientId`"},"accessSettings":{"type":"object","properties":{"datamartName":{"type":"string","description":"The datamart the embed queries. Its tenancy must match the workspace."},"isAllowAiPilot":{"type":"boolean","description":"Use AI features.","default":false},"isAllowEmailReports":{"type":"boolean","description":"Schedule email reports."},"isAllowManageMetrics":{"type":"boolean","description":"Manage metrics."},"isAllowCreateDashboardView":{"type":"boolean","description":"Save dashboard views."},"isAllowEndUserDashboardFilter":{"type":"boolean","description":"Add dashboard filters.","default":false},"isAllowEndUserMetricFilter":{"type":"boolean","description":"Add metric filters.","default":false},"isAllowCrossTenantDashboardImport":{"type":"boolean","description":"Import a dashboard that uses another tenant's metrics, rebound to their own tenant.","default":false},"isAllowMetricCreation":{"type":"boolean","description":"Create metrics."},"isAllowMetricDeletion":{"type":"boolean","description":"Delete metrics."},"isAllowMetricLayoutChange":{"type":"boolean","description":"Move and resize metrics."},"isAllowMetricUpdate":{"type":"boolean","description":"Edit metrics."},"isAllowUnderlyingData":{"type":"boolean","description":"See the underlying data."},"isIncrementalJoin":{"type":"boolean","description":"Same as `joinModel: multi` (older field)","default":false},"joinModel":{"type":"string","enum":["single","multi"],"description":"`multi` lets metrics join tables. `single` does not."},"metricCreationMode":{"type":"string","enum":["DRAG_DROP","CHAT"],"description":"Create metrics with `DRAG_DROP` or `CHAT`"},"tableTenancySettings":{"type":"array","items":{"type":"object","properties":{"clientColumn":{"type":"string"},"name":{"type":"string"}},"required":["clientColumn","name"],"additionalProperties":false},"description":"The tenant column per table: `{ \"name\": \"orders\", \"clientColumn\": \"customer_id\" }`. `name` has no schema.","default":"From the datamart"},"dashboardFilterColumns":{"type":"array","items":{"type":"object","properties":{"tableName":{"type":"string"},"columns":{"type":"array","items":{"type":"string"}}},"required":["tableName","columns"],"additionalProperties":false},"description":"Columns they can filter dashboards on: `{ \"tableName\": \"public.orders\", \"columns\": [\"region\"] }`","default":"All columns"},"metricFilterColumns":{"type":"array","items":{"type":"object","properties":{"tableName":{"type":"string"},"columns":{"type":"array","items":{"type":"string"}}},"required":["tableName","columns"],"additionalProperties":false},"description":"Columns they can filter metrics on, same shape.","default":"All columns"}},"required":["datamartName","isAllowEmailReports","isAllowManageMetrics","isAllowCreateDashboardView","isAllowMetricCreation","isAllowMetricDeletion","isAllowMetricLayoutChange","isAllowMetricUpdate","isAllowUnderlyingData","metricCreationMode"],"additionalProperties":false,"description":"Same fields as [Embed a dashboard or metric](/developer-docs/helpers/api-reference/create-embed#accesssettings)"},"name":{"type":"string","description":"Embed name. Default: `dashboardId`"},"embedDescription":{"type":"string","description":"Embed description."},"isRenameDashboard":{"type":"boolean","description":"Give the dashboard the `name` too. Otherwise it is named `<dashboardId>_<clientId>`","default":false},"templateDashboardId":{"type":"string","description":"A dashboard in the same workspace. Its filters and spacing are copied, not its layout."},"isImportMetrics":{"type":"boolean","description":"Also copy the template's metrics."},"metricImportMode":{"type":"string","enum":["GALLERY","METRIC"],"description":"`METRIC` or `GALLERY`"},"isAllowPrivateMetricsByDefault":{"type":"boolean","description":"New metrics are private to the user who makes them. Default `false`","default":false},"metadata":{"type":"object","description":"Your own data, stored on the dashboard and returned by [List embeds](/developer-docs/helpers/api-reference/list-embed)"},"importDashboardData":{"type":"object","description":"A dashboard export, from [Export an embedded dashboard](/developer-docs/helpers/api-reference/export-embed) or [Export a dashboard](/developer-docs/helpers/api-reference/export-dashboard). Overrides the template."},"importDashboardDataFile":{"type":"string","format":"binary","description":"Multipart only: the export as a `.json` file. Overrides `importDashboardData`"},"schemaPairs":{"type":"array","items":{"type":"object","properties":{"replaceSchema":{"type":"string"},"targetSchema":{"type":"string"}},"required":["replaceSchema","targetSchema"],"additionalProperties":false},"description":"Schema names to swap in imported SQL: `{ \"replaceSchema\": \"staging\", \"targetSchema\": \"public\" }`"}},"required":["dashboardId","workspaceName","clientId","accessSettings"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"acme-sales","name":"Acme sales","importSummary":{"imported":8,"skipped":1,"skippedMetrics":[{"metricId":"b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e","name":"Churn","reason":"TARGET_TABLE_NOT_FOUND"}]}}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: A field is missing or wrong. In `schemaPairs`, fill both names or neither\n- `WORKSPACE_ID_ERROR`: No workspace has this name\n- `INVALID_DATA_APP_API_KEY`: You used a service token\n- `CLIENT_ID_ERROR`: `clientId` is empty\n- `INVALID_DASHBOARD_ID`: A dashboard in the workspace already has this `dashboardId`\n- `TEMPLATE_DASHBOARD_ERROR`: No dashboard in the workspace has the `templateDashboardId`\n- `DASHBOARD_CREATE_ERROR`: The dashboard or the import failed. Nothing was kept. `hint` says what to check\n- `INVALID_DATAMART`: The `accessSettings.datamartName` is wrong\n- `DATAMART_TABLE_NOT_FOUND`: The `accessSettings.datamartName` is wrong\n- `FILE_UPLOAD_ERROR`: The file is not JSON\n- `IMPORT_DASHBOARD_DATA_FILE_ERROR`: The file field is not named `importDashboardDataFile`\n- `INVALID_DASHBOARD_DATA`: The uploaded file is empty JSON (`null`, `false`, `0` or `\"\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"A field is missing or wrong. In `schemaPairs`, fill both names or neither"}}}}},"403":{"description":"- `entitlement_required`: Your plan does not include embedding","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"entitlement_required","message":"Your plan does not include embedding"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: The request failed, for example the file is not valid JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"The request failed, for example the file is not valid JSON"}}}}},"503":{"description":"- `entitlement_check_unavailable`: Databrain could not check your plan. Try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"entitlement_check_unavailable","message":"Databrain could not check your plan. Try again"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body","intro":"Send JSON, or `multipart/form-data` to upload an export file.","after":"With multipart, send `accessSettings`, `metadata`, `importDashboardData`, `schemaPairs` and the booleans as JSON strings."}],"x-mint-rest":"## Response\n\n```json\n{\n  \"id\": \"acme-sales\",\n  \"name\": \"Acme sales\",\n  \"importSummary\": {\n    \"imported\": 8,\n    \"skipped\": 1,\n    \"skippedMetrics\": [\n      { \"metricId\": \"b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e\", \"name\": \"Churn\", \"reason\": \"TARGET_TABLE_NOT_FOUND\" }\n    ]\n  }\n}\n```\n\n`importSummary` is there only after an import. A metric can be skipped for `TARGET_TABLE_NOT_FOUND`, `MISSING_DATASET_CONFIGURATION`, `MISSING_DEPENDENT_METRIC`, `RAW_SQL_NOT_SAFE_TO_REGENERATE`, `TARGET_CLIENT_COLUMN_NOT_CONFIGURED` or `QUERY_GENERATION_FAILED`.\n\n## Errors\n\nErrors can have `hint` and `details`.\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | A field is missing or wrong. In `schemaPairs`, fill both names or neither |\n| 400 | `INVALID_DATA_APP_API_KEY` | You used a service token |\n| 400 | `WORKSPACE_ID_ERROR` | No workspace has this name |\n| 400 | `CLIENT_ID_ERROR` | `clientId` is empty |\n| 400 | `INVALID_DASHBOARD_ID` | A dashboard in the workspace already has this `dashboardId` |\n| 400 | `TEMPLATE_DASHBOARD_ERROR` | No dashboard in the workspace has the `templateDashboardId` |\n| 400 | `DASHBOARD_CREATE_ERROR` | The dashboard or the import failed. Nothing was kept. `hint` says what to check |\n| 400 | `INVALID_DATAMART` or `DATAMART_TABLE_NOT_FOUND` | The `accessSettings.datamartName` is wrong |\n| 400 | `FILE_UPLOAD_ERROR` | The file is not JSON |\n| 400 | `IMPORT_DASHBOARD_DATA_FILE_ERROR` | The file field is not named `importDashboardDataFile` |\n| 403 | `entitlement_required` | Your plan does not include embedding |\n| 500 | `INTERNAL_SERVER_ERROR` | The request failed, for example the file is not valid JSON |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/data-app/embeds/reports":{"get":{"operationId":"listScheduleReportsByEmbed","summary":"List scheduled reports","description":"```bash\ncurl \"https://api.usedatabrain.com/api/v2/data-app/embeds/reports?embedId=sales-overview&clientId=acme\" \\\n  --header \"Authorization: Bearer $DATABRAIN_API_TOKEN\"\n```\n\n## Auth\n\nA data app API token. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Embeds"],"x-mint-page":"/developer-docs/helpers/api-reference/list-schedule-reports-by-embed","x-title":"List scheduled reports","security":[{"DataAppApiToken":[]}],"parameters":[{"name":"embedId","in":"query","required":true,"schema":{"type":"string"},"description":"A dashboard embed of the data app."},{"name":"clientId","in":"query","required":true,"schema":{"type":"string"},"description":"The customer. Without it you get `400`, so one call never shows every customer's reports."},{"name":"userIdentifier","in":"query","required":false,"schema":{"type":"string"},"description":"Only reports made by this user, the guest token's `params.userIdentifier`"},{"name":"isPagination","in":"query","required":false,"schema":{"type":"string","enum":["true","false"],"default":"false"},"description":"`true` returns 10 reports per page."},{"name":"pageNumber","in":"query","required":false,"schema":{"type":"integer","default":1},"description":"Page, from `1`"}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"subject":"Weekly sales","scheduleEmailReportCharts":[{"externalMetric":{"metricId":"b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e"}}],"timeConfigurations":{},"createdAt":"2026-11-12T09:00:00.000Z","updatedAt":"2026-11-12T09:00:00.000Z","embedId":"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d","createdByIdentifier":"jane@acme.com","clientId":"acme"}]}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: `clientId` or `embedId` is missing\n- `INVALID_DATA_APP_API_KEY`: You used a service token\n- `INVALID_EMBED_ID`: No dashboard embed of this data app has this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"`clientId` or `embedId` is missing"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: The list could not be read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"The list could not be read"}}}}}},"x-mint-sections":[{"in":"parameters","heading":"Query"}],"x-mint-rest":"## Response\n\n```json\n{\n  \"data\": [\n    {\n      \"subject\": \"Weekly sales\",\n      \"scheduleEmailReportCharts\": [{ \"externalMetric\": { \"metricId\": \"b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e\" } }],\n      \"timeConfigurations\": { },\n      \"createdAt\": \"2026-11-12T09:00:00.000Z\",\n      \"updatedAt\": \"2026-11-12T09:00:00.000Z\",\n      \"embedId\": \"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d\",\n      \"createdByIdentifier\": \"jane@acme.com\",\n      \"clientId\": \"acme\"\n    }\n  ]\n}\n```\n\n| Field | Description |\n| --- | --- |\n| `subject` | Email subject |\n| `scheduleEmailReportCharts` | The metrics in the report |\n| `timeConfigurations` | When the report is sent |\n| `createdByIdentifier` | The user who made it |\n| `embedId` | Internal id of the embed, not the embed id you sent |\n\nRecipients and the report id are not returned. The order is not fixed.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | `clientId` or `embedId` is missing |\n| 400 | `INVALID_DATA_APP_API_KEY` | You used a service token |\n| 400 | `INVALID_EMBED_ID` | No dashboard embed of this data app has this id |\n| 500 | `INTERNAL_SERVER_ERROR` | The list could not be read |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."},"delete":{"operationId":"deleteScheduleReport","summary":"Delete scheduled report","description":"```bash\ncurl --request DELETE \\\n  \"https://api.usedatabrain.com/api/v2/data-app/embeds/reports?embedId=sales-overview&id=8f9e0d1c-2b3a-4c5d-9e6f-7a8b9c0d1e2f\" \\\n  --header \"Authorization: Bearer $DATABRAIN_API_TOKEN\"\n```\n\n> [!WARNING]\n> You cannot undo this. The report stops at once.\n\n## Auth\n\nA data app API token. A service token gets `401`. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Embeds"],"x-mint-page":"/developer-docs/helpers/api-reference/delete-schedule-report","x-title":"Delete a scheduled report","security":[{"DataAppApiToken":[]}],"parameters":[{"name":"embedId","in":"query","required":true,"schema":{"type":"string"},"description":"A dashboard embed of the data app."},{"name":"id","in":"query","required":true,"schema":{"type":"string"},"description":"The scheduled report id. [List scheduled reports](/developer-docs/helpers/api-reference/list-schedule-reports-by-embed) does not return it."}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":{"deleted":1}}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: `embedId` or `id` is missing: `Deleting a scheduled report needs both an embedId and an id. Both are query parameters.`\n- `Deleting a scheduled report needs both an embedId and an id. Both are query parameters.`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"`embedId` or `id` is missing: `Deleting a scheduled report needs both an embedId and an id. Both are query parameters.`"}}}}},"401":{"description":"- `INVALID_REQUEST_BODY`: The token has no data app: `This API token is not scoped to a data app, so it cannot delete a scheduled report. Create a data app API token and use that.`\n- `This API token is not scoped to a data app, so it cannot delete a scheduled report. Create a data app API token and use that.`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"The token has no data app: `This API token is not scoped to a data app, so it cannot delete a scheduled report. Create a data app API token and use that.`"}}}}},"404":{"description":"- `INVALID_REQUEST_BODY`: No such report on this embed: `That scheduled report is not on this embed for this data app, so nothing was deleted.`\n- `That scheduled report is not on this embed for this data app, so nothing was deleted.`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"No such report on this embed: `That scheduled report is not on this embed for this data app, so nothing was deleted.`"}}}}},"500":{"description":"- `INVALID_REQUEST_BODY`: `The scheduled report could not be deleted just now. Try again in a minute.`\n- `The scheduled report could not be deleted just now. Try again in a minute.`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"`The scheduled report could not be deleted just now. Try again in a minute.`"}}}}}},"x-mint-sections":[{"in":"parameters","heading":"Query"}],"x-mint-rest":"## Response\n\n```json\n{ \"data\": { \"deleted\": 1 } }\n```\n\n## Errors\n\nAll errors on this endpoint have the code `INVALID_REQUEST_BODY`. Read the status and the message.\n\n| Status | Message |\n| --- | --- |\n| 400 | `Deleting a scheduled report needs both an embedId and an id. Both are query parameters.` |\n| 401 | `This API token is not scoped to a data app, so it cannot delete a scheduled report. Create a data app API token and use that.` |\n| 404 | `That scheduled report is not on this embed for this data app, so nothing was deleted.` |\n| 500 | `The scheduled report could not be deleted just now. Try again in a minute.` |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/dashboard/updateDashboardFilterAlias":{"post":{"operationId":"updateFilterAlias","summary":"Update filter alias","description":"Your app calls this with a guest token, for the customer who is viewing. The alias shows instead of the filter name.\n\n```bash\ncurl --request POST https://api.usedatabrain.com/api/v2/dashboard/updateDashboardFilterAlias \\\n  --header \"X-Plugin-Token: $GUEST_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{ \"externalDashboard\": \"sales-overview\", \"filterKey\": \"public.orders.region\", \"alias\": \"Sales region\" }'\n```\n\nFor a metric filter, call `POST /api/v2/dashboard/updateMetricFilterAlias` with `externalMetricId` instead of `externalDashboard`.\n\n## Auth\n\nA guest token in the `X-Plugin-Token` header, not a Bearer token. The guest token needs `params.accessPermissions.isAllowDashboardFilterNameChange` (or `isAllowMetricFilterNameChange` for a metric) set to `true`. See [Create a guest token](/developer-docs/helpers/api-reference/token).\n\nA guest token that sees all tenants sets the alias for every customer. Otherwise it is set for the token's `clientId` only.","tags":["Embeds"],"x-mint-page":"/developer-docs/helpers/api-reference/update-filter-alias","x-title":"Rename a filter in an embed","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"externalDashboard":{"type":"string","description":"Required dashboard. The dashboard's `externalDashboardId`"},"externalMetricId":{"type":"string","description":"Required metric. The metric id."},"filterKey":{"type":"string","description":"The filter's column as `table.column`, for example `public.orders.region`. Letter case does not matter."},"alias":{"type":"string","description":"The new label, up to 100 characters. `\"\"` removes the alias."}},"required":["filterKey","alias","externalDashboard"]},"example":{"externalDashboard":"sales-overview","filterKey":"public.orders.region","alias":"Sales region"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":{"filterKey":"public.orders.region","alias":""}}}}},"400":{"description":"- The `X-Plugin-Token` header is missing or wrong. The body is `{ \"error\": \"UNAUTHORISED REQUEST!\" }`.\n- The body is wrong: `Invalid dashboard filter alias payload`.\n- `alias` is longer than 100 characters.\n- The guest token could not be read.\n- `filterKey` is not a dashboard filter that an admin made.\n- `Invalid dashboard filter alias payload`: A field is missing or empty\n- `Dashboard filter alias is too long`: `alias` is over 100 characters\n- `Invalid dashboard filter`: No filter on the dashboard has this `filterKey`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"The `X-Plugin-Token` header is missing or wrong. The body is `{ \"error\": \"UNAUTHORISED REQUEST!\" }`."}}}}},"401":{"description":"- `AUTHENTICATION_ERROR`: The token is unknown, revoked or expired. Use a current token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"The token is unknown, revoked or expired. Use a current token"}}}}},"403":{"description":"- A report link token cannot rename filters: `{ \"message\": \"Access denied: report link.\" }`.\n- The token cannot rename this filter: the dashboard is not in the token, the data app or its allowed embeds (`UNAUTHORIZED`).\n- `FORBIDDEN`: The token is not for all clients and its `clientId` is empty: `You do not have permission to rename this dashboard filter.`\n- `UNAUTHORIZED`: The guest token may not rename filters, or the dashboard is outside it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"A report link token cannot rename filters: `{ \"message\": \"Access denied: report link.\" }`."}}}}},"404":{"description":"- No dashboard has this id.\n- `Dashboard not found`: The id is unknown\n- `Metric not found`: The id is unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"No dashboard has this id."}}}}},"500":{"description":"- The new name was not saved: `Something went wrong`.\n- `INTERNAL_SERVER_ERROR`: Databrain failed. Try again. If it fails again, contact support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"The new name was not saved: `Something went wrong`."}}}}}},"x-mint-sections":[{"in":"body","heading":"Body","after":"Only filters that you made in the app can get an alias, not filters a customer added."}],"x-mint-rest":"## Response\n\n```json\n{ \"data\": { \"id\": \"2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e\", \"filterKey\": \"public.orders.region\", \"alias\": \"Sales region\" } }\n```\n\nWhen you remove the alias, `id` is not in the response.\n\n## Errors\n\nThis endpoint puts the error in `data.error`:\n\n```json\n{ \"data\": { \"error\": { \"message\": \"Invalid dashboard filter\" } } }\n```\n\n| Status | Message | Why |\n| --- | --- | --- |\n| 400 | `Invalid dashboard filter alias payload` | A field is missing or empty |\n| 400 | `Dashboard filter alias is too long` | `alias` is over 100 characters |\n| 400 | `Invalid dashboard filter` | No filter on the dashboard has this `filterKey` |\n| 403 | `UNAUTHORIZED` | The guest token may not rename filters, or the dashboard is outside it |\n| 404 | `Dashboard not found` or `Metric not found` | The id is unknown |\n\nThe metric endpoint returns the same messages with `metric` instead of `dashboard`."}},"/api/v2/data-app/embeds/rename":{"put":{"operationId":"renameEmbed","summary":"Rename embed","description":"```bash\ncurl --request PUT https://api.usedatabrain.com/api/v2/data-app/embeds/rename \\\n  --header \"Authorization: Bearer $DATABRAIN_API_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{ \"embedId\": \"sales-overview\", \"name\": \"Sales at a glance\", \"isRenameDashboard\": true }'\n```\n\n## Auth\n\nA data app API token. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Embeds"],"x-mint-page":"/developer-docs/helpers/api-reference/rename-embed","x-title":"Rename an embed","security":[{"DataAppApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"embedId":{"type":"string","description":"A dashboard embed of the data app."},"name":{"type":"string","description":"The new name. Cannot be empty."},"embedDescription":{"type":"string","description":"The new description. `\"\"` does not clear it."},"isRenameDashboard":{"type":"boolean","description":"Also rename the dashboard. Every embed of that dashboard shows the new name. Send a JSON boolean.","default":false}},"required":["embedId","name"],"additionalProperties":false},"example":{"embedId":"sales-overview","name":"Sales at a glance","isRenameDashboard":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"sales-overview","name":"Sales at a glance","embedDescription":null}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: `embedId` or `name` is missing or empty\n- `INVALID_DATA_APP_API_KEY`: You used a service token\n- `INVALID_EMBED_ID`: No dashboard embed of this data app has this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"`embedId` or `name` is missing or empty"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: The rename failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"The rename failed"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body"}],"x-mint-rest":"## Response\n\n```json\n{ \"id\": \"sales-overview\", \"name\": \"Sales at a glance\", \"embedDescription\": null }\n```\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | `embedId` or `name` is missing or empty |\n| 400 | `INVALID_DATA_APP_API_KEY` | You used a service token |\n| 400 | `INVALID_EMBED_ID` | No dashboard embed of this data app has this id |\n| 500 | `INTERNAL_SERVER_ERROR` | The rename failed |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/data-app/embeds/export":{"get":{"operationId":"exportEmbed","summary":"Export embed","description":"The file has the dashboard as its owner sees it. Pass it to [Create a customer dashboard embed](/developer-docs/helpers/api-reference/create-dashboard-embed) as `importDashboardDataFile` to copy it.\n\n```bash\ncurl \"https://api.usedatabrain.com/api/v2/data-app/embeds/export?embedId=sales-overview\" \\\n  --header \"Authorization: Bearer $DATABRAIN_API_TOKEN\" \\\n  --output dashboard-sales-overview.json\n```\n\n## Auth\n\nA data app API token. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Embeds"],"x-mint-page":"/developer-docs/helpers/api-reference/export-embed","x-title":"Export an embedded dashboard","security":[{"DataAppApiToken":[]}],"parameters":[{"name":"embedId","in":"query","required":true,"schema":{"type":"string"},"description":"A dashboard embed of the data app."}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"_meta":{"exportedAt":"2026-11-19T10:00:00.000Z","embedId":"sales-overview","name":"Sales overview","createdAt":"2026-11-10T08:00:00.000Z","embedType":"dashboard","embedDataAppAccessSetting":{"isAllowAiPilot":false,"isAllowEmailReports":true,"isAllowManageMetrics":false,"isAllowCreateDashboardView":true,"isAllowEndUserDashboardFilter":false,"isAllowEndUserMetricFilter":false,"isAllowMetricCreation":false,"isAllowMetricDeletion":false,"isAllowMetricLayoutChange":true,"isAllowMetricUpdate":false,"isAllowUnderlyingData":true,"metricCreationMode":"DRAG_DROP","isIncrementalJoin":false},"dashboardId":"sales-overview"},"data":{}}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: `embedId` is missing\n- `INVALID_DATA_APP_API_KEY`: You used a service token\n- `EMBED_PARAM_ERROR`: No dashboard embed of this data app has this id\n- `INVALID_EMBED_ID`: The embed was deleted while the export ran.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"`embedId` is missing"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: The export failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"The export failed"}}}}}},"x-mint-sections":[{"in":"parameters","heading":"Query"}],"x-mint-rest":"## Response\n\nA file download: `Content-Disposition: attachment; filename=\"dashboard-<embedId>.json\"`.\n\n```json\n{\n  \"_meta\": {\n    \"exportedAt\": \"2026-11-19T10:00:00.000Z\",\n    \"embedId\": \"sales-overview\",\n    \"name\": \"Sales overview\",\n    \"createdAt\": \"2026-11-10T08:00:00.000Z\",\n    \"embedType\": \"dashboard\",\n    \"dashboardId\": \"sales-overview\",\n    \"embedDataAppAccessSetting\": {\n      \"isAllowAiPilot\": false,\n      \"isAllowEmailReports\": true,\n      \"isAllowManageMetrics\": false,\n      \"isAllowCreateDashboardView\": true,\n      \"isAllowEndUserDashboardFilter\": false,\n      \"isAllowEndUserMetricFilter\": false,\n      \"isAllowMetricCreation\": false,\n      \"isAllowMetricDeletion\": false,\n      \"isAllowMetricLayoutChange\": true,\n      \"isAllowMetricUpdate\": false,\n      \"isAllowUnderlyingData\": true,\n      \"metricCreationMode\": \"DRAG_DROP\",\n      \"isIncrementalJoin\": false\n    }\n  },\n  \"data\": { }\n}\n```\n\n`data` is the dashboard, with its values encrypted. Do not edit it. `_meta` is for you to read; the import ignores it.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | `embedId` is missing |\n| 400 | `INVALID_DATA_APP_API_KEY` | You used a service token |\n| 400 | `EMBED_PARAM_ERROR` | No dashboard embed of this data app has this id |\n| 500 | `INTERNAL_SERVER_ERROR` | The export failed |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/data-app/whitelist-domains":{"put":{"operationId":"whitelistDomains","summary":"Allowed domains","description":"The list is for your whole organization: every data app uses it. PUT replaces the whole list.\n\n```bash\ncurl --request PUT https://api.usedatabrain.com/api/v2/data-app/whitelist-domains \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{ \"domains\": [\"app.example.com\", \"*.example.com\", \"localhost:3000\"] }'\n```\n\nTo read the list:\n\n```bash\ncurl https://api.usedatabrain.com/api/v2/data-app/whitelist-domains \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\"\n```\n\n## Auth\n\nA service token. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Embeds"],"x-mint-page":"/developer-docs/helpers/api-reference/whitelist-domains","x-title":"Set the allowed domains","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domains":{"type":"array","items":{"type":"string","pattern":"^(\\*\\.)?([a-zA-Z0-9-]+\\.)+[a-zA-Z]{2,63}$|^(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(:\\d+)?$|^[lL][oO][cC][aA][lL][hH][oO][sS][tT](:\\d+)?$"},"description":"The allowed domains. `[]` empties the list."}},"required":["domains"],"additionalProperties":false},"example":{"domains":["app.example.com","*.example.com","localhost:3000"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":["app.example.com","*.example.com","localhost:3000"]}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: `domains` is missing, or an item is not valid: `Invalid domain format. Please enter domain/IP without http:// or https://`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"`domains` is missing, or an item is not valid: `Invalid domain format. Please enter domain/IP without http:// or https://`"}}}}},"403":{"description":"- `AUTHENTICATION_ERROR`: A data app API token on a service-token endpoint. Use a service token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"A data app API token on a service-token endpoint. Use a service token"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: The list could not be saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"The list could not be saved"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body (PUT)","after":"Each item is one of:\n\n- A domain, with no `http://` or `https://` and no port, for example `app.example.com`. Start with `*.` for all subdomains: `*.example.com`.\n- An IPv4 address, with or without a port: `203.0.113.10:8080`.\n- `localhost`, with or without a port: `localhost:3000`.\n\nItems are saved as you send them."}],"x-mint-rest":"## Response\n\nGET:\n\n```json\n{ \"data\": [\"app.example.com\", \"*.example.com\", \"localhost:3000\"] }\n```\n\nPUT:\n\n```json\n{ \"data\": { \"domains\": [\"app.example.com\", \"*.example.com\", \"localhost:3000\"] } }\n```\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | `domains` is missing, or an item is not valid: `Invalid domain format. Please enter domain/IP without http:// or https://` |\n| 500 | `INTERNAL_SERVER_ERROR` | The list could not be saved |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/data-app/smtp-settings":{"put":{"operationId":"smtpSettings","summary":"SMTP settings","description":"The setting is for your whole organization. Databrain signs in to the server first and saves the settings only if that works.\n\n```bash\ncurl --request PUT https://api.usedatabrain.com/api/v2/data-app/smtp-settings \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\n    \"host\": \"smtp.example.com\",\n    \"port\": 587,\n    \"secure\": true,\n    \"username\": \"reports@example.com\",\n    \"password\": \"<password>\",\n    \"fromAddress\": \"reports@example.com\",\n    \"replyToAddress\": \"support@example.com\"\n  }'\n```\n\n## Auth\n\nA service token. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Embeds"],"x-mint-page":"/developer-docs/helpers/api-reference/smtp-settings","x-title":"Set the SMTP server","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"host":{"type":"string","description":"The SMTP server. It must be a public address."},"port":{"type":"integer","description":"The port, for example `587` or `465`"},"secure":{"type":"boolean","description":"Use TLS. See below."},"username":{"type":"string","description":"SMTP user."},"password":{"type":"string","description":"SMTP password."},"fromAddress":{"type":"string","format":"email","description":"The sender email address."},"replyToAddress":{"type":"string","format":"email","description":"The reply-to email address."}},"required":["host","port","username","password","fromAddress","replyToAddress","secure"],"additionalProperties":false},"example":{"host":"smtp.example.com","port":587,"secure":true,"username":"reports@example.com","password":"<password>","fromAddress":"reports@example.com","replyToAddress":"support@example.com"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":{"success":true}}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: A field is missing or wrong, for example `\"fromAddress\" must be a valid email`. Or the host is a private address\n- `INTERNAL_SERVER_ERROR`: Databrain could not sign in to the server. The message says why. Nothing was saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"A field is missing or wrong, for example `\"fromAddress\" must be a valid email`. Or the host is a private address"}}}}},"403":{"description":"- `AUTHENTICATION_ERROR`: A data app API token on a service-token endpoint. Use a service token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"A data app API token on a service-token endpoint. Use a service token"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: The settings could not be saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"The settings could not be saved"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body","intro":"All fields are required. Unknown fields are refused.","after":"| Port | `secure: true` | `secure: false` |\n| --- | --- | --- |\n| 465 | TLS from the start | TLS from the start |\n| 25, 587, 2525 | STARTTLS, required | TLS only if the server offers it |\n| Other | TLS from the start | TLS only if the server offers it |\n\nThe connection test waits up to 20 seconds."}],"x-mint-rest":"## Response\n\n```json\n{ \"data\": { \"success\": true } }\n```\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | A field is missing or wrong, for example `\"fromAddress\" must be a valid email`. Or the host is a private address |\n| 400 | `INTERNAL_SERVER_ERROR` | Databrain could not sign in to the server. The message says why. Nothing was saved |\n| 500 | `INTERNAL_SERVER_ERROR` | The settings could not be saved |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/data-app":{"post":{"operationId":"createDataApp","summary":"Create data app","description":"```bash\ncurl --request POST https://api.usedatabrain.com/api/v2/data-app \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{ \"name\": \"Customer portal\" }'\n```\n\n## Before you start\n\n- You have a service token. See [Authentication](/developer-docs/helpers/api-reference/authentication).\n- Your plan includes embedding. Check with [Check embed access](/developer-docs/helpers/api-reference/check-embed-access).","tags":["Data App APIs / Data App CRUD"],"x-mint-page":"/developer-docs/helpers/api-reference/create-data-app","x-title":"Create a data app","security":[{"ServiceToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The data app name. No other data app in your organization may have it."}},"required":["name"],"additionalProperties":false},"example":{"name":"Customer portal"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"name":"Customer portal"}}}},"400":{"description":"- `AUTHENTICATION_ERROR`: You used a data app API token\n- `INVALID_REQUEST_BODY`: `name` is missing or empty, or a field is unknown\n- `DATA_APP_ALREADY_EXISTS`: A data app has this name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"You used a data app API token"}}}}},"401":{"description":"- `AUTHENTICATION_ERROR`: You used a data app API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"You used a data app API token"}}}}},"403":{"description":"- `ACCOUNT_DISABLED`: The organization is disabled or locked for deletion. Contact Databrain support\n- `AUTHENTICATION_ERROR`: You used a data app API token\n- `entitlement_required`: Your plan does not include embedding","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"ACCOUNT_DISABLED","message":"The organization is disabled or locked for deletion. Contact Databrain support"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: The data app could not be saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"The data app could not be saved"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body","after":"Unknown fields are refused."}],"x-mint-rest":"## Response\n\n```json\n{ \"name\": \"Customer portal\" }\n```\n\nThe data app is an embedded data app. It has no API token and no embeds yet.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | `name` is missing or empty, or a field is unknown |\n| 400 | `DATA_APP_ALREADY_EXISTS` | A data app has this name |\n| 403 | `AUTHENTICATION_ERROR` | You used a data app API token |\n| 403 | `entitlement_required` | Your plan does not include embedding |\n| 500 | `INTERNAL_SERVER_ERROR` | The data app could not be saved |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint).\n\nNext, [create an API token](/developer-docs/helpers/api-reference/create-api-token) for it."},"get":{"operationId":"listDataApps","summary":"List data apps","description":"```bash\ncurl \"https://api.usedatabrain.com/api/v2/data-app?isPagination=true&pageNumber=1\" \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\"\n```\n\n## Auth\n\nA service token. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Data App APIs / Data App CRUD"],"x-mint-page":"/developer-docs/helpers/api-reference/list-data-apps","x-title":"List data apps","security":[{"ServiceToken":[]}],"parameters":[{"name":"isPagination","in":"query","required":false,"schema":{"type":"string","enum":["true"]},"description":"`true` returns 10 data apps per page. Without it you get all."},{"name":"pageNumber","in":"query","required":false,"schema":{"type":"integer","default":1},"description":"Page, from `1`"}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"name":"Customer portal","type":"embedded","createdAt":"2026-11-01T10:00:00.000Z","updatedAt":"2026-11-15T12:30:00.000Z","embedCount":1,"embeds":[{"name":"Sales overview","embedId":"sales-overview","createdAt":"2026-11-10T08:00:00.000Z","updatedAt":"2026-11-10T08:00:00.000Z"}]}]}}}},"400":{"description":"- `AUTHENTICATION_ERROR`: You used a data app API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"You used a data app API token"}}}}},"401":{"description":"- `AUTHENTICATION_ERROR`: You used a data app API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"You used a data app API token"}}}}},"403":{"description":"- `ACCOUNT_DISABLED`: The organization is disabled or locked for deletion. Contact Databrain support\n- `AUTHENTICATION_ERROR`: You used a data app API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"ACCOUNT_DISABLED","message":"The organization is disabled or locked for deletion. Contact Databrain support"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: The list could not be read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"The list could not be read"}}}}}},"x-mint-sections":[{"in":"parameters","heading":"Query","after":"The order is not fixed and there is no total count."}],"x-mint-rest":"## Response\n\n```json\n{\n  \"data\": [\n    {\n      \"name\": \"Customer portal\",\n      \"type\": \"embedded\",\n      \"createdAt\": \"2026-11-01T10:00:00.000Z\",\n      \"updatedAt\": \"2026-11-15T12:30:00.000Z\",\n      \"embedCount\": 1,\n      \"embeds\": [\n        {\n          \"name\": \"Sales overview\",\n          \"embedId\": \"sales-overview\",\n          \"createdAt\": \"2026-11-10T08:00:00.000Z\",\n          \"updatedAt\": \"2026-11-10T08:00:00.000Z\"\n        }\n      ]\n    }\n  ]\n}\n```\n\nOnly embedded data apps are listed. Slack and Microsoft Teams apps are not.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 403 | `AUTHENTICATION_ERROR` | You used a data app API token |\n| 500 | `INTERNAL_SERVER_ERROR` | The list could not be read |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."},"put":{"operationId":"updateDataApp","summary":"Update data app","description":"```bash\ncurl --request PUT https://api.usedatabrain.com/api/v2/data-app \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{ \"name\": \"Customer portal\", \"updateName\": \"Customer portal EU\" }'\n```\n\n## Auth\n\nA service token. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Data App APIs / Data App CRUD"],"x-mint-page":"/developer-docs/helpers/api-reference/update-data-app","x-title":"Update a data app","security":[{"ServiceToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The data app's current name."},"updateName":{"type":"string","description":"The new name. Databrain does not check that it is unique, so pick one no other data app has."},"allowedImportSources":{"type":"array","maxItems":50,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":200},"description":"Organization ids whose dashboard exports this data app's customers may import. Up to 50, each 1 to 200 characters. Replaces the list. `[]` empties it."}},"required":["name"],"additionalProperties":false,"anyOf":[{"required":["updateName"]},{"required":["allowedImportSources"]}]},"example":{"name":"Customer portal","updateName":"Customer portal EU"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"name":"Customer portal EU","allowedImportSources":["org-id-1"]}}}},"400":{"description":"- `AUTHENTICATION_ERROR`: You used a data app API token\n- `INVALID_REQUEST_BODY`: A field is missing or wrong\n- `DATA_APP_NOT_FOUND`: No data app has this `name`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"You used a data app API token"}}}}},"401":{"description":"- `AUTHENTICATION_ERROR`: You used a data app API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"You used a data app API token"}}}}},"403":{"description":"- `ACCOUNT_DISABLED`: The organization is disabled or locked for deletion. Contact Databrain support\n- `AUTHENTICATION_ERROR`: You used a data app API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"ACCOUNT_DISABLED","message":"The organization is disabled or locked for deletion. Contact Databrain support"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: The update failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"The update failed"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body","intro":"Send `name` and at least one of `updateName` or `allowedImportSources`.","after":"Embeds and API tokens stay with the data app when you rename it. Use the new name in later calls."}],"x-mint-rest":"## Response\n\n```json\n{ \"name\": \"Customer portal EU\" }\n```\n\nWhen you send `allowedImportSources`, the response has it too.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | A field is missing or wrong |\n| 400 | `DATA_APP_NOT_FOUND` | No data app has this `name` |\n| 403 | `AUTHENTICATION_ERROR` | You used a data app API token |\n| 500 | `INTERNAL_SERVER_ERROR` | The update failed |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."},"delete":{"operationId":"deleteDataApp","summary":"Delete data app","description":"```bash\ncurl --request DELETE \"https://api.usedatabrain.com/api/v2/data-app?name=Customer%20portal\" \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\"\n```\n\n> [!WARNING]\n> You cannot undo this. The data app's embeds, API tokens, settings and the scheduled reports of its embeds are deleted too. Its API tokens stop working at once, so your app can no longer create guest tokens with them. Dashboards and workspaces stay.\n\n## Auth\n\nA service token. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Data App APIs / Data App CRUD"],"x-mint-page":"/developer-docs/helpers/api-reference/delete-data-app","x-title":"Delete a data app","security":[{"ServiceToken":[]}],"parameters":[{"name":"name","in":"query","required":true,"schema":{"type":"string"},"description":"The data app name."}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"name":"Customer portal"}}}},"400":{"description":"- `AUTHENTICATION_ERROR`: You used a data app API token\n- `INVALID_REQUEST_BODY`: `name` is missing\n- `DATA_APP_NOT_FOUND`: No data app has this name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"You used a data app API token"}}}}},"401":{"description":"- `AUTHENTICATION_ERROR`: You used a data app API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"You used a data app API token"}}}}},"403":{"description":"- `ACCOUNT_DISABLED`: The organization is disabled or locked for deletion. Contact Databrain support\n- `AUTHENTICATION_ERROR`: You used a data app API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"ACCOUNT_DISABLED","message":"The organization is disabled or locked for deletion. Contact Databrain support"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: The delete failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"The delete failed"}}}}}},"x-mint-sections":[{"in":"parameters","heading":"Query"}],"x-mint-rest":"## Response\n\n```json\n{ \"name\": \"Customer portal\" }\n```\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | `name` is missing |\n| 400 | `DATA_APP_NOT_FOUND` | No data app has this name |\n| 403 | `AUTHENTICATION_ERROR` | You used a data app API token |\n| 500 | `INTERNAL_SERVER_ERROR` | The delete failed |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/data-app/api-tokens":{"post":{"operationId":"createApiToken","summary":"Create API token","description":"```bash\ncurl --request POST https://api.usedatabrain.com/api/v2/data-app/api-tokens \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{ \"dataAppName\": \"Customer portal\", \"name\": \"Production backend\" }'\n```\n\n## Before you start\n\n- You have a service token. See [Authentication](/developer-docs/helpers/api-reference/authentication).\n- Your plan includes embedding.","tags":["Data App APIs / API Tokens"],"x-mint-page":"/developer-docs/helpers/api-reference/create-api-token","x-title":"Create an API token","security":[{"ServiceToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dataAppName":{"type":"string","description":"The data app."},"name":{"type":"string","description":"A label for the token. Unique in your organization, in any letter case."}},"required":["dataAppName","name"],"additionalProperties":false},"example":{"dataAppName":"Customer portal","name":"Production backend"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"key":"3f9a1c2e-8b7d-4e6f-9a0b-1c2d3e4f5a6b","keyId":"c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f","keyLast4":"5a6b"}}}},"400":{"description":"- `AUTHENTICATION_ERROR`: You used a data app API token\n- `INVALID_REQUEST_BODY`: A field is missing or unknown\n- `DATA_APP_NOT_FOUND`: No data app has this name\n- `API_TOKEN_NAME_ALREADY_EXISTS`: `An API key with this name already exists. Use a different name.`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"You used a data app API token"}}}}},"401":{"description":"- `AUTHENTICATION_ERROR`: You used a data app API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"You used a data app API token"}}}}},"403":{"description":"- `ACCOUNT_DISABLED`: The organization is disabled or locked for deletion. Contact Databrain support\n- `AUTHENTICATION_ERROR`: You used a data app API token\n- `entitlement_required`: Your plan does not include embedding","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"ACCOUNT_DISABLED","message":"The organization is disabled or locked for deletion. Contact Databrain support"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: Databrain failed. Try again. If it fails again, contact support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"Databrain failed. Try again. If it fails again, contact support"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body"}],"x-mint-rest":"## Response\n\n```json\n{\n  \"key\": \"3f9a1c2e-8b7d-4e6f-9a0b-1c2d3e4f5a6b\",\n  \"keyId\": \"c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f\",\n  \"keyLast4\": \"5a6b\"\n}\n```\n\n| Field | Description |\n| --- | --- |\n| `key` | The API token. You see it only in this response |\n| `keyId` | The public id of the token. It is not a credential |\n| `keyLast4` | The last 4 characters of the token |\n\n> [!WARNING]\n> Store `key` now. Databrain keeps only a hash of it, so no screen or API can show it again. If you lose it, rotate the token in **Data Apps > API tokens** with **Rotate token**, or create a new one.\n\nThe token has the `Access Metrics` and `Access Dashboards` scopes and does not expire.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | A field is missing or unknown |\n| 400 | `DATA_APP_NOT_FOUND` | No data app has this name |\n| 400 | `API_TOKEN_NAME_ALREADY_EXISTS` | `An API key with this name already exists. Use a different name.` |\n| 403 | `AUTHENTICATION_ERROR` | You used a data app API token |\n| 403 | `entitlement_required` | Your plan does not include embedding |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint).\n\nNext, [create a guest token](/developer-docs/helpers/api-reference/token) with it."},"get":{"operationId":"listApiTokens","summary":"List API tokens","description":"```bash\ncurl \"https://api.usedatabrain.com/api/v2/data-app/api-tokens?dataAppName=Customer%20portal\" \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\"\n```\n\n## Auth\n\nA service token. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Data App APIs / API Tokens"],"x-mint-page":"/developer-docs/helpers/api-reference/list-api-tokens","x-title":"List API tokens","security":[{"ServiceToken":[]}],"parameters":[{"name":"dataAppName","in":"query","required":true,"schema":{"type":"string"},"description":"The data app."},{"name":"isPagination","in":"query","required":false,"schema":{"type":"string","enum":["true"]},"description":"`true` returns 10 tokens per page."},{"name":"pageNumber","in":"query","required":false,"schema":{"type":"integer"},"description":"Page, from `1`"}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"key":null,"keyId":"c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f","keyLast4":"5a6b","name":"Production backend","description":"API key for data app Customer portal","createdAt":"2026-11-18T09:00:00.000Z"}]}}}},"400":{"description":"- `AUTHENTICATION_ERROR`: You used a data app API token\n- `INVALID_REQUEST_BODY`: `dataAppName` is missing\n- `DATA_APP_NOT_FOUND`: No data app has this name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"You used a data app API token"}}}}},"401":{"description":"- `AUTHENTICATION_ERROR`: You used a data app API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"You used a data app API token"}}}}},"403":{"description":"- `ACCOUNT_DISABLED`: The organization is disabled or locked for deletion. Contact Databrain support\n- `AUTHENTICATION_ERROR`: You used a data app API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"ACCOUNT_DISABLED","message":"The organization is disabled or locked for deletion. Contact Databrain support"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: Databrain failed. Try again. If it fails again, contact support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"Databrain failed. Try again. If it fails again, contact support"}}}}}},"x-mint-sections":[{"in":"parameters","heading":"Query","after":"Tokens are listed oldest first."}],"x-mint-rest":"## Response\n\n```json\n{\n  \"data\": [\n    {\n      \"key\": null,\n      \"keyId\": \"c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f\",\n      \"keyLast4\": \"5a6b\",\n      \"name\": \"Production backend\",\n      \"description\": \"API key for data app Customer portal\",\n      \"createdAt\": \"2026-11-18T09:00:00.000Z\"\n    }\n  ]\n}\n```\n\n| Field | Description |\n| --- | --- |\n| `keyId` | The public id of the token. It is not a credential |\n| `keyLast4` | The last 4 characters of the token |\n| `key` | Deprecated. `null` for every token made since tokens are stored as a hash. The full token only for an older token |\n| `name`, `description`, `createdAt` | The token's label, description and creation time |\n\n> [!WARNING]\n> `key` will be removed. Use `keyId` and `keyLast4`. Every successful response has a `Deprecation` header and a `Sunset` header; the `Sunset` header gives the removal date. Until then the list can return the full value of an older token, so keep the response out of logs.\n\nThe list does not say whether a token is expired.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | `dataAppName` is missing |\n| 400 | `DATA_APP_NOT_FOUND` | No data app has this name |\n| 403 | `AUTHENTICATION_ERROR` | You used a data app API token |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/data-app/rotate-api":{"post":{"operationId":"rotateApiKey","summary":"Rotate API token","description":"You call it with the token you want to replace. You get a new token, and the old one keeps working for `expireAt` seconds. `POST /api/v2/data-app/api-tokens/rotate` does the same.\n\n```bash\ncurl --request POST https://api.usedatabrain.com/api/v2/data-app/rotate-api \\\n  --header \"Authorization: Bearer $DATABRAIN_API_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{ \"expireAt\": 3600 }'\n```\n\n## Auth\n\nThe data app API token to rotate. A service token gets `400 INVALID_DATA_APP_API_KEY`. See [Authentication](/developer-docs/helpers/api-reference/authentication).\n\nYou need the current token. If you lost it, select **Rotate token** in **Data Apps > API tokens**, or create a new token.","tags":["Data App APIs / API Tokens"],"x-mint-page":"/developer-docs/helpers/api-reference/rotate-api-key","x-title":"Rotate an API token","security":[{"DataAppApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expireAt":{"anyOf":[{"type":"number"},{"type":"string"}],"description":"How many seconds the old token keeps working. `0` stops it at once. Not a date.","type":"number"}},"required":["expireAt"],"additionalProperties":false},"example":{"expireAt":3600}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"key":"7d2e4f6a-1b3c-4d5e-8f9a-0b1c2d3e4f5a","keyId":"e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b","keyLast4":"4f5a"}}}},"400":{"description":"- `AUTHENTICATION_ERROR`: No `Authorization: Bearer` header, or the token is not a UUID. Send `Authorization: Bearer <token>`\n- `INVALID_DATA_APP_API_KEY`: You used a service token, or the token is already being replaced\n- `INVALID_REQUEST_BODY`: `expireAt` is missing\n- `API_TOKEN_NAME_ALREADY_EXISTS`: Another token already has the name the new token would get. Rename or delete it, then rotate again\n- `INTERNAL_SERVER_ERROR`: The rotation failed. The old token still works","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"No `Authorization: Bearer` header, or the token is not a UUID. Send `Authorization: Bearer <token>`"}}}}},"401":{"description":"- `AUTHENTICATION_ERROR`: The token is unknown, revoked or expired. Use a current token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"The token is unknown, revoked or expired. Use a current token"}}}}},"403":{"description":"- `ACCOUNT_DISABLED`: The organization is disabled or locked for deletion. Contact Databrain support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"ACCOUNT_DISABLED","message":"The organization is disabled or locked for deletion. Contact Databrain support"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: The rotation failed. The old token still works","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"The rotation failed. The old token still works"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body"}],"x-mint-rest":"## Response\n\n```json\n{\n  \"key\": \"7d2e4f6a-1b3c-4d5e-8f9a-0b1c2d3e4f5a\",\n  \"keyId\": \"e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b\",\n  \"keyLast4\": \"4f5a\"\n}\n```\n\n| Field | Description |\n| --- | --- |\n| `key` | The new token. You see it only in this response |\n| `keyId` | The public id of the new token |\n| `keyLast4` | The last 4 characters of the new token |\n\nThe new token gets the old token's name. The old token is renamed `<name> (replaced <date> UTC)` and expires after `expireAt` seconds. A token that is already being replaced cannot be rotated again.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | `expireAt` is missing |\n| 400 | `INVALID_DATA_APP_API_KEY` | You used a service token, or the token is already being replaced |\n| 400 | `API_TOKEN_NAME_ALREADY_EXISTS` | Another token already has the name the new token would get. Rename or delete it, then rotate again |\n| 500 | `INTERNAL_SERVER_ERROR` | The rotation failed. The old token still works |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/data-app/dashboards":{"get":{"operationId":"fetchDashboardsByDatapp","summary":"Fetch dashboards","description":"```bash\ncurl \"https://api.usedatabrain.com/api/v2/data-app/dashboards?dashboardNames=Sales%20overview,Churn\" \\\n  --header \"Authorization: Bearer $DATABRAIN_API_TOKEN\"\n```\n\n## Auth\n\nA data app API token. A service token gets `400 INVALID_DATA_APP_API_KEY`. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Data App APIs / Data Retrieval"],"x-mint-page":"/developer-docs/helpers/api-reference/fetch-dashboards-by-datapp","x-title":"Fetch dashboards by data app","security":[{"DataAppApiToken":[]}],"parameters":[{"name":"dashboardNames","in":"query","required":false,"schema":{"type":"string"},"description":"Dashboard names, split by commas with no spaces around them. Only these are returned."},{"name":"isPagination","in":"query","required":false,"schema":{"type":"string","enum":["true"]},"description":"`true` returns 10 rows per page."},{"name":"pageNumber","in":"query","required":false,"schema":{"type":"integer","default":1},"description":"Page, from `1`"}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"name":"Sales overview","externalDashboardId":"sales-overview","embedId":"sales-overview"}]}}}},"400":{"description":"- `AUTHENTICATION_ERROR`: No `Authorization: Bearer` header, or the token is not a UUID. Send `Authorization: Bearer <token>`\n- `INVALID_REQUEST_BODY`: A field is wrong or unknown\n- `INVALID_DATA_APP_API_KEY`: You used a service token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"No `Authorization: Bearer` header, or the token is not a UUID. Send `Authorization: Bearer <token>`"}}}}},"401":{"description":"- `AUTHENTICATION_ERROR`: The token is unknown, revoked or expired. Use a current token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"The token is unknown, revoked or expired. Use a current token"}}}}},"403":{"description":"- `ACCOUNT_DISABLED`: The organization is disabled or locked for deletion. Contact Databrain support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"ACCOUNT_DISABLED","message":"The organization is disabled or locked for deletion. Contact Databrain support"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: The list could not be read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"The list could not be read"}}}}}},"x-mint-sections":[{"in":"parameters","heading":"Query","after":"`POST /api/v2/data-app/dashboards` does the same with a JSON body: `{ \"isPagination\": true, \"pageNumber\": 1, \"filters\": { \"dashboardNames\": [\"Sales overview\"] } }`."}],"x-mint-rest":"## Response\n\n```json\n{\n  \"data\": [\n    { \"name\": \"Sales overview\", \"externalDashboardId\": \"sales-overview\", \"embedId\": \"sales-overview\" }\n  ]\n}\n```\n\nThere is one row per dashboard embed. A dashboard with two embeds is listed twice. The order is not fixed.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | A field is wrong or unknown |\n| 400 | `INVALID_DATA_APP_API_KEY` | You used a service token |\n| 500 | `INTERNAL_SERVER_ERROR` | The list could not be read |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/data-app/metrics":{"get":{"operationId":"fetchMetricsByEmbedAndClient","summary":"Fetch metrics","description":"```bash\ncurl \"https://api.usedatabrain.com/api/v2/data-app/metrics?embedId=sales-overview&clientId=acme\" \\\n  --header \"Authorization: Bearer $DATABRAIN_API_TOKEN\"\n```\n\n## Auth\n\nA data app API token. A service token gets `400 INVALID_DATA_APP_API_KEY`. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Data App APIs / Data Retrieval"],"x-mint-page":"/developer-docs/helpers/api-reference/fetch-metrics-by-embed-and-client","x-title":"Fetch metrics by embed","security":[{"DataAppApiToken":[]}],"parameters":[{"name":"embedId","in":"query","required":true,"schema":{"type":"string"},"description":"The **dashboard id** of the embed (`dashboardId` in [List embeds](/developer-docs/helpers/api-reference/list-embed)). For an embed id with a `__` suffix, send the dashboard id without it."},{"name":"clientId","in":"query","required":true,"schema":{"type":"string"},"description":"The customer. Metrics a customer made show only to that customer."},{"name":"userIdentifier","in":"query","required":false,"schema":{"type":"string"},"description":"Only metrics this user made."},{"name":"isMetric","in":"query","required":false,"schema":{"type":"string","enum":["true"]},"description":"`true` returns only saved metrics."},{"name":"isPagination","in":"query","required":false,"schema":{"type":"string","enum":["true"]},"description":"`true` pages the dashboard's metrics, 10 at a time."},{"name":"pageNumber","in":"query","required":false,"schema":{"type":"integer"},"description":"Page, from `1`"}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"externalMetricId":"9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a","metricId":"b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e","name":"Monthly revenue","isPublished":true,"createdByUser":null,"editable":false}]}}}},"400":{"description":"- `AUTHENTICATION_ERROR`: No `Authorization: Bearer` header, or the token is not a UUID. Send `Authorization: Bearer <token>`\n- `INVALID_REQUEST_BODY`: `embedId` or `clientId` is missing or empty\n- `INVALID_DATA_APP_API_KEY`: You used a service token\n- `EMBED_PARAM_ERROR`: No embed of this data app has this dashboard id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"No `Authorization: Bearer` header, or the token is not a UUID. Send `Authorization: Bearer <token>`"}}}}},"401":{"description":"- `AUTHENTICATION_ERROR`: The token is unknown, revoked or expired. Use a current token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"The token is unknown, revoked or expired. Use a current token"}}}}},"403":{"description":"- `ACCOUNT_DISABLED`: The organization is disabled or locked for deletion. Contact Databrain support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"ACCOUNT_DISABLED","message":"The organization is disabled or locked for deletion. Contact Databrain support"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: The list could not be read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"The list could not be read"}}}}}},"x-mint-sections":[{"in":"parameters","heading":"Query","after":"Pages are cut before the filters run, so a page can have fewer than 10 metrics, or none, when later pages have more. Read pages until one is empty.\n\n`POST /api/v2/data-app/metrics` does the same with the same fields in a JSON body."}],"x-mint-rest":"## Response\n\n```json\n{\n  \"data\": [\n    {\n      \"externalMetricId\": \"9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a\",\n      \"metricId\": \"b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e\",\n      \"name\": \"Monthly revenue\",\n      \"isPublished\": true,\n      \"createdByUser\": null,\n      \"editable\": false\n    }\n  ]\n}\n```\n\n| Field | Description |\n| --- | --- |\n| `metricId` | The metric id |\n| `externalMetricId` | Internal id of the metric row |\n| `isPublished` | `true` for every metric you made. For a customer's metric, whether it is published |\n| `createdByUser` | The `userIdentifier` of the user who made it, or `null` |\n| `editable` | `true` when this customer made the metric |\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | `embedId` or `clientId` is missing or empty |\n| 400 | `INVALID_DATA_APP_API_KEY` | You used a service token |\n| 400 | `EMBED_PARAM_ERROR` | No embed of this data app has this dashboard id |\n| 500 | `INTERNAL_SERVER_ERROR` | The list could not be read |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/data-app/query":{"post":{"operationId":"fetchMetricDataByDataapp","summary":"Query metric data","description":"Databrain runs the metric of a metric embed for the tenant in `clientId` and returns the rows. No guest token is used.\n\n```bash\ncurl --request POST https://api.usedatabrain.com/api/v2/data-app/query \\\n  --header \"Authorization: Bearer $DATABRAIN_API_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\n    \"dataAppId\": \"7c8d9e0f-1a2b-4c3d-8e4f-5a6b7c8d9e0f\",\n    \"embedId\": \"monthly-revenue\",\n    \"metricId\": \"b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e\",\n    \"clientId\": \"acme\"\n  }'\n```\n\n## Auth\n\nA data app API token, or a service token. With a service token, `dataAppId` picks the data app. With a data app API token, its own data app is used. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Data App APIs / Data Retrieval"],"x-mint-page":"/developer-docs/helpers/api-reference/fetch-metric-data-by-dataapp","x-title":"Query a metric","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dataAppId":{"type":"string","description":"The data app id (`dataAppId` in [List embeds](/developer-docs/helpers/api-reference/list-embed)). With a data app API token it must be that token's data app."},"embedId":{"type":"string","description":"The embed id of a **metric** embed."},"metricId":{"type":"string","description":"The metric id. The embed decides which metric runs; this value is not used to pick it."},"clientId":{"type":"string","description":"The tenant whose rows you get."},"dashboardFilter":{"description":"Dashboard filter values: `{ \"tableName\": \"...\", \"filters\": [ ... ] }`"},"metricFilter":{"description":"Row conditions on the metric."},"datasourceName":{"type":"string","description":"Multi-datasource workspaces: the datasource to query."},"dataMartName":{"type":"string","description":"Multi-datamart workspaces: the datamart to query."}},"required":["dataAppId","embedId","clientId","metricId"],"additionalProperties":false},"example":{"dataAppId":"7c8d9e0f-1a2b-4c3d-8e4f-5a6b7c8d9e0f","embedId":"monthly-revenue","metricId":"b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e","clientId":"acme"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"month":"2026-10","revenue":182340.5},{"month":"2026-11","revenue":194112}],"timeTaken":412,"comparisonValue":null,"totalRecords":2,"metaData":{"groupbyColumnList":["month"]}}}}},"400":{"description":"- `AUTHENTICATION_ERROR`: No `Authorization: Bearer` header, or the token is not a UUID. Send `Authorization: Bearer <token>`\n- `INVALID_REQUEST_BODY`: A field is missing or unknown\n- `INVALID_EMBED_ID`: No embed of this data app has this id\n- `INVALID_METRIC_ID`: The embed is a dashboard embed, not a metric embed\n- `DATASOURCE_NAME_ERROR`: The datasource or datamart name is unknown\n- `DATAMART_NAME_ERROR`: The datasource or datamart name is unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"No `Authorization: Bearer` header, or the token is not a UUID. Send `Authorization: Bearer <token>`"}}}}},"401":{"description":"- `AUTHENTICATION_ERROR`: The token is unknown, revoked or expired. Use a current token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"The token is unknown, revoked or expired. Use a current token"}}}}},"403":{"description":"- `ACCOUNT_DISABLED`: The organization is disabled or locked for deletion. Contact Databrain support\n- `DATA_APP_ID_ERROR`: `dataAppId` is not the data app of your API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"ACCOUNT_DISABLED","message":"The organization is disabled or locked for deletion. Contact Databrain support"}}}}},"404":{"description":"- `DATA_APP_NOT_FOUND`: No data app in your organization has this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"DATA_APP_NOT_FOUND","message":"No data app in your organization has this id"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: The request failed, for example `dataAppId` is not a UUID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"The request failed, for example `dataAppId` is not a UUID"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body","intro":"Unknown fields are refused, `timezone` too."}],"x-mint-rest":"## Response\n\n```json\n{\n  \"data\": [\n    { \"month\": \"2026-10\", \"revenue\": 182340.5 },\n    { \"month\": \"2026-11\", \"revenue\": 194112.0 }\n  ],\n  \"timeTaken\": 412,\n  \"metaData\": { \"groupbyColumnList\": [\"month\"] }\n}\n```\n\n| Field | Description |\n| --- | --- |\n| `data` | The rows. Up to the metric's own row limit, or 10,000 |\n| `timeTaken` | Query time in milliseconds |\n| `metaData.groupbyColumnList` | The group-by columns |\n| `metaData.rowsTruncated`, `metaData.rowLimit` | Set when rows were cut at the limit |\n| `comparisonValue` | `{ \"mainValue\", \"compareValue\" }` for a single-value metric with a comparison |\n| `totalRecords` | Total row count, when the metric has one |\n\n> [!WARNING]\n> When the warehouse query fails, you still get `200` with `data: []`. An empty `data` can mean no rows or a failed query. Check the metric in the app if you expect rows.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | A field is missing or unknown |\n| 400 | `INVALID_EMBED_ID` | No embed of this data app has this id |\n| 400 | `INVALID_METRIC_ID` | The embed is a dashboard embed, not a metric embed |\n| 400 | `DATASOURCE_NAME_ERROR` or `DATAMART_NAME_ERROR` | The datasource or datamart name is unknown |\n| 403 | `DATA_APP_ID_ERROR` | `dataAppId` is not the data app of your API token |\n| 404 | `DATA_APP_NOT_FOUND` | No data app in your organization has this id |\n| 500 | `INTERNAL_SERVER_ERROR` | The request failed, for example `dataAppId` is not a UUID |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/data-app/getDashboardPdf":{"post":{"operationId":"getDashboardPdf","summary":"Dashboard PDF","description":"```bash\ncurl --request POST https://api.usedatabrain.com/api/v2/data-app/getDashboardPdf \\\n  --header \"Authorization: Bearer $DATABRAIN_API_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\n    \"dataAppId\": \"7c8d9e0f-1a2b-4c3d-8e4f-5a6b7c8d9e0f\",\n    \"embedId\": \"sales-overview\",\n    \"dashboardId\": \"sales-overview\",\n    \"clientId\": \"acme\",\n    \"pageSetup\": { \"orientation\": \"landscape\" }\n  }' \\\n  --output sales-overview.pdf\n```\n\n## Auth\n\nA data app API token, or a service token. With a service token, `dataAppId` picks the data app. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Data App APIs / Data Retrieval"],"x-mint-page":"/developer-docs/helpers/api-reference/get-dashboard-pdf","x-title":"Download a dashboard as PDF","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dataAppId":{"type":"string","description":"The data app id. With a data app API token it must be that token's data app."},"embedId":{"type":"string","description":"The embed id."},"dashboardId":{"type":"string","description":"The embed's dashboard id. This picks the dashboard."},"clientId":{"type":"string","description":"The tenant whose data is shown."},"datasourceName":{"type":"string","description":"Multi-datasource workspaces: the datasource."},"dataMartName":{"type":"string","description":"Multi-datamart workspaces: the datamart."},"pageSetup":{"type":"object","properties":{"orientation":{"type":"string","enum":["landscape","portrait"],"description":"One of `landscape`, `portrait`. Page orientation."},"density":{"type":"string","enum":["auto","one-up","two-up"],"description":"One of `auto`, `one-up`, `two-up`. Charts per row."},"tableMode":{"type":"string","enum":["paginate","all"],"description":"One of `paginate`, `all`. Split long tables over pages, or show all rows."},"tableRowCap":{"type":"integer","minimum":0,"description":"One of integer from 0. Rows per table."},"hardRowCeiling":{"type":"integer","minimum":1,"description":"One of integer from 1. Most rows in the whole file."}},"additionalProperties":false,"description":"Page size and table limits of the PDF."}},"required":["dataAppId","embedId","dashboardId","clientId"],"additionalProperties":false},"example":{"dataAppId":"7c8d9e0f-1a2b-4c3d-8e4f-5a6b7c8d9e0f","embedId":"sales-overview","dashboardId":"sales-overview","clientId":"acme","pageSetup":{"orientation":"landscape"}}}}},"responses":{"200":{"description":"Success","content":{"application/pdf":{"example":"<binary PDF>"}}},"400":{"description":"- `AUTHENTICATION_ERROR`: No `Authorization: Bearer` header, or the token is not a UUID. Send `Authorization: Bearer <token>`\n- `INVALID_REQUEST_BODY`: A field is missing or wrong\n- `INVALID_DASHBOARD_ID`: No embed of the data app has this dashboard\n- `DATASOURCE_NAME_ERROR`: The name is unknown\n- `DATAMART_NAME_ERROR`: The name is unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"No `Authorization: Bearer` header, or the token is not a UUID. Send `Authorization: Bearer <token>`"}}}}},"401":{"description":"- `AUTHENTICATION_ERROR`: The token is unknown, revoked or expired. Use a current token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"The token is unknown, revoked or expired. Use a current token"}}}}},"403":{"description":"- `ACCOUNT_DISABLED`: The organization is disabled or locked for deletion. Contact Databrain support\n- `DATA_APP_ID_ERROR`: `dataAppId` is not the data app of your API token\n- `INVALID_REQUEST_BODY`: A field is missing or wrong","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"ACCOUNT_DISABLED","message":"The organization is disabled or locked for deletion. Contact Databrain support"}}}}},"404":{"description":"- `DATA_APP_NOT_FOUND`: No data app in your organization has this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"DATA_APP_NOT_FOUND","message":"No data app in your organization has this id"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: The PDF could not be made","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"The PDF could not be made"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body"}],"x-mint-rest":"## Response\n\nThe PDF file, with `Content-Type: application/pdf`.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | A field is missing or wrong |\n| 400 | `INVALID_DASHBOARD_ID` | No embed of the data app has this dashboard |\n| 400 | `DATASOURCE_NAME_ERROR` or `DATAMART_NAME_ERROR` | The name is unknown |\n| 403 | `DATA_APP_ID_ERROR` | `dataAppId` is not the data app of your API token |\n| 404 | `DATA_APP_NOT_FOUND` | No data app in your organization has this id |\n| 500 | `INTERNAL_SERVER_ERROR` | The PDF could not be made |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/data-app/ask":{"post":{"operationId":"askQuestion","summary":"Ask a question","description":"Bryn turns the question into SQL on a datamart or a workspace, runs it and returns the answer.\n\n```bash\ncurl --request POST https://api.usedatabrain.com/api/v2/data-app/ask \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{ \"question\": \"Revenue by month this year\", \"datamartName\": \"Sales\", \"timezone\": \"America/New_York\" }'\n```\n\n## Before you start\n\n- You have a service token. A data app API token gets `403`. See [Authentication](/developer-docs/helpers/api-reference/authentication).\n- Each question uses AI credits of your plan.\n- The datamart has no tenancy, or `TABLE` tenancy. Datamarts with a schema or database per tenant are refused, because the call has no tenant.","tags":["Data App APIs / Data Retrieval"],"x-mint-page":"/developer-docs/helpers/api-reference/ask-question","x-title":"Ask a question","security":[{"ServiceToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"question":{"type":"string","description":"The question."},"datamartName":{"type":"string","description":"Send this or the other one of the pair. The datamart to ask."},"workspaceName":{"type":"string","description":"Send this or the other one of the pair. The workspace to ask."},"timezone":{"type":"string","description":"IANA time zone for dates. Default `UTC`","default":"UTC"},"sessionId":{"type":"string","description":"The `sessionId` of an earlier answer, to keep the conversation."},"config":{"type":"object","properties":{"followUp":{"type":"object","properties":{"isEnable":{"type":"boolean","description":"`true` treats this question as a follow-up to the previous one.","x-mint-extra":true},"previousQuestion":{"type":"string","default":"","description":"The previous question.","x-mint-extra":true},"previousSql":{"type":"string","default":"","description":"The SQL of the previous answer.","x-mint-extra":true}},"required":["isEnable"],"additionalProperties":false,"description":"`{ \"isEnable\": true, \"previousQuestion\": \"...\", \"previousSql\": \"...\" }` to ask a follow-up."}},"additionalProperties":false,"description":"Follow-up settings."},"datasourceName":{"type":"string","description":"Accepted, but not used. Name the datamart or the workspace instead.","x-mint-extra":true}},"required":["question"],"additionalProperties":false,"anyOf":[{"required":["datamartName"]},{"required":["workspaceName"]}]},"example":{"question":"Revenue by month this year","datamartName":"Sales","timezone":"America/New_York"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":{"data":[{"month":"2026-01","revenue":120400}],"columns":{"dimensions":["month"],"measures":["revenue"]},"suggestedChartType":"line","chartSettings":null,"chartTypeReason":null,"reasoning":"...","confidence":null,"timeTaken":3120,"sessionId":"5f6e7d8c-...","summary":"Revenue grew each month.","query":"SELECT ...","isTimeSeries":true,"isCountryDimension":false,"questionType":null},"_optionalKeys":"semantic, verified, verifyReason, assumptions, sqlFacts appear only when the pipeline reports them"}}}},"400":{"description":"- `AUTHENTICATION_ERROR`: No workspace has this name\n- `INVALID_REQUEST_BODY`: `question` is missing, neither name was sent, or nothing matched them\n- `WORKSPACE_HAS_NO_DATASOURCE`: The workspace has no datasource\n- `INVALID_DATAMART`: No datamart has this name\n- `DATABASE_TENANCY_REQUIRES_CLIENT`: The datamart has a schema or database per tenant\n- `NOT_DATA_QUESTION`: The question is not about your data\n- `QUERY_REFUSED`: Bryn would not run the query. The body has a `refusal` object that says why\n- `FORECAST_LLM_INVALID_REQUEST`: The AI model refused the request.\n- `FORECAST_CONTEXT_LIMIT_EXCEEDED`: The question and its context are too large for the AI model.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"No workspace has this name"}}}}},"401":{"description":"- `AUTHENTICATION_ERROR`: No workspace has this name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"No workspace has this name"}}}}},"402":{"description":"- `FORECAST_LLM_BILLING_BLOCKED`: The AI model account cannot take requests now (billing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"FORECAST_LLM_BILLING_BLOCKED","message":"The AI model account cannot take requests now (billing)."}}}}},"403":{"description":"- `ACCOUNT_DISABLED`: The organization is disabled or locked for deletion. Contact Databrain support\n- `AUTHENTICATION_ERROR`: You used a data app API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"ACCOUNT_DISABLED","message":"The organization is disabled or locked for deletion. Contact Databrain support"}}}}},"429":{"description":"- `FORECAST_LLM_RATE_LIMIT`: The AI model is busy. Wait and try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"FORECAST_LLM_RATE_LIMIT","message":"The AI model is busy. Wait and try again."}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: `Query generation failed due to an internal error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"`Query generation failed due to an internal error`"}}}}},"503":{"description":"- `SEMANTIC_EXECUTION_FAILED`: The query failed. Try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"SEMANTIC_EXECUTION_FAILED","message":"The query failed. Try again"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body","intro":"Send `question` and at least one of `datamartName` or `workspaceName`."}],"x-mint-rest":"## Response\n\n```json\n{\n  \"data\": {\n    \"data\": [{ \"month\": \"2026-01\", \"revenue\": 120400 }],\n    \"columns\": { \"dimensions\": [\"month\"], \"measures\": [\"revenue\"] },\n    \"query\": \"SELECT ...\",\n    \"summary\": \"Revenue grew each month.\",\n    \"suggestedChartType\": \"line\",\n    \"reasoning\": \"...\",\n    \"isTimeSeries\": true,\n    \"sessionId\": \"5f6e7d8c-...\",\n    \"timeTaken\": 3120\n  }\n}\n```\n\n| Field | Description |\n| --- | --- |\n| `data` | The rows |\n| `columns` | Which columns are dimensions and which are measures |\n| `query` | The SQL that ran |\n| `summary` | A short answer in words |\n| `suggestedChartType` | A chart type that fits the rows |\n| `sessionId` | Send it back for a follow-up |\n\nThe response can have more fields, such as `confidence`, `assumptions`, `chartSettings` and `verified`.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | `question` is missing, neither name was sent, or nothing matched them |\n| 400 | `INVALID_DATAMART` | No datamart has this name |\n| 400 | `AUTHENTICATION_ERROR` | No workspace has this name |\n| 400 | `DATABASE_TENANCY_REQUIRES_CLIENT` | The datamart has a schema or database per tenant |\n| 400 | `WORKSPACE_HAS_NO_DATASOURCE` | The workspace has no datasource |\n| 400 | `NOT_DATA_QUESTION` | The question is not about your data |\n| 400 | `QUERY_REFUSED` | Bryn would not run the query. The body has a `refusal` object that says why |\n| 403 | `AUTHENTICATION_ERROR` | You used a data app API token |\n| 503 | `SEMANTIC_EXECUTION_FAILED` | The query failed. Try again |\n| 500 | `INTERNAL_SERVER_ERROR` | `Query generation failed due to an internal error` |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/data-app/chart-preview":{"post":{"operationId":"chartPreview","summary":"Preview chart","description":"Use it to show the answer of [Ask a question](/developer-docs/helpers/api-reference/ask-question) as a chart. Nothing is saved and no query runs: you send the rows.\n\n```bash\ncurl --request POST https://api.usedatabrain.com/api/v2/data-app/chart-preview \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\n    \"chartType\": \"line\",\n    \"title\": \"Revenue by month\",\n    \"xAxis\": \"month\",\n    \"yAxis\": [\"revenue\"],\n    \"rows\": [{ \"month\": \"2026-10\", \"revenue\": 182340 }, { \"month\": \"2026-11\", \"revenue\": 194112 }]\n  }'\n```\n\n## Auth\n\nA service token only. See [Authentication](/developer-docs/helpers/api-reference/authentication).\n\n## Limits\n\n120 requests a minute per token.","tags":["Data App APIs / Data Retrieval"],"x-mint-page":"/developer-docs/helpers/api-reference/chart-preview","x-title":"Preview a chart","security":[{"ServiceToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object"},"description":"The rows to draw. A JSON string of the array also works."},"chartType":{"type":"string","description":"The chart type, for example `line`, 1 to 80 characters."},"title":{"type":"string","description":"Up to 500 characters.","default":""},"xAxis":{"type":"string","description":"Column for the x axis."},"yAxis":{"type":"array","items":{"type":"string"},"description":"Columns for the y axis, up to 10."},"seriesField":{"type":"string","description":"Column that splits the series."},"singleValue":{"type":"string","description":"Column for a single-value chart."},"dimensions":{"type":"array","items":{"type":"string"},"description":"Up to 20 each.","default":[]},"measures":{"type":"array","items":{"type":"string"},"description":"Up to 20 each.","default":[]},"width":{"type":"integer","description":"240 to 1200. Default `600`","default":600},"height":{"type":"integer","description":"120 to 800. Default `320`","default":320}},"required":["rows","chartType"]},"example":{"chartType":"line","title":"Revenue by month","xAxis":"month","yAxis":["revenue"],"rows":[{"month":"2026-10","revenue":182340},{"month":"2026-11","revenue":194112}]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"kind":"chart","title":"Revenue by month","chartSpec":{"type":"line"},"columns":["month","revenue"],"rows":[{"month":"2026-10","revenue":182340},{"month":"2026-11","revenue":194112}],"width":600,"height":320,"points":[],"svg":"<svg ...>...</svg>"}}}},"400":{"description":"- `AUTHENTICATION_ERROR`: You used a data app API token\n- `INVALID_PREVIEW_REQUEST`: A field is missing or out of range\n- `INVALID_CHART_CONFIG`: The columns do not fit the chart type\n- `UNSUPPORTED_CHART_TYPE`: The `chartType` is not one the preview can draw.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"You used a data app API token"}}}}},"401":{"description":"- `AUTHENTICATION_ERROR`: You used a data app API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"You used a data app API token"}}}}},"403":{"description":"- `ACCOUNT_DISABLED`: The organization is disabled or locked for deletion. Contact Databrain support\n- `AUTHENTICATION_ERROR`: You used a data app API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"ACCOUNT_DISABLED","message":"The organization is disabled or locked for deletion. Contact Databrain support"}}}}},"413":{"description":"- `CHART_DATA_TOO_LARGE`: Too much data: more than 1000 rows, more than 20 keys in a row, a key longer than 128 characters, or more than 2,000,000 characters in all.\n- `UNSUPPORTED_CHART_CELL`: A cell is an object, an array, a number that is not finite, or text longer than 2000 characters.\n- `CHART_PAGE_TOO_LARGE`: The drawn chart is too large to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"CHART_DATA_TOO_LARGE","message":"Too much data: more than 1000 rows, more than 20 keys in a row, a key longer than 128 characters, or more than 2,000,000 characters in all."}}}}},"429":{"description":"- More than 120 requests in a minute. The body is plain text.\n- Over 120 requests a minute","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"message":"More than 120 requests in a minute. The body is plain text."}}}}},"503":{"description":"- `INVALID_QUERY_RESULT`: `rows` is not a list of objects, or the text is not JSON.\n- `CHART_UNAVAILABLE`: The chart could not be drawn. Try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_QUERY_RESULT","message":"`rows` is not a list of objects, or the text is not JSON."}}}}}},"x-mint-sections":[{"in":"body","heading":"Body"}],"x-mint-rest":"## Response\n\n```json\n{\n  \"kind\": \"chart\",\n  \"title\": \"Revenue by month\",\n  \"chartSpec\": { \"type\": \"line\" },\n  \"columns\": [\"month\", \"revenue\"],\n  \"rows\": [{ \"month\": \"2026-10\", \"revenue\": 182340 }, { \"month\": \"2026-11\", \"revenue\": 194112 }],\n  \"width\": 600,\n  \"height\": 320,\n  \"points\": [],\n  \"svg\": \"<svg ...>...</svg>\"\n}\n```\n\n| Field | Description |\n| --- | --- |\n| `kind` | `chart`, `kpi` or `table` |\n| `svg` | The chart as an SVG string. Put it in your page as is |\n| `value` | For a `kpi`: the single value |\n| `rows`, `columns` | The rows that were drawn |\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_PREVIEW_REQUEST` | A field is missing or out of range |\n| 400 | `INVALID_CHART_CONFIG` | The columns do not fit the chart type |\n| 403 | `AUTHENTICATION_ERROR` | You used a data app API token |\n| 429 | | Over 120 requests a minute |\n| 503 | `CHART_UNAVAILABLE` | The chart could not be drawn. Try again |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/data-app/export-dashboard":{"post":{"operationId":"exportDashboard","summary":"Export dashboard","description":"```bash\ncurl --request POST https://api.usedatabrain.com/api/v2/data-app/export-dashboard \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{ \"dashboardId\": \"sales-overview\", \"workspaceName\": \"Customer analytics\" }' \\\n  --output dashboard-sales-overview.json\n```\n\n## Auth\n\nA service token only. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Data App APIs / Data Retrieval"],"x-mint-page":"/developer-docs/helpers/api-reference/export-dashboard","x-title":"Export a dashboard","security":[{"ServiceToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dashboardId":{"type":"string","description":"The dashboard's `externalDashboardId`. It must be unique in your organization: the workspace does not pick it."},"workspaceName":{"type":"string","description":"Written into the file's `_meta` for you."},"sourceClientId":{"type":"string","minLength":1,"description":"Export the dashboard as this customer sees it, with their layout."}},"required":["dashboardId"],"additionalProperties":false},"example":{"dashboardId":"sales-overview","workspaceName":"Customer analytics"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"_meta":{"exportedAt":"2026-11-19T10:00:00.000Z","metricList":[{"name":"Monthly revenue","id":"b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e"}],"dashboardFilterList":[{"name":"Region","id":"f1e2d3c4-..."}],"workspaceName":"Customer analytics","dashboardId":"sales-overview"},"data":{}}}}},"400":{"description":"- `AUTHENTICATION_ERROR`: You used a data app API token\n- `INVALID_REQUEST_BODY`: `dashboardId` is missing\n- `INVALID_DASHBOARD_ID_OR_WORKSPACE_NAME`: No dashboard has this id\n- `CLIENT_ID_ERROR`: The `sourceClientId` is not a customer of this dashboard's workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"You used a data app API token"}}}}},"401":{"description":"- `AUTHENTICATION_ERROR`: You used a data app API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"You used a data app API token"}}}}},"403":{"description":"- `ACCOUNT_DISABLED`: The organization is disabled or locked for deletion. Contact Databrain support\n- `AUTHENTICATION_ERROR`: You used a data app API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"ACCOUNT_DISABLED","message":"The organization is disabled or locked for deletion. Contact Databrain support"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: The export failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"The export failed"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body"}],"x-mint-rest":"## Response\n\nA file download: `Content-Disposition: attachment; filename=\"dashboard-<dashboardId>.json\"`.\n\n```json\n{\n  \"_meta\": {\n    \"exportedAt\": \"2026-11-19T10:00:00.000Z\",\n    \"dashboardId\": \"sales-overview\",\n    \"workspaceName\": \"Customer analytics\",\n    \"metricList\": [{ \"name\": \"Monthly revenue\", \"id\": \"b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e\" }],\n    \"dashboardFilterList\": [{ \"name\": \"Region\", \"id\": \"f1e2d3c4-...\" }]\n  },\n  \"data\": { }\n}\n```\n\n`data` is the dashboard, with its values encrypted. Do not edit it. Pass the whole file to [Import a dashboard](/developer-docs/helpers/api-reference/import-dashboard).\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | `dashboardId` is missing |\n| 400 | `INVALID_DASHBOARD_ID_OR_WORKSPACE_NAME` | No dashboard has this id |\n| 400 | `CLIENT_ID_ERROR` | The `sourceClientId` is not a customer of this dashboard's workspace |\n| 403 | `AUTHENTICATION_ERROR` | You used a data app API token |\n| 500 | `INTERNAL_SERVER_ERROR` | The export failed |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/data-app/import-dashboard":{"post":{"operationId":"importDashboard","summary":"Import dashboard","description":"Databrain makes the dashboard with its metrics, filters and layout in the workspace you name.\n\n```bash\ncurl --request POST https://api.usedatabrain.com/api/v2/data-app/import-dashboard \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data \"{\n    \\\"workspaceName\\\": \\\"Customer analytics EU\\\",\n    \\\"dashboardId\\\": \\\"sales-overview-eu\\\",\n    \\\"schemaPairs\\\": [{ \\\"replaceSchema\\\": \\\"public\\\", \\\"targetSchema\\\": \\\"eu\\\" }],\n    \\\"importDashboardData\\\": $(cat dashboard-sales-overview.json)\n  }\"\n```\n\n## Before you start\n\n- You have a service token. See [Authentication](/developer-docs/helpers/api-reference/authentication).\n- You have a file from [Export a dashboard](/developer-docs/helpers/api-reference/export-dashboard).\n- The workspace has a datasource or datamart with the tables the metrics use.","tags":["Data App APIs / Data Retrieval"],"x-mint-page":"/developer-docs/helpers/api-reference/import-dashboard","x-title":"Import a dashboard","security":[{"ServiceToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"workspaceName":{"type":"string","description":"The workspace to import into."},"importDashboardData":{"type":"object","description":"The export file as it is, or only its `data`"},"dashboardId":{"type":"string","description":"Id of the new dashboard. Default: the exported id plus a time stamp.","default":"<exported externalDashboardId>_<Date.now()>"},"dashboardName":{"type":"string","description":"Name of the new dashboard. Default: the exported name."},"schemaPairs":{"type":"array","items":{"type":"object","properties":{"replaceSchema":{"type":"string","x-mint-extra":true},"targetSchema":{"type":"string","x-mint-extra":true}},"required":["replaceSchema","targetSchema"],"additionalProperties":false},"description":"Schema names to swap in the metrics' SQL: `{ \"replaceSchema\": \"public\", \"targetSchema\": \"eu\" }`. Fill both or neither."},"mode":{"type":"string","description":"`replace`","enum":["replace"]},"dryRun":{"type":"boolean","description":"`true` checks and shows the changes. Leave it out to replace.","default":false},"expectedVersion":{"type":"string","description":"Required to replace: the `version` from your dry run."},"acknowledgeShared":{"type":"array","items":{"type":"string"},"description":"Shared metrics you agree to change.","default":[]},"message":{"type":"string","description":"A note, up to 200 characters.","default":"Import (replace)"}},"required":["workspaceName","importDashboardData"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":{"dashboardId":"sales-overview","version":"...","changes":{"added":0,"updated":2,"retired":0,"unchanged":5},"metrics":[{"source":"m1","target":"m1","action":"updated"}],"checks":[],"warnings":[],"dryRun":true}}}}},"400":{"description":"- `AUTHENTICATION_ERROR`: You used a data app API token\n- `INVALID_REQUEST_BODY`: A field is missing or wrong\n- `WORKSPACE_ID_ERROR`: No workspace has this name\n- `INVALID_DASHBOARD_ID`: A dashboard in the workspace already has this `dashboardId`\n- `INVALID_IMPORT_FILE`: Replace mode: the export file could not be read.\n- `WORKSPACE_NOT_FOUND`: Replace mode: no workspace, or more than one, has this name.\n- `EXPECTED_VERSION_REQUIRED`: Replace: run a dry run first and send its version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"You used a data app API token"}}}}},"401":{"description":"- `AUTHENTICATION_ERROR`: You used a data app API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"You used a data app API token"}}}}},"403":{"description":"- `ACCOUNT_DISABLED`: The organization is disabled or locked for deletion. Contact Databrain support\n- `AUTHENTICATION_ERROR`: You used a data app API token\n- `FEATURE_NOT_ENABLED`: Replace: dashboard environments are off\n- `FOREIGN_EXPORT`: Replace: the file is from another organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"ACCOUNT_DISABLED","message":"The organization is disabled or locked for deletion. Contact Databrain support"}}}}},"404":{"description":"- `DASHBOARD_NOT_FOUND`: Replace: no dashboard has this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"DASHBOARD_NOT_FOUND","message":"Replace: no dashboard has this id"}}}}},"409":{"description":"- `CLIENT_DASHBOARD`: Replace mode: a customer made the target dashboard, so it cannot be replaced.\n- `LIVE_CHANGED`: Replace: the dashboard changed after your dry run\n- `AMBIGUOUS_MATCH or SHARED_METRIC`: Replace mode: a check blocks the replace. The body lists the `checks`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"CLIENT_DASHBOARD","message":"Replace mode: a customer made the target dashboard, so it cannot be replaced."}}}}},"422":{"description":"- `<first blocking check code>`: Replace mode: another check blocks the replace. The `code` is the first blocking check, and the body lists the `checks`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"<first blocking check code>","message":"Replace mode: another check blocks the replace. The `code` is the first blocking check, and the body lists the `checks`."}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: The import failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"The import failed"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body"}],"x-mint-rest":"## Response\n\n```json\n{\n  \"data\": {\n    \"response\": {\n      \"message\": \"Imported Dashboard with 8 metrics\",\n      \"dashboardId\": \"sales-overview-eu\",\n      \"dashboardName\": \"Sales overview\",\n      \"workspaceName\": \"Customer analytics EU\",\n      \"importSummary\": {\n        \"imported\": 8,\n        \"skipped\": 1,\n        \"skippedMetrics\": [{ \"metricId\": \"...\", \"name\": \"Churn\", \"reason\": \"TARGET_TABLE_NOT_FOUND\" }]\n      }\n    }\n  }\n}\n```\n\nA metric is skipped when the workspace cannot run it. `reason` says why, with the same values as on [Create a customer dashboard embed](/developer-docs/helpers/api-reference/create-dashboard-embed#response).\n\n> [!WARNING]\n> If the import fails part way, you still get `200`, with `data.error` instead of `data.response`, and part of the dashboard can stay. Check `data.error` on every call.\n\n```json\n{ \"data\": { \"error\": { \"message\": \"No data source or data mart is connected!\", \"hint\": \"...\" } } }\n```\n\n## Replace a dashboard in place\n\nSend `\"mode\": \"replace\"` to update an existing dashboard from the file, in a dry run first. It needs dashboard environments on for your organization (**Settings > Environments**), else `403 FEATURE_NOT_ENABLED`.\n\nThe response is `{ \"data\": { \"dashboardId\", \"version\", \"changes\", \"metrics\", \"checks\", \"warnings\", \"dryRun\" } }`. Any other `mode` value is ignored, and a normal import runs.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | A field is missing or wrong |\n| 400 | `WORKSPACE_ID_ERROR` | No workspace has this name |\n| 400 | `INVALID_DASHBOARD_ID` | A dashboard in the workspace already has this `dashboardId` |\n| 403 | `AUTHENTICATION_ERROR` | You used a data app API token |\n| 403 | `FEATURE_NOT_ENABLED` | Replace: dashboard environments are off |\n| 403 | `FOREIGN_EXPORT` | Replace: the file is from another organization |\n| 404 | `DASHBOARD_NOT_FOUND` | Replace: no dashboard has this id |\n| 400 | `EXPECTED_VERSION_REQUIRED` | Replace: run a dry run first and send its version |\n| 409 | `LIVE_CHANGED` | Replace: the dashboard changed after your dry run |\n| 500 | `INTERNAL_SERVER_ERROR` | The import failed |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/data-app/dashboard-releases":{"post":{"operationId":"promoteDashboardRelease","summary":"Promote dashboard","description":"A release copies a dashboard and its metrics from its workspace to the linked workspace of the next environment. Every call is a dry run unless you send `\"dryRun\": false`.\n\n## Before you start\n\n- You have a service token. See [Authentication](/developer-docs/helpers/api-reference/authentication).\n- An admin linked two or more workspaces as environments in **Settings > Environments**.\n\n## Steps\n\n1. Run a dry run:\n\n   ```bash\n   curl --request POST https://api.usedatabrain.com/api/v2/data-app/dashboard-releases \\\n     --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\" \\\n     --header \"Content-Type: application/json\" \\\n     --data '{ \"workspaceName\": \"Staging\", \"dashboardId\": \"sales-overview\" }'\n   ```\n\n2. Read `data.checks`, `data.metrics` and `data.canPublish`. Each metric's `action` is `added`, `updated`, `retired` or `unchanged`. Copy `data.expectedVersion`.\n3. Publish with the version:\n\n   ```bash\n   curl --request POST https://api.usedatabrain.com/api/v2/data-app/dashboard-releases \\\n     --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\" \\\n     --header \"Content-Type: application/json\" \\\n     --data '{\n       \"workspaceName\": \"Staging\",\n       \"dashboardId\": \"sales-overview\",\n       \"dryRun\": false,\n       \"expectedVersion\": \"<data.expectedVersion from step 1>\",\n       \"message\": \"Add churn chart\",\n       \"tag\": \"v12\"\n     }'\n   ```\n\nYou get the release id. Next, [list releases](/developer-docs/helpers/api-reference/list-dashboard-releases).","tags":["Data App APIs / Data Retrieval"],"x-mint-page":"/developer-docs/helpers/api-reference/promote-dashboard-release","x-title":"Promote a dashboard to the next environment","security":[{"ServiceToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"workspaceName":{"type":"string","description":"The workspace the dashboard is in now."},"dashboardId":{"type":"string","description":"The dashboard's `externalDashboardId`"},"dryRun":{"type":"boolean","description":"Only `false` publishes. Default: a dry run.","default":true},"expectedVersion":{"type":"string","description":"Required to publish. The `expectedVersion` of your dry run. If the dashboard changed since, you get `409 LIVE_CHANGED`"},"acknowledgeShared":{"type":"array","items":{"type":"string"},"description":"Names of shared metrics you agree to change. The dry run lists them.","default":[]},"message":{"type":"string","description":"A note on the release, up to 200 characters.","default":""},"tag":{"type":"string","description":"A label, up to 40 characters."},"callbackUrl":{"type":"string","description":"An `https` URL that gets a signed `POST` after the publish. See below."}},"required":["workspaceName","dashboardId"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":{"releaseId":"0a1b2c3d-...","shortId":"r-8k2m","dashboardId":"...","externalDashboardId":"sales-overview","summary":{"added":1,"updated":2,"retired":0,"unchanged":5},"callback":{"delivered":true,"status":200}}}}}},"400":{"description":"- `AUTHENTICATION_ERROR`: No `Authorization: Bearer` header, or the token is not a UUID. Send `Authorization: Bearer <token>`\n- `WORKSPACE_NOT_FOUND`: No workspace, or more than one, has this name\n- `EXPECTED_VERSION_REQUIRED`: You published without `expectedVersion`\n- `INVALID_CALLBACK_URL`: `callbackUrl` is not a public `https` URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"No `Authorization: Bearer` header, or the token is not a UUID. Send `Authorization: Bearer <token>`"}}}}},"401":{"description":"- `AUTHENTICATION_ERROR`: The token is unknown, revoked or expired. Use a current token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"The token is unknown, revoked or expired. Use a current token"}}}}},"403":{"description":"- `ACCOUNT_DISABLED`: The organization is disabled or locked for deletion. Contact Databrain support\n- `AUTHENTICATION_ERROR`: A data app API token on a service-token endpoint. Use a service token\n- `FEATURE_NOT_ENABLED`: `Dashboard environments are not on for your company.`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"ACCOUNT_DISABLED","message":"The organization is disabled or locked for deletion. Contact Databrain support"}}}}},"404":{"description":"- `DASHBOARD_NOT_FOUND`: No dashboard in the workspace has this id\n- `NOT_FOUND`: The dashboard or the workspace was not found.\n- `NOT_FOUND` or `RETRY` or `CONFLICT`: The release store refused the change: `NOT_FOUND` (404), or `RETRY` or `CONFLICT` (409). Try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"DASHBOARD_NOT_FOUND","message":"No dashboard in the workspace has this id"}}}}},"409":{"description":"- `LIVE_CHANGED`: The dashboard changed after your dry run. Run it again\n- `NO_CHANGES`: `Nothing to promote. Both environments match.`\n- `CLIENT_DASHBOARD`: Customer dashboards cannot be promoted\n- `NOT_IN_ENVIRONMENT`: The workspace is not in an environment group.\n- `LAST_ENVIRONMENT`: The workspace is the last environment, so there is nothing to promote to.\n- `AMBIGUOUS_MATCH`: The next environment has more than one matching dashboard.\n- `NOT_FOUND` or `RETRY` or `CONFLICT`: The release store refused the change: `NOT_FOUND` (404), or `RETRY` or `CONFLICT` (409). Try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"LIVE_CHANGED","message":"The dashboard changed after your dry run. Run it again"}}}}},"422":{"description":"- `CHECKS_FAILED`: `Fix the failed checks first.` The body has `checks`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"CHECKS_FAILED","message":"`Fix the failed checks first.` The body has `checks`"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: `Nothing was changed. Try again.`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"`Nothing was changed. Try again.`"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body"}],"x-mint-rest":"## Response\n\nDry run:\n\n```json\n{\n  \"data\": {\n    \"sourceDashboardId\": \"4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8\",\n    \"target\": { \"environment\": \"Production\", \"externalDashboardId\": \"sales-overview\", \"isNew\": false },\n    \"summary\": { \"added\": 1, \"updated\": 2, \"retired\": 0, \"unchanged\": 5 },\n    \"metrics\": [{ \"name\": \"Churn\", \"action\": \"added\" }],\n    \"checks\": [],\n    \"canPublish\": true,\n    \"noChanges\": false,\n    \"expectedVersion\": \"9f2c...\"\n  }\n}\n```\n\nPublish:\n\n```json\n{ \"data\": { \"releaseId\": \"0a1b2c3d-...\", \"shortId\": \"r-8k2m\", \"dashboardId\": \"...\", \"summary\": { \"added\": 1, \"updated\": 2, \"retired\": 0, \"unchanged\": 5 } } }\n```\n\nWith `callbackUrl`, the response also has `callback: { \"delivered\": true, \"status\": 200 }`.\n\n### Callback\n\nDatabrain sends `POST <callbackUrl>` with `{ \"id\", \"type\": \"release.published\", \"createdAt\", \"data\": { ... } }` and the header `Databrain-Signature: t=<unix time>,v1=<signature>`. The signature is the hex HMAC-SHA256 of `<t>.<body>`, keyed with your service token. The URL must be `https` on a public host. Databrain waits 10 seconds and does not follow redirects. A failed callback does not undo the release.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `WORKSPACE_NOT_FOUND` | No workspace, or more than one, has this name |\n| 400 | `EXPECTED_VERSION_REQUIRED` | You published without `expectedVersion` |\n| 400 | `INVALID_CALLBACK_URL` | `callbackUrl` is not a public `https` URL |\n| 403 | `AUTH_ERROR` | `A service token is required.` |\n| 403 | `FEATURE_NOT_ENABLED` | `Dashboard environments are not on for your company.` |\n| 404 | `DASHBOARD_NOT_FOUND` | No dashboard in the workspace has this id |\n| 409 | `LIVE_CHANGED` | The dashboard changed after your dry run. Run it again |\n| 409 | `NO_CHANGES` | `Nothing to promote. Both environments match.` |\n| 409 | `CLIENT_DASHBOARD` | Customer dashboards cannot be promoted |\n| 422 | `CHECKS_FAILED` | `Fix the failed checks first.` The body has `checks` |\n| 500 | `INTERNAL_SERVER_ERROR` | `Nothing was changed. Try again.` |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."},"get":{"operationId":"listDashboardReleases","summary":"List releases","description":"```bash\ncurl \"https://api.usedatabrain.com/api/v2/data-app/dashboard-releases?workspaceName=Staging&dashboardId=sales-overview\" \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\"\n```\n\n## Before you start\n\n- You have a service token. See [Authentication](/developer-docs/helpers/api-reference/authentication).\n- Dashboard environments are set up in **Settings > Environments**.","tags":["Data App APIs / Data Retrieval"],"x-mint-page":"/developer-docs/helpers/api-reference/list-dashboard-releases","x-title":"List dashboard releases","security":[{"ServiceToken":[]}],"parameters":[{"name":"workspaceName","in":"query","required":true,"schema":{"type":"string"},"description":"The workspace of the dashboard."},{"name":"dashboardId","in":"query","required":true,"schema":{"type":"string"},"description":"The dashboard's `externalDashboardId`"}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":{"releases":[{"id":"0a1b2c3d-...","shortId":"r-8k2m","version":12,"kind":"promotion","status":"published","message":"Add churn chart","tag":"v12","externalDashboardId":"4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8","sourceDashboardId":"...","sourceWorkspaceId":"...","targetWorkspaceId":"...","liveHashAfter":"...","baseLiveHash":"...","diff":{"summary":{"added":1,"updated":2,"retired":0,"unchanged":5}},"actorKind":"service_token","actorId":null,"createdAt":"2026-11-18T10:00:00.000Z","publishedAt":"2026-11-18T10:00:04.000Z","restoredFromReleaseId":null}],"drift":{"drifted":false,"since":"r-8k2m","publishedAt":"2026-11-18T10:00:04.000Z"}}}}}},"400":{"description":"- `AUTHENTICATION_ERROR`: No `Authorization: Bearer` header, or the token is not a UUID. Send `Authorization: Bearer <token>`\n- `WORKSPACE_NOT_FOUND`: No workspace, or more than one, has this name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"No `Authorization: Bearer` header, or the token is not a UUID. Send `Authorization: Bearer <token>`"}}}}},"401":{"description":"- `AUTHENTICATION_ERROR`: The token is unknown, revoked or expired. Use a current token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"The token is unknown, revoked or expired. Use a current token"}}}}},"403":{"description":"- `ACCOUNT_DISABLED`: The organization is disabled or locked for deletion. Contact Databrain support\n- `AUTHENTICATION_ERROR`: A data app API token on a service-token endpoint. Use a service token\n- `FEATURE_NOT_ENABLED`: Dashboard environments are not on for your company","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"ACCOUNT_DISABLED","message":"The organization is disabled or locked for deletion. Contact Databrain support"}}}}},"404":{"description":"- `DASHBOARD_NOT_FOUND`: No dashboard in the workspace has this id\n- `NOT_FOUND` or `RETRY` or `CONFLICT`: The release history could not be read now: `NOT_FOUND` (404), or `RETRY` or `CONFLICT` (409). Try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"DASHBOARD_NOT_FOUND","message":"No dashboard in the workspace has this id"}}}}},"409":{"description":"- `NOT_FOUND` or `RETRY` or `CONFLICT`: The release history could not be read now: `NOT_FOUND` (404), or `RETRY` or `CONFLICT` (409). Try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"The release history could not be read now: `NOT_FOUND` (404), or `RETRY` or `CONFLICT` (409). Try again."}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: Databrain failed. Try again. If it fails again, contact support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"Databrain failed. Try again. If it fails again, contact support"}}}}}},"x-mint-sections":[{"in":"parameters","heading":"Query"}],"x-mint-rest":"## Response\n\nNewest first, up to 200 releases.\n\n```json\n{\n  \"data\": {\n    \"releases\": [\n      {\n        \"id\": \"0a1b2c3d-...\",\n        \"shortId\": \"r-8k2m\",\n        \"version\": 12,\n        \"kind\": \"promotion\",\n        \"message\": \"Add churn chart\",\n        \"tag\": \"v12\",\n        \"externalDashboardId\": \"sales-overview\",\n        \"createdAt\": \"2026-11-18T10:00:00.000Z\",\n        \"publishedAt\": \"2026-11-18T10:00:04.000Z\",\n        \"restoredFromReleaseId\": null\n      }\n    ],\n    \"drift\": { \"drifted\": false, \"since\": null, \"publishedAt\": \"2026-11-18T10:00:04.000Z\" }\n  }\n}\n```\n\n| Field | Description |\n| --- | --- |\n| `releases[].id`, `shortId` | Use either one as `release` to [roll back](/developer-docs/helpers/api-reference/rollback-dashboard-release) |\n| `releases[].kind` | `promotion`, `rollback` or `import` |\n| `releases[].restoredFromReleaseId` | Set on a roll back: the release it restored |\n| `drift.drifted` | `true` when someone changed the released dashboard after the last release |\n\nEach release also has `status`, `sourceDashboardId`, `sourceWorkspaceId`, `targetWorkspaceId`, `diff`, `actorKind` and `actorId`.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `WORKSPACE_NOT_FOUND` | No workspace, or more than one, has this name |\n| 403 | `AUTH_ERROR` | `A service token is required.` |\n| 403 | `FEATURE_NOT_ENABLED` | Dashboard environments are not on for your company |\n| 404 | `DASHBOARD_NOT_FOUND` | No dashboard in the workspace has this id |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/data-app/dashboard-releases/rollback":{"post":{"operationId":"rollbackDashboardRelease","summary":"Roll back release","description":"A roll back is a new release that restores an old one. Every call is a dry run unless you send `\"dryRun\": false`.\n\n## Before you start\n\n- You have a service token. See [Authentication](/developer-docs/helpers/api-reference/authentication).\n- You have the release `id` or `shortId` from [List dashboard releases](/developer-docs/helpers/api-reference/list-dashboard-releases).\n\n## Steps\n\n1. Run a dry run:\n\n   ```bash\n   curl --request POST https://api.usedatabrain.com/api/v2/data-app/dashboard-releases/rollback \\\n     --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\" \\\n     --header \"Content-Type: application/json\" \\\n     --data '{ \"workspaceName\": \"Staging\", \"dashboardId\": \"sales-overview\", \"release\": \"r-8k2m\" }'\n   ```\n\n2. Read `data.checks` and `data.canRollBack`. Copy `data.expectedVersion`.\n3. Send the same body with `\"dryRun\": false` and `\"expectedVersion\": \"<data.expectedVersion>\"`.\n\nYou get the new release id in `data.releaseId`.","tags":["Data App APIs / Data Retrieval"],"x-mint-page":"/developer-docs/helpers/api-reference/rollback-dashboard-release","x-title":"Roll back a dashboard release","security":[{"ServiceToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"workspaceName":{"type":"string","description":"The workspace of the dashboard."},"dashboardId":{"type":"string","description":"The dashboard's `externalDashboardId`"},"release":{"type":"string","description":"The release `id` or `shortId` to restore."},"dryRun":{"type":"boolean","description":"Only `false` rolls back. Default: a dry run.","default":true},"expectedVersion":{"type":"string","description":"Required to roll back. The `expectedVersion` of your dry run."},"acknowledgeShared":{"type":"array","items":{"type":"string"},"description":"Shared metrics you agree to change.","default":[]},"callbackUrl":{"type":"string","description":"An `https` URL that gets a signed `POST` afterwards, as on [promote](/developer-docs/helpers/api-reference/promote-dashboard-release#callback)"}},"required":["workspaceName","dashboardId","release"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":{"releaseId":"5e6f7a8b-...","shortId":"r-9p3q","restored":"r-8k2m","summary":{"added":0,"updated":2,"retired":1,"unchanged":5},"callback":{"delivered":true,"status":200}}}}}},"400":{"description":"- `AUTHENTICATION_ERROR`: No `Authorization: Bearer` header, or the token is not a UUID. Send `Authorization: Bearer <token>`\n- `WORKSPACE_NOT_FOUND`: No workspace, or more than one, has this name.\n- `EXPECTED_VERSION_REQUIRED`: You rolled back without `expectedVersion`\n- `INVALID_CALLBACK_URL`: `callbackUrl` is not a valid URL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"No `Authorization: Bearer` header, or the token is not a UUID. Send `Authorization: Bearer <token>`"}}}}},"401":{"description":"- `AUTHENTICATION_ERROR`: The token is unknown, revoked or expired. Use a current token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"The token is unknown, revoked or expired. Use a current token"}}}}},"403":{"description":"- `ACCOUNT_DISABLED`: The organization is disabled or locked for deletion. Contact Databrain support\n- `AUTHENTICATION_ERROR`: A data app API token on a service-token endpoint. Use a service token\n- `FEATURE_NOT_ENABLED`: Not a service token, or environments are off","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"ACCOUNT_DISABLED","message":"The organization is disabled or locked for deletion. Contact Databrain support"}}}}},"404":{"description":"- `DASHBOARD_NOT_FOUND`: No dashboard in the workspace has this id\n- `RELEASE_NOT_FOUND`: `Release not found.`\n- `NOT_FOUND`: No release snapshot has this id.\n- `NOT_FOUND` or `RETRY` or `CONFLICT`: The release store refused the change: `NOT_FOUND` (404), or `RETRY` or `CONFLICT` (409). Try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"DASHBOARD_NOT_FOUND","message":"No dashboard in the workspace has this id"}}}}},"409":{"description":"- `LIVE_CHANGED`: The dashboard changed after your dry run\n- `NO_CHANGES`: `The dashboard already matches that release.`\n- `NOT_FOUND` or `RETRY` or `CONFLICT`: The release store refused the change: `NOT_FOUND` (404), or `RETRY` or `CONFLICT` (409). Try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"LIVE_CHANGED","message":"The dashboard changed after your dry run"}}}}},"422":{"description":"- `CHECKS_FAILED`: `This roll back is blocked.` The body has `checks`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"CHECKS_FAILED","message":"`This roll back is blocked.` The body has `checks`"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: `Nothing was changed. Try again.`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"`Nothing was changed. Try again.`"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body"}],"x-mint-rest":"## Response\n\nDry run:\n\n```json\n{\n  \"data\": {\n    \"releaseShortId\": \"r-8k2m\",\n    \"summary\": { \"added\": 0, \"updated\": 2, \"retired\": 1, \"unchanged\": 5 },\n    \"metrics\": [{ \"name\": \"Churn\", \"action\": \"retired\" }],\n    \"checks\": [],\n    \"canRollBack\": true,\n    \"noChanges\": false,\n    \"expectedVersion\": \"4b1d...\"\n  }\n}\n```\n\nRoll back:\n\n```json\n{ \"data\": { \"releaseId\": \"5e6f7a8b-...\", \"shortId\": \"r-9p3q\", \"restored\": \"r-8k2m\", \"summary\": { \"added\": 0, \"updated\": 2, \"retired\": 1, \"unchanged\": 5 } } }\n```\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `EXPECTED_VERSION_REQUIRED` | You rolled back without `expectedVersion` |\n| 403 | `AUTH_ERROR` or `FEATURE_NOT_ENABLED` | Not a service token, or environments are off |\n| 404 | `RELEASE_NOT_FOUND` | `Release not found.` |\n| 404 | `DASHBOARD_NOT_FOUND` | No dashboard in the workspace has this id |\n| 409 | `LIVE_CHANGED` | The dashboard changed after your dry run |\n| 409 | `NO_CHANGES` | `The dashboard already matches that release.` |\n| 422 | `CHECKS_FAILED` | `This roll back is blocked.` The body has `checks` |\n| 500 | `INTERNAL_SERVER_ERROR` | `Nothing was changed. Try again.` |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/data-app/metrics/publish":{"put":{"operationId":"publishMetric","summary":"Publish metric","description":"```bash\ncurl --request PUT https://api.usedatabrain.com/api/v2/data-app/metrics/publish \\\n  --header \"Authorization: Bearer $DATABRAIN_API_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{ \"embedId\": \"sales-overview\", \"metricId\": \"b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e\", \"isPublished\": true }'\n```\n\n## Auth\n\nA data app API token. A service token gets `400 INVALID_DATA_APP_API_KEY`. See [Authentication](/developer-docs/helpers/api-reference/authentication).","tags":["Metric APIs"],"x-mint-page":"/developer-docs/helpers/api-reference/publish-metric","x-title":"Publish or unpublish a metric","security":[{"DataAppApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"embedId":{"type":"string","description":"The embed id of a dashboard embed of the data app."},"metricId":{"type":"string","description":"The metric id, from [Fetch metrics by embed](/developer-docs/helpers/api-reference/fetch-metrics-by-embed-and-client)"},"isPublished":{"type":"boolean","description":"`true` to publish, `false` to unpublish."}},"required":["embedId","metricId","isPublished"],"additionalProperties":false},"example":{"embedId":"sales-overview","metricId":"b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e","isPublished":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e"}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: A field is missing\n- `INVALID_DATA_APP_API_KEY`: You used a service token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"A field is missing"}}}}},"500":{"description":"- `INVALID_METRIC_ID`: `Invalid metric id or embed id`: the metric is not on that embed\n- `INTERNAL_SERVER_ERROR`: The update failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_METRIC_ID","message":"`Invalid metric id or embed id`: the metric is not on that embed"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body","after":"The flag is on the metric itself, so it changes on every dashboard that shows the metric. Databrain saves a revision of the metric."}],"x-mint-rest":"## Response\n\n```json\n{ \"id\": \"b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e\" }\n```\n\n`id` is the metric id.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | A field is missing |\n| 400 | `INVALID_DATA_APP_API_KEY` | You used a service token |\n| 500 | `INVALID_METRIC_ID` | `Invalid metric id or embed id`: the metric is not on that embed |\n| 500 | `INTERNAL_SERVER_ERROR` | The update failed |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/admin-account":{"post":{"operationId":"createAdminAccount","summary":"Create admin account","description":"Call it once, on a new self-hosted install. It makes the organization, its admin user and a demo workspace, and returns an access token for that admin.\n\n```bash\ncurl --request POST https://databrain-api.example.com/api/v2/admin-account \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\n    \"firstName\": \"Alex\",\n    \"lastName\": \"Morgan\",\n    \"email\": \"alex@example.com\",\n    \"password\": \"<password>\",\n    \"companyName\": \"Example Inc\"\n  }'\n```\n\n## Before you start\n\n- Self-hosted only. On Databrain cloud the call returns `SELFHOSTED_APP_ERROR`.\n- No organization exists on the install yet. After the first call, the endpoint refuses.\n\n## Auth\n\nNone. Run it from your own network, before you open the install to users.","tags":["Self-Hosted APIs"],"x-mint-page":"/developer-docs/helpers/api-reference/create-admin-account","x-title":"Create the admin account","security":[],"servers":[{"url":"{origin}","description":"Your self-hosted Databrain API","variables":{"origin":{"default":"https://databrain-api.example.com","description":"The API origin of your install"}}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string","description":"3 to 30 characters."},"lastName":{"type":"string","description":"Last name.","default":""},"email":{"type":"string","description":"A work email. Free mail domains such as Gmail, Yahoo and Outlook are refused."},"password":{"type":"string","description":"At least 8 characters, with an upper-case letter, a lower-case letter, a number and a special character, and no spaces."},"companyName":{"type":"string","description":"Organization name. Saved in lower case."},"productUpdatesOptIn":{"type":"boolean","description":"Get product update emails. Default `false`","default":false}},"required":["firstName","email","password","companyName"]},"example":{"firstName":"Alex","lastName":"Morgan","email":"alex@example.com","password":"<password>","companyName":"Example Inc"}}}},"responses":{"200":{"description":"Success, or an error. This endpoint answers errors with HTTP 200 and an `error` object:\n- `INVALID_REQUEST`: An admin account already exists on this install. Sign in instead.\n- `INVALID REQUEST BODY`: A field is missing or wrong. The message names the field.\n- `USER_EXISTS`: A user with this email already exists.\n- `EMAIL_ALIAS_REFUSED`: The email is a `+` alias of an email that already has an account.\n- `COMPANY_EXISTS`: An organization with this name already exists.\n- `SELFHOSTED_APP_ERROR`: This endpoint works only on self-hosted Databrain.\n- `INTERNAL_SERVER_ERROR`: Databrain failed. Try again. If it fails again, contact support\n- `INTERNAL SERVER ERROR`: The account was not created (for example, the database is not reachable). Try again.","content":{"application/json":{"examples":{"success":{"summary":"Success","value":{"data":{"accessToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}}},"error":{"summary":"Error","value":{"error":{"code":"INVALID_REQUEST","message":"An admin account already exists on this install. Sign in instead."}}}}}}}},"x-mint-sections":[{"in":"body","heading":"Body"}],"x-mint-rest":"## Response\n\n```json\n{ \"data\": { \"accessToken\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\" } }\n```\n\n`accessToken` is a JWT for the admin. It lasts 10 minutes, unless you set `ACCESS_TOKEN_TTL`. Use it to [create a service token](/developer-docs/helpers/api-reference/create-service-token). For a new one later, [create an admin JWT](/developer-docs/helpers/api-reference/create-admin-jwt).\n\n## Errors\n\n> [!WARNING]\n> This endpoint returns HTTP `200` for errors too. Check for `error` in the body.\n\n```json\n{ \"error\": { \"code\": \"INVALID_REQUEST\", \"message\": \"Your company account is already created, please sign in\" } }\n```\n\n| `error.code` | Why |\n| --- | --- |\n| `INVALID_REQUEST` | An organization already exists. [Sign in with an admin JWT](/developer-docs/helpers/api-reference/create-admin-jwt) |\n| `INVALID REQUEST BODY` | A field is missing or wrong. The message names it, for example `\"password\" should contain at least 1 special character` or `Please use a valid email address.` |\n| `SELFHOSTED_APP_ERROR` | `This feature is only available for self-hosted instances` |\n| `COMPANY_EXISTS` or `USER_EXISTS` | The organization or user could not be created |\n| `INTERNAL_SERVER_ERROR` | The account was not created. Try again |"}},"/api/v2/admin-account/jwt":{"post":{"operationId":"createAdminJwt","summary":"Create admin JWT","description":"Use the token to [create a service token](/developer-docs/helpers/api-reference/create-service-token), [rotate a token](/developer-docs/helpers/api-reference/rotate-token-from-app) or [reset your password](/developer-docs/helpers/api-reference/reset-admin-password).\n\n```bash\ncurl --request POST https://databrain-api.example.com/api/v2/admin-account/jwt \\\n  --header \"Content-Type: application/json\" \\\n  --data '{ \"email\": \"alex@example.com\", \"password\": \"<password>\" }'\n```\n\n## Before you start\n\n- Self-hosted only.\n- Multi-factor sign-in is off for your organization. With it on, this endpoint cannot return a token.\n\n## Auth\n\nNone. Any verified user of the install can sign in. The token has that user's own role, so use an admin for token work.","tags":["Self-Hosted APIs"],"x-mint-page":"/developer-docs/helpers/api-reference/create-admin-jwt","x-title":"Create an admin JWT","security":[],"servers":[{"url":"{origin}","description":"Your self-hosted Databrain API","variables":{"origin":{"default":"https://databrain-api.example.com","description":"The API origin of your install"}}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"The user's email."},"password":{"type":"string","description":"The user's password."},"passwordCiphertext":{"type":"string","description":"The password, encrypted with the install's public password key (RSA-OAEP-256, base64). Send it with `keyId` instead of `password` when the install refuses plain passwords.","x-mint-extra":true},"keyId":{"type":"string","description":"The id of the key that encrypted `passwordCiphertext`.","x-mint-extra":true}},"required":["email","password"]},"example":{"email":"alex@example.com","password":"<password>"}}}},"responses":{"200":{"description":"Success, or an error. This endpoint answers errors with HTTP 200 and an `error` object:\n- `Invalid credentials`: The email or password is wrong. The `code` is the text `Invalid credentials`.\n- `ACCOUNT NOT VERIFIED`: The user has not verified the account.\n- `INVITATION_NOT_ACCEPTED`: The user has not accepted the invitation.\n- `LICENSE_EXPIRED`: Self-hosted only: the licence key expired. Renew the licence key\n- `ACCOUNT_DISABLED`: The organization is disabled or locked for deletion. Contact Databrain support\n- `APP_CODE_REQUIRED`: The user has an authenticator app, so no token is issued. Use an admin without one.\n- `PASSWORD_ENCRYPTION_REQUIRED`: This install refuses plain passwords. Send `passwordCiphertext` and `keyId`.\n- `PASSWORD_KEY_MISMATCH`: `keyId` does not match the key of this install.\n- `SELFHOSTED_APP_ERROR`: This endpoint works only on self-hosted Databrain.\n- `INTERNAL_SERVER_ERROR`: Databrain failed. Try again. If it fails again, contact support","content":{"application/json":{"examples":{"success":{"summary":"Success","value":{"data":{"accessToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}}},"error":{"summary":"Error","value":{"error":{"code":"Invalid credentials","message":"The email or password is wrong. The `code` is the text `Invalid credentials`."}}}}}}}},"x-mint-sections":[{"in":"body","heading":"Body"}],"x-mint-rest":"## Response\n\n```json\n{ \"data\": { \"accessToken\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\" } }\n```\n\nThe token lasts 10 minutes, unless you set `ACCESS_TOKEN_TTL`. No refresh token is returned: call this endpoint again for a new one. Send it as `Authorization: Bearer <accessToken>`.\n\n## Errors\n\n> [!WARNING]\n> This endpoint returns HTTP `200` for errors too. Check for `error` in the body.\n\n| `error.code` | Why |\n| --- | --- |\n| `Invalid credentials` | The email or password is wrong, or no user has this email |\n| `ACCOUNT NOT VERIFIED` | The user has not verified their email |\n| `INVITATION_NOT_ACCEPTED` | The user has not accepted the invitation |\n| `LICENSE_EXPIRED` | `Trial or License Key is Expired!` |\n| `ACCOUNT_DISABLED` | The organization is disabled |\n| `SELFHOSTED_APP_ERROR` | You called it on Databrain cloud |\n| `INTERNAL_SERVER_ERROR` | No token was made. This is also the answer when multi-factor sign-in is on |"}},"/api/v2/service-token":{"post":{"operationId":"createServiceToken","summary":"Create service token","description":"You send a UUID. It becomes your organization's service token. Use it for the rest of this API. See [Authentication](/developer-docs/helpers/api-reference/authentication).\n\n```bash\ncurl --request POST https://databrain-api.example.com/api/v2/service-token \\\n  --header \"Authorization: Bearer $ADMIN_ACCESS_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data \"{ \\\"token\\\": \\\"$(uuidgen)\\\" }\"\n```\n\n> [!WARNING]\n> If the organization already has a service token, the new value replaces it at once. Every integration that uses the old token stops working. To keep the old one working for a while, [rotate](/developer-docs/helpers/api-reference/rotate-service-token) instead.\n\n## Before you start\n\n- Self-hosted only.\n- You have an access token from [Create the admin account](/developer-docs/helpers/api-reference/create-admin-account) or [Create an admin JWT](/developer-docs/helpers/api-reference/create-admin-jwt). The user needs permission to create API tokens. Admins have it.\n\n## Auth\n\n`Authorization: Bearer <accessToken>`, the user's access token. A service token or a data app API token does not work here.","tags":["Self-Hosted APIs"],"x-mint-page":"/developer-docs/helpers/api-reference/create-service-token","x-title":"Create a service token","security":[{"AdminJwt":[]}],"servers":[{"url":"{origin}","description":"Your self-hosted Databrain API","variables":{"origin":{"default":"https://databrain-api.example.com","description":"The API origin of your install"}}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","description":"The service token you want. Generate a random UUID, for example with `uuidgen`"}},"required":["token"]}}}},"responses":{"200":{"description":"Success, or an error. This endpoint answers errors with HTTP 200 and an `error` object:\n- `UNAUTHORIZED`: No access token was sent\n- The admin session was signed out. Get a new admin JWT. The answer is HTTP 200 with `{ \"error\": { \"message\": \"Please refresh\" } }`.","content":{"application/json":{"examples":{"success":{"summary":"Success","value":{"key":"3f9a1c2e-8b7d-4e6f-9a0b-1c2d3e4f5a6b","keyId":"c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f","keyLast4":"5a6b"}},"error":{"summary":"Error","value":{"error":{"code":"UNAUTHORIZED","message":"No access token was sent"}}}}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: `token` is missing or not a UUID\n- `API_TOKEN_NAME_ALREADY_EXISTS`: Another key is named `Service Token`. Rename it, then try again\n- `LICENSE_EXPIRED`: The licence key expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"`token` is missing or not a UUID"}}}}},"401":{"description":"- `UNAUTHORIZED`: No access token was sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"UNAUTHORIZED","message":"No access token was sent"}}}}},"403":{"description":"- `FORBIDDEN`: `You do not have permission to create tokens.`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"FORBIDDEN","message":"`You do not have permission to create tokens.`"}}}}},"500":{"description":"- `SELFHOSTED_APP_ERROR`: You called it on Databrain cloud\n- `ACCOUNT_NOT_FOUND`: The token was not saved\n- `INTERNAL_SERVER_ERROR`: The token was not saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"SELFHOSTED_APP_ERROR","message":"You called it on Databrain cloud"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body"}],"x-mint-rest":"## Response\n\n```json\n{\n  \"key\": \"3f9a1c2e-8b7d-4e6f-9a0b-1c2d3e4f5a6b\",\n  \"keyId\": \"c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f\",\n  \"keyLast4\": \"5a6b\"\n}\n```\n\n| Field | Description |\n| --- | --- |\n| `key` | The service token, in lower case with hyphens |\n| `keyId` | The public id of the token. Use it to [rotate as a signed-in user](/developer-docs/helpers/api-reference/rotate-token-from-app) |\n| `keyLast4` | The last 4 characters |\n\nDatabrain stores only a hash of the token. A new token is named `Service Token` and has the `Access Metrics` and `Access Dashboards` scopes.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | `token` is missing or not a UUID |\n| 400 | `API_TOKEN_NAME_ALREADY_EXISTS` | Another key is named `Service Token`. Rename it, then try again |\n| 400 | `LICENSE_EXPIRED` | The licence key expired |\n| 401 | `UNAUTHORIZED` | No access token was sent |\n| 403 | `FORBIDDEN` | `You do not have permission to create tokens.` |\n| 500 | `SELFHOSTED_APP_ERROR` | You called it on Databrain cloud |\n| 500 | `ACCOUNT_NOT_FOUND` or `INTERNAL_SERVER_ERROR` | The token was not saved |\n\nAn expired access token returns HTTP `200` with `{ \"error\": { \"code\": \"UNAUTHORIZED\", \"message\": \"jwt expired\" } }`. Get a new one with [Create an admin JWT](/developer-docs/helpers/api-reference/create-admin-jwt)."}},"/api/v2/service-token/rotate":{"post":{"operationId":"rotateServiceToken","summary":"Rotate service token","description":"You call it with the service token you want to replace. Works on cloud and self-hosted.\n\n```bash\ncurl --request POST https://api.usedatabrain.com/api/v2/service-token/rotate \\\n  --header \"Authorization: Bearer $DATABRAIN_SERVICE_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{ \"expireAt\": 86400 }'\n```\n\n## Auth\n\nThe service token to rotate. A data app API token gets `400`; use [Rotate an API token](/developer-docs/helpers/api-reference/rotate-api-key) for those. See [Authentication](/developer-docs/helpers/api-reference/authentication).\n\nIf you lost the token, rotate it as a signed-in user: select **Rotate token** in **Settings > Developers > Tokens**, or call [Rotate a token as a signed-in user](/developer-docs/helpers/api-reference/rotate-token-from-app).","tags":["Self-Hosted APIs"],"x-mint-page":"/developer-docs/helpers/api-reference/rotate-service-token","x-title":"Rotate a service token","security":[{"ApiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expireAt":{"type":"number","description":"How many seconds the old token keeps working. `0` stops it at once. Not a date."}},"required":["expireAt"]},"example":{"expireAt":86400}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"key":"7d2e4f6a-1b3c-4d5e-8f9a-0b1c2d3e4f5a","keyId":"e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b","keyLast4":"4f5a"}}}},"400":{"description":"- `AUTHENTICATION_ERROR`: `Invalid Service Token`: you used a data app API token\n- `INVALID_REQUEST_BODY`: `expireAt` is missing\n- `EXPIRED_SERVICE_TOKEN`: This token is already being replaced, so it cannot rotate itself. Use the new token, or rotate in **Settings > Developers > Tokens**\n- `INVALID_SERVICE_TOKEN`: The token was not found\n- `INTERNAL_SERVER_ERROR`: The rotation failed. The old token still works\n- `API_TOKEN_NAME_ALREADY_EXISTS`: Another key already has the name the new token would get. Rename or delete it\n- `LICENSE_EXPIRED`: Self-hosted only: the licence key expired. Renew the licence key\n- `UNSUBSCRIBED_ACCOUNT_ERROR`: The trial ended. Choose a plan in **Settings > Billing**","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"`Invalid Service Token`: you used a data app API token"}}}}},"401":{"description":"- `AUTHENTICATION_ERROR`: `Invalid Service Token`: you used a data app API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"AUTHENTICATION_ERROR","message":"`Invalid Service Token`: you used a data app API token"}}}}},"403":{"description":"- `ACCOUNT_DISABLED`: The organization is disabled or locked for deletion. Contact Databrain support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"ACCOUNT_DISABLED","message":"The organization is disabled or locked for deletion. Contact Databrain support"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: The rotation failed. The old token still works","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"The rotation failed. The old token still works"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body"}],"x-mint-rest":"## Response\n\n```json\n{\n  \"key\": \"7d2e4f6a-1b3c-4d5e-8f9a-0b1c2d3e4f5a\",\n  \"keyId\": \"e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b\",\n  \"keyLast4\": \"4f5a\"\n}\n```\n\n`key` is the new token. You see it only in this response. It has the old token's name and scopes, and no expiry. The old token is renamed `<name> (replaced <date> UTC)`.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | `expireAt` is missing |\n| 400 | `AUTHENTICATION_ERROR` | `Invalid Service Token`: you used a data app API token |\n| 400 | `EXPIRED_SERVICE_TOKEN` | This token is already being replaced, so it cannot rotate itself. Use the new token, or rotate in **Settings > Developers > Tokens** |\n| 400 | `API_TOKEN_NAME_ALREADY_EXISTS` | Another key already has the name the new token would get. Rename or delete it |\n| 400 | `INVALID_SERVICE_TOKEN` | The token was not found |\n| 500 | `INTERNAL_SERVER_ERROR` | The rotation failed. The old token still works |\n\nFor errors that every endpoint returns, see [Authentication](/developer-docs/helpers/api-reference/authentication#errors-on-every-endpoint)."}},"/api/v2/service-token/rotate-from-app":{"post":{"operationId":"rotateTokenFromApp","summary":"Rotate token as a user","description":"This is the API behind **Rotate token** in the app. You need a user's access token and the token's `keyId`, not the token itself.\n\n```bash\ncurl --request POST https://databrain-api.example.com/api/v2/service-token/rotate-from-app \\\n  --header \"Authorization: Bearer $ADMIN_ACCESS_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{ \"tokenId\": \"c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f\", \"expireAt\": 3600 }'\n```\n\n## Auth\n\n`Authorization: Bearer <accessToken>`, a user's access token, for example from [Create an admin JWT](/developer-docs/helpers/api-reference/create-admin-jwt) on self-hosted. The user needs permission to create API tokens.","tags":["Self-Hosted APIs"],"x-mint-page":"/developer-docs/helpers/api-reference/rotate-token-from-app","x-title":"Rotate a token as a signed-in user","security":[{"AdminJwt":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tokenId":{"type":"string","description":"The `keyId` of the service token or data app API token, from the create response or [List API tokens](/developer-docs/helpers/api-reference/list-api-tokens)"},"expireAt":{"type":"number","description":"How many seconds the old token keeps working. `0` stops it at once."}},"required":["tokenId","expireAt"]},"example":{"tokenId":"c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f","expireAt":3600}}}},"responses":{"200":{"description":"Success, or an error. This endpoint answers errors with HTTP 200 and an `error` object:\n- `UNAUTHORIZED`: No access token was sent\n- The session was signed out. Sign in again. The answer is HTTP 200 with `{ \"error\": { \"message\": \"Please refresh\" } }`.","content":{"application/json":{"examples":{"success":{"summary":"Success","value":{"key":"7d2e4f6a-1b3c-4d5e-8f9a-0b1c2d3e4f5a","keyId":"e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b","keyLast4":"4f5a"}},"error":{"summary":"Error","value":{"error":{"code":"UNAUTHORIZED","message":"No access token was sent"}}}}}}},"400":{"description":"- `INVALID_REQUEST_BODY`: A field is missing, or `tokenId` is not a UUID. The message calls it `\"token\"`\n- `INVALID_DATA_APP_API_KEY`: The data app API token could not be rotated.\n- `INVALID_SERVICE_TOKEN`: The service token could not be rotated.\n- `API_TOKEN_NAME_ALREADY_EXISTS`: The new token's name is already used. Try again.\n- `INTERNAL_SERVER_ERROR`: The rotation failed\n- `LICENSE_EXPIRED`: Self-hosted only: the licence key expired. Renew the licence key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_REQUEST_BODY","message":"A field is missing, or `tokenId` is not a UUID. The message calls it `\"token\"`"}}}}},"401":{"description":"- `UNAUTHORIZED`: No access token was sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"UNAUTHORIZED","message":"No access token was sent"}}}}},"403":{"description":"- `FORBIDDEN`: `You do not have permission to rotate tokens.`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"FORBIDDEN","message":"`You do not have permission to rotate tokens.`"}}}}},"404":{"description":"- `TOKEN_NOT_FOUND`: No token of your organization has this `keyId`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"TOKEN_NOT_FOUND","message":"No token of your organization has this `keyId`"}}}}},"500":{"description":"- `INTERNAL_SERVER_ERROR`: The rotation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"The rotation failed"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body","after":"A token that is already being replaced can be rotated again. Its end time never moves later."}],"x-mint-rest":"## Response\n\n```json\n{\n  \"key\": \"7d2e4f6a-1b3c-4d5e-8f9a-0b1c2d3e4f5a\",\n  \"keyId\": \"e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b\",\n  \"keyLast4\": \"4f5a\"\n}\n```\n\n`key` is the new token. You see it only in this response.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `INVALID_REQUEST_BODY` | A field is missing, or `tokenId` is not a UUID. The message calls it `\"token\"` |\n| 401 | `UNAUTHORIZED` | No access token was sent |\n| 403 | `FORBIDDEN` | `You do not have permission to rotate tokens.` |\n| 404 | `TOKEN_NOT_FOUND` | No token of your organization has this `keyId` |\n| 500 | `INTERNAL_SERVER_ERROR` | The rotation failed |"}},"/api/v2/service-token/reset-password":{"post":{"operationId":"resetAdminPassword","summary":"Reset admin password","description":"The password changes for the user of the access token. Any signed-in user can change their own password.\n\n```bash\ncurl --request POST https://databrain-api.example.com/api/v2/service-token/reset-password \\\n  --header \"Authorization: Bearer $ADMIN_ACCESS_TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{ \"currentPassword\": \"<current password>\", \"password\": \"<new password>\" }'\n```\n\n## Before you start\n\n- Self-hosted only.\n- You have an access token from [Create an admin JWT](/developer-docs/helpers/api-reference/create-admin-jwt).","tags":["Self-Hosted APIs"],"x-mint-page":"/developer-docs/helpers/api-reference/reset-admin-password","x-title":"Change your password","security":[{"AdminJwt":[]}],"servers":[{"url":"{origin}","description":"Your self-hosted Databrain API","variables":{"origin":{"default":"https://databrain-api.example.com","description":"The API origin of your install"}}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"currentPassword":{"type":"string","description":"The current password."},"password":{"type":"string","description":"The new password: at least 8 characters, with an upper-case letter, a lower-case letter, a number and a special character, and no spaces."}},"required":["currentPassword","password"]},"example":{"currentPassword":"<current password>","password":"<new password>"}}}},"responses":{"200":{"description":"Success, or an error. This endpoint answers errors with HTTP 200 and an `error` object:\n- `UNAUTHORIZED`: No access token was sent\n- The admin session was signed out. Get a new admin JWT. The answer is HTTP 200 with `{ \"error\": { \"message\": \"Please refresh\" } }`.","content":{"application/json":{"examples":{"success":{"summary":"Success","value":{"data":{"success":true}}},"error":{"summary":"Error","value":{"error":{"code":"UNAUTHORIZED","message":"No access token was sent"}}}}}}},"400":{"description":"- `RESET_PASSWORD_ERROR`: The new password is too weak, a field is missing, or `The current password is not correct!`\n- `LICENSE_EXPIRED`: The licence key expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RESET_PASSWORD_ERROR","message":"The new password is too weak, a field is missing, or `The current password is not correct!`"}}}}},"401":{"description":"- `UNAUTHORIZED`: No access token was sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"UNAUTHORIZED","message":"No access token was sent"}}}}},"500":{"description":"- `SELFHOSTED_APP_ERROR`: You called it on Databrain cloud\n- `INTERNAL_SERVER_ERROR`: The password was not changed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"SELFHOSTED_APP_ERROR","message":"You called it on Databrain cloud"}}}}}},"x-mint-sections":[{"in":"body","heading":"Body"}],"x-mint-rest":"## Response\n\n```json\n{ \"data\": { \"success\": true } }\n```\n\nSessions are not signed out. Access tokens you already have keep working until they expire.\n\n## Errors\n\n| Status | `error.code` | Why |\n| --- | --- | --- |\n| 400 | `RESET_PASSWORD_ERROR` | The new password is too weak, a field is missing, or `The current password is not correct!` |\n| 400 | `LICENSE_EXPIRED` | The licence key expired |\n| 401 | `UNAUTHORIZED` | No access token was sent |\n| 500 | `SELFHOSTED_APP_ERROR` | You called it on Databrain cloud |\n| 500 | `INTERNAL_SERVER_ERROR` | The password was not changed |"}}},"components":{"securitySchemes":{"ApiToken":{"type":"http","scheme":"bearer","description":"A service token or a data app API token."},"ServiceToken":{"type":"http","scheme":"bearer","description":"A service token. A data app API token is refused."},"DataAppApiToken":{"type":"http","scheme":"bearer","description":"A data app API token. A service token is refused."},"AdminJwt":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Self-hosted only: the admin JWT from Create admin JWT."}},"schemas":{"Error":{"type":"object","description":"Every error has this shape. Some errors add fields such as `hint` or `details`.","properties":{"error":{"type":"object","additionalProperties":true,"properties":{"code":{"type":"string","description":"A stable code, for example `INVALID_REQUEST_BODY`."},"message":{"type":"string","description":"What went wrong, in words."},"hint":{"type":"string","description":"What to do next, when the API knows."},"details":{"type":"object","additionalProperties":true,"description":"More facts about the error, for some errors."}}}},"additionalProperties":true}}}}