REST API for Oracle Analytics Cloud

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 machine learning 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(required):
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

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" ]

There's no request body for this operation.

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:

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

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

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.

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"
    ]
}

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==" 
 }
 {
   ...
 }
]

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'