List 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",
          "label": "Customer Records",
          "clientColumn": "id",
          "isHide": false,
          "datamartTableColumns": [
            {},
            {
              "columnName": "id",
              "datatype": "integer",
              "alias": "customer_id",
              "label": "Customer ID",
              "isHide": false
            },
            {
              "columnName": "name",
              "datatype": "varchar",
              "alias": "customer_name",
              "label": "Customer Name",
              "isHide": false
            }
          ]
        }
          ]
        }
      ],
      "datamartRelationships": [
        {
          "parentTableName": "orders",
          "parentColumnName": "customer_id",
          "childTableName": "customers",
          "childColumnName": "id",
          "relationshipName": "orders_to_customers",
          "cardinality": "ManyToOne",
          "join": "LEFT JOIN"
        }
      ]
    }
  ],
  "error": null
}

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",
          "label": "Customer Records",
          "clientColumn": "id",
          "isHide": false,
          "datamartTableColumns": [
            {},
            {
              "columnName": "id",
              "datatype": "integer",
              "alias": "customer_id",
              "label": "Customer ID",
              "isHide": false
            },
            {
              "columnName": "name",
              "datatype": "varchar",
              "alias": "customer_name",
              "label": "Customer Name",
              "isHide": false
            }
          ]
        }
          ]
        }
      ],
      "datamartRelationships": [
        {
          "parentTableName": "orders",
          "parentColumnName": "customer_id",
          "childTableName": "customers",
          "childColumnName": "id",
          "relationshipName": "orders_to_customers",
          "cardinality": "ManyToOne",
          "join": "LEFT JOIN"
        }
      ]
    }
  ],
  "error": null
}

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",
          "label": "Customer Records",
          "clientColumn": "id",
          "isHide": false,
          "datamartTableColumns": [
            {},
            {
              "columnName": "id",
              "datatype": "integer",
              "alias": "customer_id",
              "label": "Customer ID",
              "isHide": false
            },
            {
              "columnName": "name",
              "datatype": "varchar",
              "alias": "customer_name",
              "label": "Customer Name",
              "isHide": false
            }
          ]
        }
          ]
        }
      ],
      "datamartRelationships": [
        {
          "parentTableName": "orders",
          "parentColumnName": "customer_id",
          "childTableName": "customers",
          "childColumnName": "id",
          "relationshipName": "orders_to_customers",
          "cardinality": "ManyToOne",
          "join": "LEFT JOIN"
        }
      ]
    }
  ],
  "error": null
}

GET

api

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",
          "label": "Customer Records",
          "clientColumn": "id",
          "isHide": false,
          "datamartTableColumns": [
            {},
            {
              "columnName": "id",
              "datatype": "integer",
              "alias": "customer_id",
              "label": "Customer ID",
              "isHide": false
            },
            {
              "columnName": "name",
              "datatype": "varchar",
              "alias": "customer_name",
              "label": "Customer Name",
              "isHide": false
            }
          ]
        }
          ]
        }
      ],
      "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

New Endpoint (Recommended)
Legacy Endpoint (Deprecated Soon)

GET https://api.usedatabrain.com/api/v2/data-app/datamarts

Use this endpoint for all new integrations. This is the recommended endpoint format.

POST https://api.usedatabrain.com/api/v2/dataApp/datamart/list
Content-Type: application/json

{
  "isPagination": true,
  "pageNumber": 1
}

This endpoint still works but will be deprecated. Uses POST method with JSON body.

Authentication

This endpoint requires a service token in the Authorization header. Service tokens differ from data app API keys and provide organization-level permissions. To access your service token:

Go to your Databrain dashboard and open Settings.
Navigate to Settings.
Find the Service Tokens section.
Click the “Generate Token” button to generate a new service token if you don’t have one already.

Use this token as the Bearer value in your Authorization header.

Headers

Authorization

string

required

Bearer token for API authentication. Use your service token.

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.label

string

Label for the table providing a human-readable display name. Empty string when not set.

data.datamartTables.clientColumn

string | null

Client/tenant column configured for this table. null when not set.

data.datamartTables.isHide

boolean

Indicates whether the table is hidden in the datamart UI. Defaults to false.

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.datamartTables.datamartTableColumns.label

string

Label for the column providing better readability.

data.datamartTables.datamartTableColumns.isHide

boolean

Indicates whether the column is hidden in the datamart UI. Defaults to false.

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 Code	Description
200	OK - Request successful
400	Bad Request - Invalid request parameters or missing API key
401	Unauthorized - Invalid or expired API token
500	Internal Server Error - Unexpected server error

Possible Errors

Code	Message	HTTP Status
INVALID_DATA_APP_API_KEY	Missing or invalid data app	400
INTERNAL_SERVER_ERROR	Unexpected failure	500

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

Get your API token

For detailed instructions, see the Create Service Token guide.

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.

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...'

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

Embed a Pre-built Dashboard/Metric

Create embeddable configurations for your datamarts

Guest Token API

Generate secure tokens for embedded access

Create Datamart

Update Datamart

Authentication

Datasource APIs

Datamart APIs

Workspace APIs

Embeds

Data App APIs

Metric APIs

Self-Hosted APIs

Endpoint Formats

Authentication

Headers

Query Parameters

Response

Examples

Error Codes

HTTP Status Code Summary

Possible Errors

Usage Examples

Basic Usage

Processing Results

Best Practices

Use Pagination

Cache Results

Error Handling

Monitor Usage

Quick Start Guide

Next Steps

Create Datamart

Delete Datamart

Embed a Pre-built Dashboard/Metric

Guest Token API

Authentication

Datasource APIs

Datamart APIs

Workspace APIs

Embeds

Data App APIs

Metric APIs

Self-Hosted APIs

​Endpoint Formats

​Authentication

​Headers

​Query Parameters

​Response

​Examples

​Error Codes

​HTTP Status Code Summary

​Possible Errors

​Usage Examples

​Basic Usage

​With Pagination

​Processing Results

​Best Practices

Use Pagination

Cache Results

Error Handling

Monitor Usage

​Quick Start Guide

​Next Steps

Create Datamart

Delete Datamart

Embed a Pre-built Dashboard/Metric

Guest Token API

Endpoint Formats

Authentication

Headers

Query Parameters

Response

Examples

Error Codes

HTTP Status Code Summary

Possible Errors

Usage Examples

Basic Usage

With Pagination

Processing Results

Best Practices

Quick Start Guide

Next Steps