Introduction

With the Coginiti Browse API, users can browse the Catalog assets.

 

Base URL

All API URLs referenced in this documentation have the following base URL unless otherwise specified:

{hostname}/api/v1

Authentication

The following API requires authentication with a personal access token created in the Coginiti UI. Please follow the instructions here on how to create a personal access token.

 

List Catalog Assets

The given endpoint allows users to list catalog assets by the given path. The response contains a list of catalog objects which are direct children of the given folder. For each nested folder, the user has to perform separate list requests passing the path to those folders as a parameter.

Endpoint: /catalog/list/{path}

Parameters:

• path: path of the asset that you want to get, with a forward slash to separate each level of nesting. It should be URL-encoded to replace all special characters (such as whitespaces, etc) with their UTF-8 equivalent characters. Should start from the namespace name: @Personal, @Shared.

Type of request: GET

Result format: JSON

Request example using curl application:

curl -X GET 'https://{hostname}/api/v1/catalog/list/@Personal/Reports/Sample%20Project' \
  --header 'Authorization: Bearer _YOUR_ACCESS_TOKEN_HERE_'

Response

{
    data: [
        {
            "name": "Folder 1",
            "path": "@Personal/Reports/Sample Project/Folder 1",
            "type": "REGULAR_FOLDER",
            "created_at": "2023-02-14T19:28:40.840Z",
            "updated_at": "2023-02-14T19:28:40.840Z"

        },
        {
            "name": "Asset 1",
            "path": "@Personal/Reports/Sample Project/Asset 1",
            "type": "SQL_SCRIPT",
            "created_at": "2023-02-14T19:28:40.840Z",
            "updated_at": "2023-02-14T19:28:40.840Z"
        }
    ]
}

Return an object with the "data" property which contains the list of the catalog objects found by the given path. Each object within the data list has the following structure:

name	description
name	Name of the catalog asset.
path	Path of the asset within Coginiti Catalog.
type	Type of the catalog asset.
created_at	Date and time that the catalog asset was created, in UTC format.
updated_at	Date and time that the catalog asset was updated, in UTC format.

"type" property could have following values:

name	description
REGULAR_FOLDER	Folder
USER_HOME	User home folder
SCHEDULED_EVENTS	Scheduled event
PROJECT	CoginitiScript project
SQL_SCRIPT	SQL Script
COGINITI_SCRIPT	CoginitiScript
UPLOAD_TEMPLATE	Bulk load template
DATA_INSERT_TEMPLATE	Data insert template
PROJECT_MANIFEST	Project manifest file

 

Errors

Path parameter should contain a valid path to the folder within the Catalog which user want to list. In case user passed a valid path but it points to the catalog asset, rather than to the folder, API will return an error "Not a folder: <path>" and with 400 Bad Request status code.

condition	status	detail
The path is not found	404	Path not found: @Personal/Reports
The path is found but points to the asset instead of the folder	400	Not a folder: @Personal/Reports/asset1
The user doesn't have permission for the given path	403	You don't have permission to perform the request

 

Get Catalog Asset by Path

The given endpoint allows users to get a single asset by path.

Endpoint: /catalog/by-path/{path}

Parameters:

• path: path of the asset that you want to get, with a forward slash to separate each level of nesting. It should be URL-encoded to replace all special characters (such as whitespaces, etc) with their UTF-8 equivalent characters. Should start from the namespace name: @Personal, @Shared.

Type of request: GET

Result format: JSON

Request example using curl application:

curl -X GET 'https://{hostname}/api/v1/catalog/by-path/@Personal/Reports/Sample%20Project/my_asset' \
  --header 'Authorization: Bearer _YOUR_ACCESS_TOKEN_HERE_'

Response:

{
    "name": "my_asset",
    "description": "Asset description",
    "path": "@Personal/Reports/Sample Project/my_asset",
    "type": "SQL_SCRIPT",
    "data": {
        "content": "SELECT * FROM fact_sales",
    }
    "created_at": "2023-02-14T19:28:40.840Z",
    "updated_at": "2023-02-14T19:28:40.840Z"
}

Return an object with the following structure:

name	description
name	Name of the catalog asset.
description	Catalog asset description.
path	Absolute path of the asset within Catalog.
type	Asset type.
data	Object which contains asset-type specific properties.
created_at	Date and time that the catalog object was created, in UTC format.
updated_at	Date and time that the catalog object was updated, in UTC format.

The data object has the following structure in case the asset type is SQL_SCRIPT or COGINITI_SCRIPT:

name	description
content	Content of the SQL / CoginitiScript file.

For other asset types API doesn't expose additional information via data object.

Errors

condition	status	detail
The path is not found	404	Path not found: @Personal/Reports
The user doesn't have permission for the given path	403	You don't have permission to perform the request