Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Datasets

List datasets

get
/api/v1/workspaces/{wsId}/datasets

Lists datasets for the workspace with current ontology conceptVersions on every source. Paginated (limit, cursor).

Authorizations
AuthorizationstringRequired

An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.

Path parameters
wsIdstringRequired

Path parameter: wsId

Example: 123
Query parameters
limitnumber · min: 1 · max: 1000Optional

Page size (1-1000, default 50).

Example: 1
cursorstringOptional

Opaque cursor from a previous response's pagination.cursor.

Example: example
Responses
200

Successful response

application/json
get/api/v1/workspaces/{wsId}/datasets
GET /api/v1/workspaces/{wsId}/datasets HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": [],
  "pagination": {
    "cursor": "text",
    "hasMore": true,
    "total": 1
  }
}

Create dataset

post
/api/v1/workspaces/{wsId}/datasets

Creates a new dataset — a derived, queryable table over one or more sources. Body: name, sources, operations, optional description, tags, anchorConceptId. Every non-empty source must include conceptVersions with exactly one entry per conceptId, copied from a current GET or recommendation response; stale versions return a conflict. Returns the created dataset document.

Authorizations
AuthorizationstringRequired

An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.

Path parameters
wsIdstringRequired

Path parameter: wsId

Example: 123
Body
namestringRequired
descriptionstring · nullableOptional
tagsstring[] · nullableOptional
anchorConceptIdstring · nullableOptional
Responses
201

Successful response

application/json
dataany of · nullableRequired

Payload not declared in this repo

stringOptional
or
numberOptional
or
booleanOptional
or
or
post/api/v1/workspaces/{wsId}/datasets
POST /api/v1/workspaces/{wsId}/datasets HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 391

{
  "name": "text",
  "sources": [
    {
      "id": "text",
      "type": "text",
      "name": null,
      "conceptIds": [
        "text"
      ],
      "conceptVersions": {
        "ANY_ADDITIONAL_PROPERTY": 1
      },
      "version": {
        "kind": "text"
      }
    }
  ],
  "operations": [
    {
      "id": "text",
      "sourceId": "text",
      "config": {
        "type": "text",
        "filterGroup": {
          "column": "text",
          "comparisonOperator": "Equal to",
          "value": "text",
          "correctType": true
        }
      }
    }
  ],
  "description": null,
  "tags": [
    "text"
  ],
  "anchorConceptId": null
}
{
  "data": "text"
}

Get dataset

get
/api/v1/workspaces/{wsId}/datasets/{id}

Returns the dataset by id with current ontology conceptVersions on every source. Must belong to the workspace.

Authorizations
AuthorizationstringRequired

An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.

Path parameters
wsIdstringRequired

Path parameter: wsId

Example: 123
idstringRequired

Path parameter: id

Example: 123
Responses
200

Successful response

application/json
dataany of · nullableRequired

Payload not declared in this repo

stringOptional
or
numberOptional
or
booleanOptional
or
or
get/api/v1/workspaces/{wsId}/datasets/{id}
GET /api/v1/workspaces/{wsId}/datasets/{id} HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": "text"
}

Delete dataset

delete
/api/v1/workspaces/{wsId}/datasets/{id}

Deletes the dataset. Its sources are left intact. Requires full permission.

Authorizations
AuthorizationstringRequired

An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.

Path parameters
wsIdstringRequired

Path parameter: wsId

Example: 123
idstringRequired

Path parameter: id

Example: 123
Responses
204

No Content

No content
delete/api/v1/workspaces/{wsId}/datasets/{id}
DELETE /api/v1/workspaces/{wsId}/datasets/{id} HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update dataset

patch
/api/v1/workspaces/{wsId}/datasets/{id}

Updates name, description, tags, sources, operations, anchorConceptId. A sources update must round-trip conceptVersions from a current GET and include exactly one version per conceptId; stale versions return a conflict. Changing sources/operations may change schema and row count.

Authorizations
AuthorizationstringRequired

An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.

Path parameters
wsIdstringRequired

Path parameter: wsId

Example: 123
idstringRequired

Path parameter: id

Example: 123
Body
namestringOptional
descriptionstring · nullableOptional
tagsstring[]Optional
anchorConceptIdstring · nullableOptional
Responses
200

Successful response

application/json
dataany of · nullableRequired

Payload not declared in this repo

stringOptional
or
numberOptional
or
booleanOptional
or
or
patch/api/v1/workspaces/{wsId}/datasets/{id}
PATCH /api/v1/workspaces/{wsId}/datasets/{id} HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 237

{
  "name": "text",
  "description": null,
  "tags": [
    "text"
  ],
  "sources": [
    {
      "id": "text",
      "type": "text",
      "name": null,
      "conceptIds": [
        "text"
      ],
      "conceptVersions": {
        "ANY_ADDITIONAL_PROPERTY": 1
      },
      "version": {
        "kind": "text"
      }
    }
  ],
  "operations": [],
  "anchorConceptId": null
}
{
  "data": "text"
}

Get recommended datasets

get
/api/v1/workspaces/{wsId}/datasets/recommended

Returns recommended dataset definitions for the workspace (e.g. based on ontology or usage). Used to suggest datasets to create.

Authorizations
AuthorizationstringRequired

An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.

Path parameters
wsIdstringRequired

Path parameter: wsId

Example: 123
Responses
200

Successful response

application/json
dataany of · nullableRequired

Payload not declared in this repo

stringOptional
or
numberOptional
or
booleanOptional
or
or
get/api/v1/workspaces/{wsId}/datasets/recommended
GET /api/v1/workspaces/{wsId}/datasets/recommended HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": "text"
}

Get enriched dataset

get
/api/v1/workspaces/{wsId}/datasets/{id}/enriched

Returns the dataset with enriched metadata: output schema, column metadata, row count, concept metadata, operation details. Use when you need full schema and stats without fetching records.

Authorizations
AuthorizationstringRequired

An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.

Path parameters
wsIdstringRequired

Path parameter: wsId

Example: 123
idstringRequired

Path parameter: id

Example: 123
Responses
200

Successful response

application/json
dataany of · nullableRequired

Payload not declared in this repo

stringOptional
or
numberOptional
or
booleanOptional
or
or
get/api/v1/workspaces/{wsId}/datasets/{id}/enriched
GET /api/v1/workspaces/{wsId}/datasets/{id}/enriched HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": "text"
}

Get dataset metadata

get
/api/v1/workspaces/{wsId}/datasets/{id}/metadata

Returns schema entries, column metadata, and row count for the dataset in one call. More efficient than fetching schema and records separately when you only need structure and count.

Authorizations
AuthorizationstringRequired

An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.

Path parameters
wsIdstringRequired

Path parameter: wsId

Example: 123
idstringRequired

Path parameter: id

Example: 123
Responses
200

Successful response

application/json
dataany of · nullableRequired

Payload not declared in this repo

stringOptional
or
numberOptional
or
booleanOptional
or
or
get/api/v1/workspaces/{wsId}/datasets/{id}/metadata
GET /api/v1/workspaces/{wsId}/datasets/{id}/metadata HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": "text"
}

Get dataset records

get
/api/v1/workspaces/{wsId}/datasets/{id}/records

Returns paginated rows from the dataset. Query params: limit (default 50, max 1000), cursor (opaque, from the previous response's pagination.cursor). Data is computed on demand from sources and operations; no materialisation.

Authorizations
AuthorizationstringRequired

An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.

Path parameters
wsIdstringRequired

Path parameter: wsId

Example: 123
idstringRequired

Path parameter: id

Example: 123
Query parameters
limitnumber · min: 1 · max: 1000Optional

Page size (1-1000, default 50).

Example: 1
cursorstringOptional

Opaque cursor from a previous response's pagination.cursor.

Example: example
Responses
200

Successful response

application/json
get/api/v1/workspaces/{wsId}/datasets/{id}/records
GET /api/v1/workspaces/{wsId}/datasets/{id}/records HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": [],
  "pagination": {
    "cursor": "text",
    "hasMore": true,
    "total": 1
  }
}

Get dataset schema

get
/api/v1/workspaces/{wsId}/datasets/{id}/schema

Returns the output schema (list of schema entries) for the dataset. Reflects the result of applying all operations to the sources.

Authorizations
AuthorizationstringRequired

An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.

Path parameters
wsIdstringRequired

Path parameter: wsId

Example: 123
idstringRequired

Path parameter: id

Example: 123
Responses
200

Successful response

application/json
dataany of · nullableRequired

Payload not declared in this repo

stringOptional
or
numberOptional
or
booleanOptional
or
or
get/api/v1/workspaces/{wsId}/datasets/{id}/schema
GET /api/v1/workspaces/{wsId}/datasets/{id}/schema HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": "text"
}

Validate an operations chain

post
/api/v1/workspaces/{wsId}/datasets/{id}/validate

Validates an operations chain without persisting anything — a schema dry-run. Body: sources, operations (same shape as a dataset). Returns sourceSchemas, operationSchemas (schema after each step), finalSchema, and the enriched dataset preview. Use to check schema and metadata before creating or updating a dataset.

Authorizations
AuthorizationstringRequired

An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.

Path parameters
wsIdstringRequired

Path parameter: wsId

Example: 123
idstringRequired

Path parameter: id

Example: 123
Body
Responses
200

Successful response

application/json
dataany of · nullableRequired

Payload not declared in this repo

stringOptional
or
numberOptional
or
booleanOptional
or
or
post/api/v1/workspaces/{wsId}/datasets/{id}/validate
POST /api/v1/workspaces/{wsId}/datasets/{id}/validate HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 319

{
  "sources": [
    {
      "id": "text",
      "type": "text",
      "name": null,
      "conceptIds": [
        "text"
      ],
      "conceptVersions": {
        "ANY_ADDITIONAL_PROPERTY": 1
      },
      "version": {
        "kind": "text"
      }
    }
  ],
  "operations": [
    {
      "id": "text",
      "sourceId": "text",
      "config": {
        "type": "text",
        "filterGroup": {
          "column": "text",
          "comparisonOperator": "Equal to",
          "value": "text",
          "correctType": true
        }
      }
    }
  ]
}
{
  "data": "text"
}

Export dataset

get
/api/v1/workspaces/{wsId}/datasets/{id}/export/{format}

Streams the dataset result as a file. Path param format: csv, json, or parquet. Response is streaming with appropriate Content-Type and Content-Disposition. Requires exports:read scope.

Authorizations
AuthorizationstringRequired

An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.

Path parameters
formatstring · enumRequired

Export format

Example: csvPossible values:
Responses
200

Successful response

application/octet-stream
dataany of · nullableRequired

Payload not declared in this repo

stringOptional
or
numberOptional
or
booleanOptional
or
or
get/api/v1/workspaces/{wsId}/datasets/{id}/export/{format}
GET /api/v1/workspaces/{wsId}/datasets/{id}/export/{format} HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": "text"
}
PreviousConnectors
NextDigital Twins

Last updated