Jump to

• Request
• Response
• Examples

Get catalog items

get

/api/20210901/catalog

Without search criteria, returns a list of supported catalog item types. With search criteria, returns catalog items that match the criteria specified. Returned lists have a maximum of 10000 items. For information about the search syntax, see Search Options.

Request

Query Parameters

• excludedFields: string
  Comma separated list of fields to exclude from response.
• fields: string
  Comma separated list of fields to include in response.
• limit: integer
  Number of catalog items per page.
• manageContent: boolean
  If true, search is performed in content management mode. You need Manage Content permission to enable content management mode.
• page: integer
  Page number.
• search: string
  Search string.
• sortBy: string
  Sort by criteria.
• sortOrder: string
  Sort order.

  Allowed Values: [ "ASC", "DESC" ]
• type:
  Catalog item type filter. These content filter 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.

There's no request body for this operation.

Back to Top

Response

Supported Media Types

• application/json

200 Response

Successful operation

Headers

• oa-current-page:
• oa-next-page:
• oa-page-count:
• oa-prev-page:
• oa-total-items:

Body ()

Root Schema : schema

Match One Schema

Show Source

• array CatalogItems
• array TypeInfos

{
    "oneOf":[
        {
            "$ref":"#/components/schemas/CatalogItems"
        },
        {
            "$ref":"#/components/schemas/TypeInfos"
        }
    ]
}

Nested Schema : CatalogItems

Type: array

Show Source

• Array of: CatalogItem

{
    "type":"array",
    "items":{
        "$ref":"#/components/schemas/CatalogItem"
    }
}

Nested Schema : TypeInfos

Type: array

Show Source

• Array of: object TypeInfo

{
    "type":"array",
    "items":{
        "$ref":"#/components/schemas/TypeInfo"
    }
}

Nested Schema : CatalogItem

Match All

Show Source

• object CatalogItemIdRef
• object CatalogItemParentIdNameRef
• object Discriminator: type
  Discriminator: { "propertyName":"type" }

{
    "allOf":[
        {
            "$ref":"#/components/schemas/CatalogItemIdRef"
        },
        {
            "$ref":"#/components/schemas/CatalogItemParentIdNameRef"
        },
        {
            "type":"object",
            "properties":{
                "description":{
                    "type":"string",
                    "description":"Catalog item description, if any"
                },
                "type":{
                    "allOf":[
                        {
                            "$ref":"#/components/schemas/Types"
                        },
                        {
                            "description":"Catalog item type"
                        },
                        {
                        }
                    ]
                },
                "owner":{
                    "type":"string",
                    "description":"Catalog item owner"
                },
                "lastModified":{
                    "type":"string",
                    "format":"date-time",
                    "description":"Catalog item last modified date and time"
                }
            },
            "discriminator":{
                "propertyName":"type"
            }
        }
    ]
}

Nested Schema : Discriminator: type

Type: object

{
    "type":"object",
    "properties":{
        "description":{
            "type":"string",
            "description":"Catalog item description, if any"
        },
        "type":{
            "allOf":[
                {
                    "$ref":"#/components/schemas/Types"
                },
                {
                    "description":"Catalog item type"
                },
                {
                }
            ]
        },
        "owner":{
            "type":"string",
            "description":"Catalog item owner"
        },
        "lastModified":{
            "type":"string",
            "format":"date-time",
            "description":"Catalog item last modified date and time"
        }
    },
    "discriminator":{
        "propertyName":"type"
    }
}

Show Source

• description: string
  Catalog item description, if any
• lastModified: string (date-time)
  Catalog item last modified date and time
• owner: string
  Catalog item owner
• type: type

{
    "type":"object",
    "properties":{
        "description":{
            "type":"string",
            "description":"Catalog item description, if any"
        },
        "type":{
            "allOf":[
                {
                    "$ref":"#/components/schemas/Types"
                },
                {
                    "description":"Catalog item type"
                },
                {
                }
            ]
        },
        "owner":{
            "type":"string",
            "description":"Catalog item owner"
        },
        "lastModified":{
            "type":"string",
            "format":"date-time",
            "description":"Catalog item last modified date and time"
        }
    },
    "discriminator":{
        "propertyName":"type"
    }
}

Nested Schema : CatalogItemIdRef

Type: object

Show Source

• id: string
  Catalog item identifier

{
    "type":"object",
    "properties":{
        "id":{
            "type":"string",
            "description":"Catalog item identifier"
        }
    }
}

Nested Schema : CatalogItemParentIdNameRef

Type: object

Show Source

• name: string
  Catalog item name
• parentId: string
  Catalog parent item identifier (if catalog item has a parent)

{
    "type":"object",
    "properties":{
        "parentId":{
            "type":"string",
            "description":"Catalog parent item identifier (if catalog item has a parent)"
        },
        "name":{
            "type":"string",
            "description":"Catalog item name"
        }
    }
}

Nested Schema : TypeInfo

Type: object

Show Source

• type: string
  Allowed Values: [ "workbooks", "folders", "datasets", "connections", "dataflows", "models", "sequences", "subjectAreas", "analysis", "reports", "dashboards", "dashboardpages", "dashboardgroupfolders", "scripts" ]

{
    "type":"object",
    "properties":{
        "type":{
            "$ref":"#/components/schemas/Types"
        }
    }
}

400 Response

Bad Request (invalid query parameters, malformed headers, and so on).

Body ()

Root Schema : Error

Type: object

Show Source

• code(required): string
  Short error code that defines the error, meant for programmatic parsing.
• message(required): string
  Human-readable error string.

{
    "type":"object",
    "properties":{
        "code":{
            "type":"string",
            "description":"Short error code that defines the error, meant for programmatic parsing.\n"
        },
        "message":{
            "type":"string",
            "description":"Human-readable error string.\n"
        }
    },
    "required":[
        "code",
        "message"
    ]
}

401 Response

Unauthorized (missing or expired credentials, and so on).

Body ()

Root Schema : Error

Type: object

Show Source

• code(required): string
  Short error code that defines the error, meant for programmatic parsing.
• message(required): string
  Human-readable error string.

{
    "type":"object",
    "properties":{
        "code":{
            "type":"string",
            "description":"Short error code that defines the error, meant for programmatic parsing.\n"
        },
        "message":{
            "type":"string",
            "description":"Human-readable error string.\n"
        }
    },
    "required":[
        "code",
        "message"
    ]
}

500 Response

Internal Server Error. The server encountered an unexpected condition preventing fulfilment of the request.

Body ()

Root Schema : Error

Type: object

Show Source

• code(required): string
  Short error code that defines the error, meant for programmatic parsing.
• message(required): string
  Human-readable error string.

{
    "type":"object",
    "properties":{
        "code":{
            "type":"string",
            "description":"Short error code that defines the error, meant for programmatic parsing.\n"
        },
        "message":{
            "type":"string",
            "description":"Human-readable error string.\n"
        }
    },
    "required":[
        "code",
        "message"
    ]
}

Back to Top

Examples

This example shows you how to obtain a list of the types of catalog object that the catalog REST API supports.

cURL Example - No Search Criteria

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

Example of Request Body

Not applicable.

Example of Response Body

Status 200:

[
    {"type": "workbooks"},
    {"type": "folders"},
    {"type": "datasets"},
    {"type": "connections"},
    {"type": "dataflows"},
    {"type": "models"},
    {"type": "sequences"},
    {"type": "subjectAreas"},
    {"type": "analysis"},
    {"type": "reports"},
    {"type": "dashboardgroupfolders"},
    {"type": "dashboardfolders"},
    {"type": "dashboardpages"},
    {"type": "dashboards"},
    {"type": "scripts"}]

cURL Example - With Search Criteria

You can add search query criteria to the search parameter in the cURL command to further refine the results of your search. This example includes search criteria that returns workbooks owned by [e-mail] that contain the word sales in the name and a column called Product.

curl -i --header 'Authorization: Bearer <token>' \
--request GET 'https://<hostname>/api/20210901/catalog/workbooks?search=owner:[e-mail] name:sales
      columns:Product'

cURL Example - With Subitem Search Criteria

You can also use the search query parameter to search for items within container objects (such as folders or dashboards). This example returns all the subitems in the shared/Sales folder.

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

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 ([e-mail]):

curl -i --header 'Authorization: Bearer <token>' \
  --request GET 'https://<hostname>/api/20210901/catalog/folders?manageContent=true&search=owner: [e-mail]'

Back to Top