Skip to main content
curl --request GET \
  --url 'https://api.usedatabrain.com/api/v2/data-app/datamarts?isPagination=true&pageNumber=1' \
  --header 'Authorization: Bearer dbn_live_abc123...'

{
  "data": [
    {
      "name": "sales-analytics",
      "datamartOrganization": {
        "tenancyLevel": "TABLE",
        "schemaName": "public",
        "tableName": "organizations",
        "clientColumnType": "STRING",
        "tableClientNameColumn": "name",
        "tablePrimaryKeyColumn": "id"
      },
      "companyIntegration": {
        "name": "postgres-prod"
      },
      "datamartTables": [
        {
          "schemaName": "public",
          "tableName": "customers",
          "datamartTableColumns": [
            {
              "columnName": "id",
              "datatype": "integer",
              "alias": "customer_id"
            },
            {
              "columnName": "name",
              "datatype": "varchar",
              "alias": "customer_name"
            }
          ]
        }
      ],
      "datamartRelationships": [
        {
          "parentTableName": "orders",
          "parentColumnName": "customer_id",
          "childTableName": "customers",
          "childColumnName": "id",
          "relationshipName": "orders_to_customers",
          "cardinality": "ManyToOne",
          "join": "LEFT JOIN"
        }
      ]
    }
  ],
  "error": null
}
GET
https://api.usedatabrain.com
/
api
/
v2
/
data-app
/
datamarts
curl --request GET \
  --url 'https://api.usedatabrain.com/api/v2/data-app/datamarts?isPagination=true&pageNumber=1' \
  --header 'Authorization: Bearer dbn_live_abc123...'

{
  "data": [
    {
      "name": "sales-analytics",
      "datamartOrganization": {
        "tenancyLevel": "TABLE",
        "schemaName": "public",
        "tableName": "organizations",
        "clientColumnType": "STRING",
        "tableClientNameColumn": "name",
        "tablePrimaryKeyColumn": "id"
      },
      "companyIntegration": {
        "name": "postgres-prod"
      },
      "datamartTables": [
        {
          "schemaName": "public",
          "tableName": "customers",
          "datamartTableColumns": [
            {
              "columnName": "id",
              "datatype": "integer",
              "alias": "customer_id"
            },
            {
              "columnName": "name",
              "datatype": "varchar",
              "alias": "customer_name"
            }
          ]
        }
      ],
      "datamartRelationships": [
        {
          "parentTableName": "orders",
          "parentColumnName": "customer_id",
          "childTableName": "customers",
          "childColumnName": "id",
          "relationshipName": "orders_to_customers",
          "cardinality": "ManyToOne",
          "join": "LEFT JOIN"
        }
      ]
    }
  ],
  "error": null
}
Get a comprehensive list of all datamarts in your data app, including their configurations, datasources, and access settings. Useful for managing and auditing your data organization.
Endpoint Migration Notice: We’re transitioning to kebab-case endpoints. The new endpoint is /api/v2/data-app/datamarts. The old endpoint /api/v2/dataApp/datamarts will be deprecated soon. Please update your integrations to use the new endpoint format.
This endpoint returns all datamarts you have access to within the authenticated data app. The response includes metadata and access permissions for each datamart.

​
Endpoint Formats

​
Authentication

All API requests must include your API key in the Authorization header. Get your API token when creating a data app - see our data app creation guide for details. Finding your API token: For detailed instructions, see the API Token guide.

​
Headers

​
Authorization
string
required
Bearer token for API authentication. Use your API key from the data app.
Authorization: Bearer dbn_live_abc123...

​
Query Parameters

​
isPagination
string
default:"false"
Enable pagination for the results. Pass "true" to enable pagination with a limit of 10 per page.Note: Query parameters are passed as strings. Use "true" or "false" (not boolean values).
​
pageNumber
string
default:"1"
Page number to retrieve (1-based). Only used when isPagination is "true". Must be a numeric string (e.g., "1", "2", "3").

​
Response

​
data
array
Array of datamart objects with their configuration details.
​
data.name
string
The name of the datamart.
​
data.datamartOrganization
object
Organization settings for the datamart.
​
data.datamartOrganization.tenancyLevel
string
The tenancy level (e.g., “TABLE”, “ROW”).
​
data.datamartOrganization.schemaName
string
Schema name for the organization table.
​
data.datamartOrganization.tableName
string
Table name for the organization.
​
data.datamartOrganization.clientColumnType
string
Type of the client column.
​
data.datamartOrganization.tableClientNameColumn
string
Column name for client identification.
​
data.datamartOrganization.tablePrimaryKeyColumn
string
Primary key column name.
​
data.companyIntegration
object
Integration details for the datamart.
​
data.companyIntegration.name
string
Name of the datasource integration.
​
data.datamartTables
array
Array of tables included in the datamart.
​
data.datamartTables.schemaName
string
Schema name of the table.
​
data.datamartTables.tableName
string
Name of the table.
​
data.datamartTables.datamartTableColumns
array
Array of columns in the table.
​
data.datamartTables.datamartTableColumns.columnName
string
Name of the column.
​
data.datamartTables.datamartTableColumns.datatype
string
Data type of the column.
​
data.datamartTables.datamartTableColumns.alias
string
Alias for the column.
​
data.datamartRelationships
array
Array of relationships defined between tables in the datamart. Can be an empty array if no relationships are configured.
​
data.datamartRelationships.parentTableName
string
Name of the parent table in the relationship.
​
data.datamartRelationships.parentColumnName
string
Column name in the parent table that participates in the relationship.
​
data.datamartRelationships.childTableName
string
Name of the child table in the relationship.
​
data.datamartRelationships.childColumnName
string
Column name in the child table that participates in the relationship.
​
data.datamartRelationships.relationshipName
string
Descriptive name for the relationship.
​
data.datamartRelationships.cardinality
string | null
The cardinality of the relationship. Can be: ManyToMany, ManyToOne, OneToMany, OneToOne, or null if not specified.
​
data.datamartRelationships.join
string | null
The type of SQL join used. Can be: INNER JOIN, LEFT JOIN, RIGHT JOIN, FULL JOIN, or null if not specified.
​
error
null
Error field, null when successful.

​
Examples

​
Error Codes

​
INVALID_DATA_APP_API_KEY
string
Missing or invalid data app - Check your API key and data app configuration
​
INTERNAL_SERVER_ERROR
string
Unexpected failure - Internal server error occurred

​
HTTP Status Code Summary

Status CodeDescription
200OK - Request successful
400Bad Request - Invalid request parameters or missing API key
401Unauthorized - Invalid or expired API token
500Internal Server Error - Unexpected server error

​
Possible Errors

CodeMessageHTTP Status
INVALID_DATA_APP_API_KEYMissing or invalid data app400
INTERNAL_SERVER_ERRORUnexpected failure500

​
Usage Examples

​
Basic Usage

// Get all datamarts
const datamarts = await listDatamarts();
console.log(`Total datamarts: ${datamarts.data.length}`);

​
With Pagination

// Get first page of datamarts
const datamarts = await listDatamarts({
  isPagination: true,
  pageNumber: 1
});
console.log(`Page 1 datamarts: ${datamarts.data.length}`);

​
Processing Results

// Process each datamart
const datamarts = await listDatamarts();
datamarts.data.forEach(datamart => {
  console.log(`Datamart: ${datamart.name}`);
  console.log(`Tables: ${datamart.datamartTables.length}`);
  console.log(`Datasource: ${datamart.companyIntegration.name}`);
});

​
Best Practices

Use Pagination

Use pagination for data apps with many datamarts

Cache Results

Cache datamart lists to reduce API calls

Error Handling

Always handle API errors gracefully

Monitor Usage

Monitor API usage and response times

​
Quick Start Guide

1

Get your API token

For detailed instructions, see the API Token guide.
2

List all datamarts

Make a simple request to see all your datamarts:
curl --request GET \
  --url 'https://api.usedatabrain.com/api/v2/data-app/datamarts' \
  --header 'Authorization: Bearer dbn_live_abc123...'
Note: You can add query parameters for pagination if needed.
3

Use pagination for large lists

If you have many datamarts, enable pagination using query parameters:
curl --request GET \
  --url 'https://api.usedatabrain.com/api/v2/data-app/datamarts?isPagination=true&pageNumber=1' \
  --header 'Authorization: Bearer dbn_live_abc123...'
4

Process the results

Use the datamart information for embed configurations:
const datamarts = await listDatamarts();
datamarts.data.forEach(datamart => {
  console.log(`Datamart: ${datamart.name}`);
  console.log(`Tables: ${datamart.datamartTables.length}`);
});

​
Next Steps

Create Datamart

Create new datamarts for your data app

Delete Datamart

Remove datamarts you no longer need

Create Embed Configuration

Create embeddable configurations for your datamarts

Guest Token API

Generate secure tokens for embedded access