Authentication
Datasource APIs
Semantic Layer APIs
Embeds
Data App APIs
Metric APIs
curl --request GET \
--url 'https://api.usedatabrain.com/api/v2/workspace' \
--header 'Authorization: Bearer dbn_live_abc123...'
{
"data": [
{
"name": "Sales Analytics"
},
{
"name": "Customer Insights"
},
{
"name": "Marketing Dashboard"
}
],
"error": null
}
curl --request GET \
--url 'https://api.usedatabrain.com/api/v2/workspace' \
--header 'Authorization: Bearer dbn_live_abc123...'
{
"data": [
{
"name": "Sales Analytics"
},
{
"name": "Customer Insights"
},
{
"name": "Marketing Dashboard"
}
],
"error": null
}
Workspace APIs
List Workspaces
Retrieve all workspaces in your organization with optional pagination support for efficient data retrieval.
curl --request GET \
--url 'https://api.usedatabrain.com/api/v2/workspace' \
--header 'Authorization: Bearer dbn_live_abc123...'
{
"data": [
{
"name": "Sales Analytics"
},
{
"name": "Customer Insights"
},
{
"name": "Marketing Dashboard"
}
],
"error": null
}
GET
/
api
/
v2
/
workspace
curl --request GET \
--url 'https://api.usedatabrain.com/api/v2/workspace' \
--header 'Authorization: Bearer dbn_live_abc123...'
{
"data": [
{
"name": "Sales Analytics"
},
{
"name": "Customer Insights"
},
{
"name": "Marketing Dashboard"
}
],
"error": null
}
Retrieve a list of all workspaces in your organization. This endpoint supports pagination to efficiently handle large numbers of workspaces.
Use pagination when you have many workspaces to improve response times and reduce data transfer. The default page limit is 10 workspaces per page.
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:- In Settings page, navigate to the Service Tokens section.
- Click the “Generate Token” button to create a new service token if you don’t have one already.
Headers
Bearer token for API authentication. Use your service token.
Authorization: Bearer dbn_live_abc123...
Query Parameters
Enable pagination to retrieve workspaces in batches. Pass
"true" to enable pagination.Note: Query parameters are passed as strings. Use "true" or "false" (not boolean values)."true": Enable pagination with page-based retrieval (10 items per page)"false"(default): Return all workspaces in a single response
Show When to use pagination
Show When to use pagination
- Use pagination when you have more than 50 workspaces
- Improves response times for large datasets
- Reduces memory usage in your application
- Each page returns up to 10 workspaces
The page number to retrieve when pagination is enabled. Must be a numeric string (e.g.,
"1", "2", "3").Note: This parameter is only used when isPagination is set to "true".- Pages start at 1 (first page)
- Each page contains up to 10 workspaces
- Returns empty array if page number exceeds available pages
Response
Array of workspace objects. Returns empty array if no workspaces exist or page number exceeds available pages.
Show workspace object properties
Show workspace object properties
The name of the workspace.
Examples
HTTP Status Code Summary
| Status Code | Description |
|---|---|
200 | OK - Workspaces retrieved successfully |
401 | Unauthorized - Invalid or missing API key |
500 | Internal Server Error - Server error occurred |
Possible Errors
| Error Code | HTTP Status | Description | Solution |
|---|---|---|---|
INVALID_DATA_APP_API_KEY | 401 | Invalid API key | Verify your API key is correct and has proper permissions |
INTERNAL_SERVER_ERROR | 500 | Server error | Contact support if error persists |
Pagination Details
How pagination works
How pagination works
When
isPagination is set to true:- Each page returns up to 10 workspaces
- Pages are 1-indexed (first page is
pageNumber=1) - An empty array is returned when you’ve reached the end
- Use this to implement “load more” or infinite scroll patterns
- Request page 1 → Returns 10 workspaces
- Request page 2 → Returns 10 more workspaces
- Request page 3 → Returns 5 workspaces
- Request page 4 → Returns empty array (no more data)
When to use pagination
When to use pagination
Use pagination when:
- You have more than 50 workspaces
- Building user interfaces with “load more” functionality
- Implementing infinite scroll
- Optimizing for mobile or slow connections
- You have fewer than 20 workspaces
- You need all workspace data for processing
- Implementing search or filter functionality client-side
Best practices
Best practices
- Cache results: Store workspace lists client-side to reduce API calls
- Handle empty pages: Check for empty arrays to detect the last page
- Show loading states: Display loading indicators between page requests
- Error handling: Implement retry logic for failed requests
- Rate limiting: Respect API rate limits when fetching multiple pages
Quick Start: Implement Pagination
Implement pagination
For large workspace lists, implement pagination to efficiently fetch results page by page:
async function loadWorkspacePage(pageNumber) {
const response = await fetch(
`https://api.usedatabrain.com/api/v2/workspace?isPagination=true&pageNumber=${pageNumber}`,
{
headers: { 'Authorization': 'Bearer dbn_live_abc123...' }
}
);
return await response.json();
}
// Load first page
const page1 = await loadWorkspacePage(1);
Implement a “Load More” button that increments the page number on each click to fetch additional workspaces.
⌘I