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

Connectors

List connectors

get
/api/v1/connectors

Returns all data connectors for the organisation. Credentials are never returned; only metadata (name, type, status, etc.). Results are filtered by organisationId from the auth context.

Authorizations
AuthorizationstringRequired

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

Responses
200

Successful response

application/json
get/api/v1/connectors
GET /api/v1/connectors HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": [
    {
      "id": null,
      "organisationId": "text",
      "name": "text",
      "type": "PostgreSQL",
      "createdAt": "text",
      "updatedAt": "text",
      "status": "unconfigured",
      "errorMessage": null
    }
  ]
}

Create connector

post
/api/v1/connectors

Creates a new connector with name, type, and optional credentials. Stored in platform MongoDB; credentials are encrypted at rest. Connector starts in status "unconfigured" until used with browse/import/test.

Authorizations
AuthorizationstringRequired

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

Body
namestringRequired
typestringRequired
credentialsobject · nullableOptional
Responses
201

Successful response

application/json
post/api/v1/connectors
POST /api/v1/connectors HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 48

{
  "name": "text",
  "type": "text",
  "credentials": null
}
{
  "data": {
    "id": null,
    "organisationId": "text",
    "name": "text",
    "type": "PostgreSQL",
    "createdAt": "text",
    "updatedAt": "text",
    "status": "unconfigured",
    "errorMessage": null
  }
}

Get connector

get
/api/v1/connectors/{id}

Returns a single connector by id. Credentials are stripped from the response. 404 if not in this organisation.

Authorizations
AuthorizationstringRequired

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

Path parameters
idstringRequired

Path parameter: id

Example: 123
Responses
200

Successful response

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

{
  "data": {
    "id": null,
    "organisationId": "text",
    "name": "text",
    "type": "PostgreSQL",
    "createdAt": "text",
    "updatedAt": "text",
    "status": "unconfigured",
    "errorMessage": null
  }
}

Delete connector

delete
/api/v1/connectors/{id}

Permanently deletes the connector. Requires full permission. Does not delete sources or jobs created from prior imports.

Authorizations
AuthorizationstringRequired

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

Path parameters
idstringRequired

Path parameter: id

Example: 123
Responses
204

No Content

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

No content

Update connector

patch
/api/v1/connectors/{id}

Updates connector name and/or credentials. Other fields (type, status) are managed by the system. updatedAt is set automatically.

Authorizations
AuthorizationstringRequired

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

Path parameters
idstringRequired

Path parameter: id

Example: 123
Body
namestringOptional
credentialsobject · nullableOptional
Responses
200

Successful response

application/json
patch/api/v1/connectors/{id}
PATCH /api/v1/connectors/{id} HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 34

{
  "name": "text",
  "credentials": null
}
{
  "data": {
    "id": null,
    "organisationId": "text",
    "name": "text",
    "type": "PostgreSQL",
    "createdAt": "text",
    "updatedAt": "text",
    "status": "unconfigured",
    "errorMessage": null
  }
}

Browse connector resources

get
/api/v1/connectors/{id}/browse

Returns the browse options at one level of the connector's hierarchy (e.g. databases, then tables, then columns). Pass the current level via level and the selected ancestors as additional query parameters (e.g. ?level=tables&database=sales, then ?level=columns&database=sales&table=orders; PostgreSQL uses schema instead of database). Any query parameter other than level and search is forwarded as browse context. Connector must exist and belong to the organisation.

Authorizations
AuthorizationstringRequired

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

Path parameters
idstringRequired

Path parameter: id

Example: 123
Query parameters
levelstring · enumRequired

Hierarchy level to list, from the connector's browse hierarchy.

Example: warehousesPossible values:
searchstringOptional

Case-insensitive filter on option values/labels.

Example: example
databasestringOptional

Browse context: parent database (MySQL/ClickHouse/Snowflake).

Example: example
schemastringOptional

Browse context: parent schema (PostgreSQL/Snowflake).

Example: example
tablestringOptional

Browse context: parent table, for level=columns.

Example: example
warehousestringOptional

Browse context: warehouse (Snowflake).

Example: example
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/connectors/{id}/browse
GET /api/v1/connectors/{id}/browse?level=warehouses HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": "text"
}

Import data from connector

post
/api/v1/connectors/{id}/import

Starts an import job from the connector into a workspace. Body: workspaceId, config (the connector-specific selection: {table} or a custom {query} for SQL connectors like Snowflake/PostgreSQL/MySQL/ClickHouse, {path} for storage, {object, fields} for CRM connectors — connectorId and type are filled in from the route), optional datasetName, ontologyMode (auto | manual, default auto), and webhookUrl for a completion callback. Returns 202 with jobId; import runs asynchronously — poll jobs or sources to track progress. Use preview-query to validate custom SQL before importing.

Authorizations
AuthorizationstringRequired

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

Path parameters
idstringRequired

Path parameter: id

Example: 123
Body
workspaceIdstringRequired

Workspace the imported source lands in

datasetNamestring · nullableOptional

Name for the created source (defaults to the table/query name)

ontologyModestring · enum · nullableOptional

Whether ontology analysis runs automatically after import (default auto)

Possible values:
webhookUrlstring · uri · nullableOptional

Optional URL called once when the import completes

Responses
202

Accepted; poll the linked resource for completion

application/json
post/api/v1/connectors/{id}/import
POST /api/v1/connectors/{id}/import HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 146

{
  "workspaceId": "text",
  "config": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "datasetName": null,
  "ontologyMode": "auto",
  "webhookUrl": "https://example.com"
}
{
  "data": {
    "jobId": "text",
    "status": "text",
    "createdAt": "text",
    "links": {
      "self": "text",
      "cancel": "text"
    }
  }
}

Preview a connector dataset

post
/api/v1/connectors/{id}/preview-query

Reads the first rows of a connector dataset and returns them, or the underlying error verbatim — what to call before committing to a full import. Point it at a browsed dataset ({table} plus database/schema/warehouse for SQL connectors, {database, collection} for MongoDB, {path} for storage), or pass {query} to preview custom SQL instead; connectorId and type are filled in from the route. Optional limit defaults to 50 and is capped at 1000. Storage previews read only the head of the object, so previewing a large file is cheap. Read-only against the external system; nothing is stored.

Authorizations
AuthorizationstringRequired

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

Path parameters
idstringRequired

Path parameter: id

Example: 123
Body
limitinteger · min: 1 · max: 1000 · nullableOptional

Row cap for the preview (default 50, max 1000)

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/connectors/{id}/preview-query
POST /api/v1/connectors/{id}/preview-query HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 59

{
  "config": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "limit": 1
}
{
  "data": "text"
}

Test connector connection

post
/api/v1/connectors/{id}/test

Proxies to data-service integrations test. Validates that the connector's credentials and configuration can reach the external source. Does not modify data. Use before import to avoid failed jobs.

Authorizations
AuthorizationstringRequired

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

Path parameters
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
post/api/v1/connectors/{id}/test
POST /api/v1/connectors/{id}/test HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": "text"
}
PreviousCatalog
NextDatasets

Last updated