Skip to main content
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

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 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
​
pageNumber
string
default:"1"
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

​
data
array
Array of workspace objects. Returns empty array if no workspaces exist or page number exceeds available pages.
​
error
null | object
Error object if the request failed, otherwise null for successful requests.

​
Examples

​
HTTP Status Code Summary

Status CodeDescription
200OK - Workspaces retrieved successfully
401Unauthorized - Invalid or missing API key
500Internal Server Error - Server error occurred

​
Possible Errors

Error CodeHTTP StatusDescriptionSolution
INVALID_DATA_APP_API_KEY401Invalid API keyVerify your API key is correct and has proper permissions
INTERNAL_SERVER_ERROR500Server errorContact support if error persists

​
Pagination Details

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
Example flow:
  1. Request page 1 → Returns 10 workspaces
  2. Request page 2 → Returns 10 more workspaces
  3. Request page 3 → Returns 5 workspaces
  4. Request page 4 → Returns empty array (no more data)
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
Skip pagination when:
  • You have fewer than 20 workspaces
  • You need all workspace data for processing
  • Implementing search or filter functionality client-side
  • 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

1

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.