Coginiti API Reference

The Coginiti HTTP API enables users to interact with Coginiti through third-party applications. The API provides three main sets of endpoints for browsing the catalog, executing queries and scripts, and managing users and groups through SCIM integration.

Overview

Base URL

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

{hostname}/api/v1

Replace {hostname} with your Coginiti instance hostname.

Supported Formats

Request Format: JSON
Response Format: JSON, CSV, Arrow Stream (execution endpoints)
Date Format: ISO 8601 (e.g., 2023-02-14T19:28:40.840Z)

Authentication

The Coginiti HTTP API requires authentication with a personal access token created in the Coginiti UI.

Personal Access Tokens

API requests that use a token must use the Authorization header. The header's value must specify the Bearer type followed by a space and the access token:

Authorization: Bearer {Token}

Creating a Personal Access Token

Login to your Coginiti Team/Enterprise application
In the upper-right corner of any page, click your profile icon, then click API Keys
In the left sidebar click "Add" button to create a new entry for your token
Under Token name, enter a name for the token
Optionally, under Description, add a note to describe the purpose of the token
Under Expiration, select an expiration for the token
(For admin accounts only) Select an owner of the token if needed
Click Save button

Security

Personal access tokens are like passwords and share the same inherent security risks. Keep your tokens secure, do not store them as plain text, and do not expose them to other persons. The token is only displayed once when created.

Deleting a Personal Access Token

Login to your Coginiti Team/Enterprise application
Click your profile icon, then click API Keys
Select the token you want to delete
Click Delete button

Once deleted, any scripts or applications using this token will no longer be able to access the Coginiti API.

Error Handling

Coginiti API uses conventional HTTP response codes to indicate the success or failure of an API request.

HTTP Status Codes

Code	Description
`200`	OK - Everything worked as expected
`400`	Bad Request - The request was unacceptable since it didn't pass validation
`401`	Unauthorized - No valid API key was provided
`403`	Forbidden - The API key doesn't have permission to perform the request
`404`	Not Found - The requested resource doesn't exist
`409`	Conflict - The request conflicts with another request
`500, 502, 503, 504`	Server Errors - Something went wrong on Coginiti's side

Error Response Format

Error messages are sent back in the response body using the following format:

{
    "message": "The request was unacceptable, since it didn't pass validation",
    "detail": "Name field should not be blank"
}

Field	Description
`message`	A brief human-readable message
`detail`	A lengthier explanation of the error (optional)

Catalog Browse API

The Catalog Browse API allows users to browse and retrieve catalog assets from their Coginiti workspace.

List Catalog Assets

List catalog assets by the given path. The response contains direct children of the given folder.

Endpoint: GET /catalog/list/{path}

Parameters:

path: Path of the asset with forward slash separators. Must be URL-encoded. Should start from namespace: @Personal, @Shared, @Project Hub

Example Request:

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

Response Fields:

Field	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 the asset was created (UTC)
`updated_at`	Date and time the asset was updated (UTC)

Asset Types:

Type	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

Project Hub Path Convention: For @Project Hub assets, the path should begin with @Project Hub/{project name}/ rather than the full absolute path. For example: @Project Hub/sales_2025/folder/of/the/project

Errors:

Condition	Status	Detail
Path not found	404	Path not found: @Personal/Reports
Path points to asset instead of folder	400	Not a folder: @Personal/Reports/asset1
No permission for path	403	You don't have permission to perform the request

Get Catalog Asset by Path

Retrieve a single asset by path.

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

Example Request:

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

Response Fields:

Field	Description
`name`	Name of the catalog asset
`description`	Asset description
`path`	Absolute path of the asset within Catalog
`type`	Asset type
`data`	Object containing asset-type specific properties
`created_at`	Date and time the asset was created (UTC)
`updated_at`	Date and time the asset was updated (UTC)

For SQL_SCRIPT and COGINITI_SCRIPT types, the data object contains:

Field	Description
`content`	Content of the SQL/CoginitiScript file

Execution API

The Execution API allows users to execute catalog assets and retrieve data sets with governance controls. It's compatible with popular data visualization tools like PowerBI, Excel, and Jupyter Notebooks, as well as orchestration tools like Dagster or Kestra.

Execute Script

Execute a script from the catalog and get a single result set. If the script produces multiple result sets, only the first one is returned.

Endpoint: POST /exec/script

Request Body:

{
  "path": "@Personal/Reports/performance",
  "params": {
    "start_date": "2012-01-01",
    "end_date": "2012-12-31"
  },
  "connection": {
    "name": "My Connection"
  }
}

Request Fields:

Field	Description
`path`	Absolute path to the catalog asset within the catalog
`params`	Object with parameter names and values for script substitution
`connection.name`	Name of the connection

Example Request:

curl -X POST '{hostname}/api/v1/exec/script' \
  --header 'Authorization: Bearer _YOUR_ACCESS_TOKEN_HERE_' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
  "path": "@Personal/Reports/performance",
  "params": {
    "start_date": "2012-01-01",
    "end_date": "2012-12-31"
  },
  "connection": {
    "name": "My Connection"
  }
}'

Response:

{
    "result": {
        "columns": [
            {
                "name": "col_1",
                "type": "INTEGER"
            },
            {
                "name": "col_2",
                "type": "STRING"
            }
        ],
        "data": [
            [1, "a"],
            [2, "b"]
        ]
    },
    "stats": {
        "started_at": "2023-08-10T15:06:57.581939751Z",
        "finished_at": "2023-08-10T15:07:57.581939751Z",
        "duration_ms": 1000
    }
}

Response Headers:

X-Coginiti-Execution-Started-At: 2023-11-01T10:03:17.354799859Z

Execute CoginitiScript Block

Execute a specific CoginitiScript block from a catalog asset.

Endpoint: POST /exec/block

Request Body:

{
  "package": "@Personal/My Projects/demo/customers",
  "block_name": "CustomersWithEmailDomain",
  "args": {
    "domain": "coginiti.co"
  },
  "params": {},
  "connection": {
    "name": "My Connection"
  }
}

Request Fields:

Field	Description
`package`	Absolute path to the CoginitiScript package
`block_name`	Name of the block to execute
`args`	Object with argument names and values for the block
`params`	Object with parameter names and values for script substitution
`connection.name`	Name of the connection

Complex Arguments:

You can pass lists and maps as block arguments using JSON:

# Passing a list
curl -X POST '{hostname}/api/v1/exec/block' \
  --header 'Authorization: Bearer _YOUR_ACCESS_TOKEN_HERE_' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "package": "@Personal/My Projects/demo/customers",
  "block_name": "CustomersWithEmailDomain",
  "args": {
    "domains": ["coginiti.co", "gmail.com"]
  },
  "connection": {
    "name": "My Connection"
  }
}'

# Passing a map
curl -X POST '{hostname}/api/v1/exec/block' \
  --data-raw '{
  "args": {
    "payment_fees": {
      "credit_card": 0.25,
      "paypal": 0.3
    }
  }
}'

Response Formats

The Accept request header specifies the response format:

application/json (default)
text/csv
application/vnd.apache.arrow.stream

Running CoginitiScript Tests

Execute CoginitiScript tests for automated data quality testing and CI/CD workflows.

Individual Test Block:

curl -X POST '{hostname}/api/v1/exec/block' \
  --header 'Authorization: Bearer _YOUR_ACCESS_TOKEN_HERE_' \
  --data-raw '{
  "package": "@Personal/data_quality_tests",
  "block_name": "TestCustomerDataIntegrity",
  "connection": {
    "name": "My Connection"
  }
}'

Test Suite with test.Run():

curl -X POST '{hostname}/api/v1/exec/script' \
  --data-raw '{
  "path": "@Personal/test_suites/nightly_tests",
  "connection": {
    "name": "My Connection"
  }
}'

Test Response Format:

{
    "tests": [
        {
            "package_name": "@Personal/data_quality_tests",
            "test_name": "TestCustomerEmailFormat",
            "status": "PASSED",
            "message": "Test passed",
            "started_at": "2023-11-01T10:03:17.500Z",
            "finished_at": "2023-11-01T10:03:18.250Z",
            "duration_ms": 750
        },
        {
            "package_name": "@Personal/data_quality_tests",
            "test_name": "TestOrderIntegrity",
            "status": "FAILED",
            "message": "Test assertion failed: The test returned non-empty recordset",
            "started_at": "2023-11-01T10:03:18.250Z",
            "finished_at": "2023-11-01T10:03:19.100Z",
            "duration_ms": 850
        }
    ],
    "stats": {
        "tests": 2,
        "passed": 1,
        "failed": 1,
        "started_at": "2023-11-01T10:03:17.354Z",
        "finished_at": "2023-11-01T10:03:19.100Z",
        "duration_ms": 1746
    }
}

Test HTTP Status Codes:

Starting from version 25.6, the API returns HTTP 200 OK for test executions even when tests fail. Check the stats.failed field in the response to determine test results.

SCIM API

The SCIM (System for Cross-domain Identity Management) v2.0 API enables integration with identity providers like Azure AD, Okta, and other SCIM-compliant systems.

Base URL

{hostname}/api/v1/scim/v2

Users

List Users

Endpoint: GET /Users

Query Parameters:

Parameter	Type	Description
`count`	integer	Maximum number of users to return (e.g., 50)
`startIndex`	integer	1-based index where to start results (e.g., 11)
`filter`	string	SCIM expression to filter users (limited to userName equality)

Example Request:

curl -X GET 'https://{hostname}/api/v1/scim/v2/Users' \
  --header 'Authorization: Bearer _YOUR_ACCESS_TOKEN_HERE_'

Response:

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 1,
    "startIndex": 1,
    "itemsPerPage": 1,
    "Resources": [
        {
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User",
                "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
            ],
            "id": "user-id",
            "userName": "john.doe@example.com",
            "active": true,
            "emails": [
                {
                    "value": "john.doe@example.com",
                    "primary": true
                }
            ],
            "name": {
                "givenName": "John",
                "familyName": "Doe",
                "fullName": "John Doe",
                "formatted": "John Doe"
            },
            "displayName": "John Doe",
            "roles": [{"value": "admin"}],
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                "organization": "Example Corp",
                "superUser": false,
                "userStatus": "CONFIRMED",
                "external": false
            },
            "groups": []
        }
    ]
}

Filter Limitations:

The current SCIM implementation supports only:

userName eq "john.doe@example.com" (userName equality filters)
Other attributes and complex expressions are not yet supported
Unsupported filters return all results

Create User

Endpoint: POST /Users

Request Body:

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "userName": "testuser1",
    "active": true,
    "emails": [
        {
            "value": "testuser1@example.com",
            "primary": true
        }
    ],
    "name": {
        "givenName": "Test",
        "familyName": "User",
        "fullName": "Test User",
        "formatted": "Test User"
    },
    "displayName": "Test User",
    "roles": [{"value": "software_engineer"}],
    "password": "SecurePass123!",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "organization": "Example Corp",
        "superUser": false,
        "userStatus": "CONFIRMED",
        "external": false
    }
}

Retrieve User

Endpoint: GET /Users/{id}

Update User

Endpoint: PUT /Users/{id}

Delete User

Endpoint: DELETE /Users/{id}

Response:

{
    "status": "200"
}

Groups

List Groups

Endpoint: GET /Groups

Query Parameters:

Parameter	Type	Description
`count`	integer	Maximum number of groups to return
`startIndex`	integer	1-based index where to start results
`filter`	string	SCIM expression to filter groups

Response:

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 1,
    "startIndex": 1,
    "itemsPerPage": 1,
    "Resources": [
        {
            "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
            "id": "group-id",
            "displayName": "Development Team",
            "description": "Software development team",
            "external": false,
            "members": [
                {
                    "value": "user-id",
                    "display": "John Doe",
                    "$ref": "link-to-user",
                    "type": "USER"
                }
            ]
        }
    ]
}

Create Group

Endpoint: POST /Groups

Retrieve Group

Endpoint: GET /Groups/{id}

Update Group

Endpoint: PUT /Groups/{id}

Delete Group

Endpoint: DELETE /Groups/{id}

Integration Examples

CI/CD Pipeline Integration

Example bash script for processing test results in CI:

#!/bin/bash

# Execute tests via API
response=$(curl -s -X POST '{hostname}/api/v1/exec/script' \
  --header 'Authorization: Bearer ${ACCESS_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "path": "@Personal/test_suites/ci_tests",
    "connection": {
      "name": "CI Connection"
    }
  }')

# Extract test statistics
failed_tests=$(echo "$response" | jq '.stats.failed')
total_tests=$(echo "$response" | jq '.stats.tests')

echo "Test Results: $((total_tests - failed_tests))/$total_tests passed"

# Exit with error code if any tests failed
if [ "$failed_tests" -gt 0 ]; then
  echo "$failed_tests test(s) failed"
  echo "$response" | jq '.tests[] | select(.status == "FAILED") | {test_name, message}'
  exit 1
else
  echo "All tests passed"
  exit 0
fi

Support

For API support and questions:

Documentation: docs.coginiti.co
Support: support.coginiti.co
Community: Ask questions on Stack Overflow

Overview​

Base URL​

Supported Formats​

Authentication​

Personal Access Tokens​

Creating a Personal Access Token​

Deleting a Personal Access Token​

Error Handling​

HTTP Status Codes​

Error Response Format​

Catalog Browse API​

List Catalog Assets​

Get Catalog Asset by Path​

Execution API​

Execute Script​

Execute CoginitiScript Block​

Response Formats​

Running CoginitiScript Tests​

SCIM API​

Base URL​

Users​

List Users​

Create User​

Retrieve User​

Update User​

Delete User​

Groups​

List Groups​

Create Group​

Retrieve Group​

Update Group​

Delete Group​

Integration Examples​

CI/CD Pipeline Integration​

Support​

Overview

Base URL

Supported Formats

Authentication

Personal Access Tokens

Creating a Personal Access Token

Deleting a Personal Access Token

Error Handling

HTTP Status Codes

Error Response Format

Catalog Browse API

List Catalog Assets

Get Catalog Asset by Path

Execution API

Execute Script

Execute CoginitiScript Block

Response Formats

Running CoginitiScript Tests

SCIM API

Base URL

Users

List Users

Create User

Retrieve User

Update User

Delete User

Groups

List Groups

Create Group

Retrieve Group

Update Group

Delete Group

Integration Examples

CI/CD Pipeline Integration

Support