Get catalog items by type

get

/api/20210901/catalog/{type}

Returns catalog items with a given type. For example, returns a list of folders, workbooks, subject areas, analyses, dashboards, dashboard groups, dashboard pages, reports, connections, datasets, data flows, sequences, scripts, or semantic models. The output from the API is paged. Page details are available in the result headers: oa-current-page, oa-page-count, oa-next-page. The oa-next-page header isn't returned if there's no next page. Returned lists have a maximum of 10000 items.

Request

Path Parameters
  • Type of catalog item. These content types are supported
    • folders - Folders containing catalog objects.
    • workbooks - Workbooks.
    • subjectAreas - Subject areas.
    • datasets - Datasets.
    • connections - Objects containing connection details.
    • dataflows - Data flows.
    • models - Predictive and machine learning models.
    • sequences - Sequences.
    • analysis - Analyses.
    • reports - Pixel-perfect reports (BIP reports).
    • dashboards - Dashboards.
    • dashboardpages - Dashboard pages.
    • dashboardgroupfolders - Workbooks and dashboards available from the Navigation menu on the Home page.
    • scripts - Custom scripts for machine learning and data curation.
Query Parameters

There's no request body for this operation.

Back to Top

Response

Supported Media Types

200 Response

Successful operation
Headers
Body ()
Root Schema : schema
Match One Schema
Show Source
Nested Schema : CatalogItems
Type: array
Show Source
Nested Schema : TypeInfos
Type: array
Show Source
Nested Schema : CatalogItem
Match All
Show Source
Nested Schema : Discriminator: type
Type: object
Show Source
Nested Schema : CatalogItemIdRef
Type: object
Show Source
Nested Schema : CatalogItemParentIdNameRef
Type: object
Show Source
Nested Schema : TypeInfo
Type: object
Show Source
  • Allowed Values: [ "workbooks", "folders", "datasets", "connections", "dataflows", "models", "sequences", "subjectAreas", "analysis", "reports", "dashboards", "dashboardpages", "dashboardgroupfolders", "scripts" ]

400 Response

Bad Request (invalid query parameters, malformed headers, and so on).
Body ()
Root Schema : Error
Type: object
Show Source

401 Response

Unauthorized (missing or expired credentials, and so on).
Body ()
Root Schema : Error
Type: object
Show Source

500 Response

Internal Server Error. The server encountered an unexpected condition preventing fulfilment of the request.
Body ()
Root Schema : Error
Type: object
Show Source
Back to Top

Examples

These examples show you how to return all catalog items of a given type with different search criteria.

  • Example 1 - Return workbooks using a wildcard search
  • Example 2 - Return workbooks using specific search criteria
  • Example 3 - Return a list of items by type

Example 1 - Return workbooks using a wildcard search

In this example, you return a list of all the workbooks in the catalog.

cURL Example:

Run the cURL command with the wildcard search (that is, search=*):

curl -i --header 'Authorization: Bearer <token>' /
--request GET 'https://<hostname>/api/20210901/catalog/workbooks?search=*'

Example of Request Body

Not applicable.

Example of Response Header

The response from the API is paged and details of the pages can be found in the result headers: oa-current-page, oa-page-count, oa-next-page

If there isn't a next page, the oa-next-page header isn't returned.

Example of Response Body

Status 200:
[
 {
    "owner": "smith",
    "name": "Sales Workbook",
    "description": "Sales forecast 2024",
    "id": "L3NoYXJlZC9TYWxlcy9TYWxlcyBXb3JrYm9vaw==",
    "lastModified": "2024-01-01T18:59:16Z",
    "type": "workbooks",
    "parentId": "L3NoYXJlZC9TYWxlcw==" 
 }
 {
    "owner": "jones",
    "name": "Product Analysis",
    "description": "Compare UK product sales",
    "id": "L3NoYXJlZC9Qcm9kdWN0cy9Qcm9kdWN0IEFuYWx5c2lz",
    "lastModified": "2024-01-01T18:59:16Z",
    "type": "workbooks",
    "parentId": "L3NoYXJlZC9Qcm9kdWN0cw==" 
 }
 {
   ...
 }
]

The id value is the full path to the catalog object with Base64URL encoding. You can use this id value, together with the type to obtain details for any catalog object. See Get catalog item details .

Example 2 - Return workbooks using specific search criteria

In this example, you return a list of workbooks with 2024 in the name.

cURL Example:

Run the cURL command with the search string 2024 (that is, search=2024):

curl -i --header 'Authorization: Bearer <token>' \
--request GET 'https://<hostname>/api/20210901/catalog/workbooks?search=2024'

Example of Request Body

Not applicable.

Example of Response Body

Status 200:
[
 {
    "owner": "smith",
    "name": "Sales Workbook",
    "description": "Sales forecast 2024",
    "id": "L3NoYXJlZC9TYWxlcy9TYWxlcyBXb3JrYm9vaw==",
    "lastModified": "2024-01-01T18:59:16Z",
    "type": "workbooks",
    "parentId": "L3NoYXJlZC9TYWxlcw==" 
 }
]

Example 3 - Return a list of items by type

The catalog API supports various item types: folders, datasets, connections, data flows, models, sequences, subject areas, analyses, and workbooks.

These examples show the syntax required to return a list of items of each type.

cURL Example:

Run the cURL command with the search wildcard (*) or specific search criteria:

curl -i --header 'Authorization: Bearer <token>' /
--request GET 'https://<hostname>/api/20210901/catalog/<itemtype>?search=<criteria>'

Use <itemtype> to specify the type of item you want to return:

  • Folders: https://<hostname>/api/20210901/catalog/folders?search=*
  • Connections: https://<hostname>/api/20210901/catalog/connections?search=*
  • Datasets: https://<hostname>/api/20210901/catalog/datasets?search=*
  • Data flows: https://<hostname>/api/20210901/catalog/dataflows?search=*
  • Sequences: https://<hostname>/api/20210901/catalog/sequences?search=*
  • Semantic models: https://<hostname>/api/20210901/catalog/models?search=*
  • Subject areas: https://<hostname>/api/20210901/catalog/subjectAreas?search=*
  • Analyses: https://<hostname>/api/20210901/catalog/analysis?search=*
  • Workbooks: https://<hostname>/api/20210901/catalog/workbooks?search=*

Example of Request Body

The response from the API is paged and details of the pages can be found in the result headers: oa-current-page, oa-page-count, oa-next-page

Example of Response Body

Status 200:
[
 {
    "owner": "admin",
    "name": "Sales",
    "description": "Folder for sales workbooks",
    "id": "L3NoYXJlZC9TYWxlcw==",
    "lastModified": "2024-01-01T18:59:16Z",
    "type": "folders",
    "parentId": " L3NoYXJlZA==" 
 }
 {
   ...
 }
]

The id value is the full path to the catalog object with Base64URL encoding. You can use this id value, together with the type to obtain details for any catalog object. See Get catalog item details .

cURL Example - With manageContent Enabled

If you have the appropriate privileges, you can run search queries in content management mode by setting the manageContent parameter set to true. When you search in content management mode, the API can return items not owned by or shared with you. You must have the Manage Content permission or BI Service Administrator role to run the query in content management mode.

This example returns a list of all catalog objects, owned by all users:

curl -i --header 'Authorization: Bearer <token>' \
  --request GET 'https://<hostname>/api/20210901/catalog?manageContent=true&search=*'

This example returns a list of all workbooks, owned by all users:

curl -i --header 'Authorization: Bearer <token>' \
  --request GET 'https://<hostname>/api/20210901/catalog/workbooks?manageContent=true&search=*'

This example returns a list of all folders, owned by a user who left the company (john.smith@example.com):

curl -i --header 'Authorization: Bearer <token>' \
  --request GET 'https://<hostname>/api/20210901/catalog/folders?manageContent=true&search=owner: john.smith@example.com'
Back to Top