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

Sources

List organisation sources

get
/api/v1/sources

Lists sources across the whole organisation, including ones not linked into any workspace. Sources are org-owned; a workspace sees one only through a link, so this is where to look when a workspace appears to have no data. Query params: limit, cursor, parentId (folder id, or 'all' to flatten the tree), format, search, sortBy, sortDir. Reads platform MongoDB.

Authorizations
AuthorizationstringRequired

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

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
parentIdstringOptional

Only return sources derived from this source.

Example: 123
formatstringOptional

Filter by data format.

Example: example
searchstringOptional

Case-insensitive filter on source name.

Example: example
sortBystringOptional

Field to sort by (default createdAt).

Example: example
sortDirstring · enumOptional

Sort direction (default desc).

Example: ascPossible values:
Responses
200

Successful response

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

{
  "data": [
    {
      "id": "text",
      "workspaceId": null,
      "organisationId": "text",
      "name": "text",
      "parentSourceId": null,
      "dataSource": "Local Upload",
      "dataFormat": "Folder",
      "description": null,
      "richDescription": {
        "markdown": "text",
        "widgets": [
          "[Circular Reference]"
        ]
      },
      "schemaEntries": [
        {
          "field": "text",
          "type": "None",
          "subtype": "Integer",
          "availableTypes": [
            "None"
          ],
          "isIndex": null,
          "categories": [
            "text"
          ],
          "aliases": [
            "text"
          ],
          "description": null,
          "displayWidth": null,
          "originalFormat": null,
          "displayFormat": null,
          "unit": null,
          "unitModifier": null,
          "dateOrderAssumed": null
        }
      ],
      "ontologyMode": "auto",
      "documentCount": null,
      "columnMetadata": {
        "ANY_ADDITIONAL_PROPERTY": {
          "dtype": null,
          "categoryOccurences": {
            "ANY_ADDITIONAL_PROPERTY": 1
          },
          "distribution": {
            "ANY_ADDITIONAL_PROPERTY": 1
          },
          "rangeFrom": "text",
          "rangeTo": "text",
          "mean": null,
          "stringPattern": null,
          "jsonObjectFraction": null,
          "cardinality": null,
          "nullFraction": null,
          "processing": null,
          "metadataStatus": "complete",
          "elementType": "None",
          "minSize": null,
          "maxSize": null,
          "avgSize": null,
          "medianSize": null,
          "p95Size": null,
          "nullCount": null,
          "emptyCount": null,
          "totalElementCount": null,
          "sizeDistribution": {
            "empty": 0,
            "oneToThree": 0,
            "fourToTen": 0,
            "elevenToFifty": 0,
            "fiftyPlus": 0
          },
          "uniqueElementCount": null,
          "avgUniquePerRow": null,
          "elementOccurences": {
            "ANY_ADDITIONAL_PROPERTY": 1
          },
          "elementMin": null,
          "elementMax": null,
          "elementMean": null,
          "elementSum": null,
          "elementStddev": null
        }
      },
      "extension": null,
      "totalSize": null,
      "createdAt": null,
      "lastSaved": null,
      "virtual": null,
      "ontologyStatus": "pending",
      "ontologyError": null,
      "extractionStatus": "pending",
      "extractionError": null,
      "pageCount": null,
      "derivedFromDatasetIds": [
        "text"
      ],
      "derivedVia": "document_tables",
      "extractionRecipe": {
        "mode": "schema",
        "sourceDocumentIds": [
          "text"
        ],
        "columns": [
          {
            "name": "text",
            "description": null,
            "dtype": "number",
            "categories": [
              "text"
            ],
            "trueSynonyms": [
              "text"
            ],
            "falseSynonyms": [
              "text"
            ],
            "unit": null,
            "examples": [
              []
            ],
            "conceptId": null,
            "ANY_ADDITIONAL_PROPERTY": "anything"
          }
        ],
        "entityTypes": [
          {
            "name": "text",
            "description": null,
            "columns": [
              {
                "name": "text",
                "description": null,
                "dtype": "number",
                "categories": [
                  "text"
                ],
                "trueSynonyms": [
                  "text"
                ],
                "falseSynonyms": [
                  "text"
                ],
                "unit": null,
                "examples": [
                  []
                ],
                "conceptId": null,
                "ANY_ADDITIONAL_PROPERTY": "anything"
              }
            ],
            "ANY_ADDITIONAL_PROPERTY": "anything"
          }
        ],
        "targetName": null,
        "createdAt": null,
        "lastAppendedAt": null,
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "pendingAnnotationCount": null,
      "ontologyExcludedFields": [
        {
          "field": "text",
          "reason": "text",
          "source": "auto"
        }
      ],
      "batchRanges": [
        {
          "hash": "text",
          "fileName": "text",
          "uploadedAt": "text",
          "rowStart": 1,
          "rowEnd": 1
        }
      ],
      "currentVersionId": null,
      "latestVersionOrdinal": null
    }
  ],
  "pagination": {
    "cursor": "text",
    "hasMore": true,
    "total": 1
  }
}

Get organisation source

get
/api/v1/sources/{id}

Returns one org-level source, plus linkedWorkspaceIds — the workspaces it is currently linked into. Must belong to the caller's organisation and pass the caller's sources-area access check.

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/sources/{id}
GET /api/v1/sources/{id} HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": {
    "id": "text",
    "workspaceId": null,
    "organisationId": "text",
    "name": "text",
    "parentSourceId": null,
    "dataSource": "Local Upload",
    "dataFormat": "Folder",
    "description": null,
    "richDescription": {
      "markdown": "text",
      "widgets": [
        {
          "id": "text",
          "evidenceId": "text",
          "type": "text",
          "explorerConfig": "[Circular Reference]"
        }
      ]
    },
    "schemaEntries": [
      {
        "field": "text",
        "type": "None",
        "subtype": "Integer",
        "availableTypes": [
          "None"
        ],
        "isIndex": null,
        "categories": [
          "text"
        ],
        "aliases": [
          "text"
        ],
        "description": null,
        "displayWidth": null,
        "originalFormat": null,
        "displayFormat": null,
        "unit": null,
        "unitModifier": null,
        "dateOrderAssumed": null
      }
    ],
    "ontologyMode": "auto",
    "documentCount": null,
    "columnMetadata": {
      "ANY_ADDITIONAL_PROPERTY": {
        "dtype": null,
        "categoryOccurences": {
          "ANY_ADDITIONAL_PROPERTY": 1
        },
        "distribution": {
          "ANY_ADDITIONAL_PROPERTY": 1
        },
        "rangeFrom": "text",
        "rangeTo": "text",
        "mean": null,
        "stringPattern": null,
        "jsonObjectFraction": null,
        "cardinality": null,
        "nullFraction": null,
        "processing": null,
        "metadataStatus": "complete",
        "elementType": "None",
        "minSize": null,
        "maxSize": null,
        "avgSize": null,
        "medianSize": null,
        "p95Size": null,
        "nullCount": null,
        "emptyCount": null,
        "totalElementCount": null,
        "sizeDistribution": {
          "empty": 0,
          "oneToThree": 0,
          "fourToTen": 0,
          "elevenToFifty": 0,
          "fiftyPlus": 0
        },
        "uniqueElementCount": null,
        "avgUniquePerRow": null,
        "elementOccurences": {
          "ANY_ADDITIONAL_PROPERTY": 1
        },
        "elementMin": null,
        "elementMax": null,
        "elementMean": null,
        "elementSum": null,
        "elementStddev": null
      }
    },
    "extension": null,
    "totalSize": null,
    "createdAt": null,
    "lastSaved": null,
    "virtual": null,
    "ontologyStatus": "pending",
    "ontologyError": null,
    "extractionStatus": "pending",
    "extractionError": null,
    "pageCount": null,
    "derivedFromDatasetIds": [
      "text"
    ],
    "derivedVia": "document_tables",
    "extractionRecipe": {
      "mode": "schema",
      "sourceDocumentIds": [
        "text"
      ],
      "columns": [
        {
          "name": "text",
          "description": null,
          "dtype": "number",
          "categories": [
            "text"
          ],
          "trueSynonyms": [
            "text"
          ],
          "falseSynonyms": [
            "text"
          ],
          "unit": null,
          "examples": [
            []
          ],
          "conceptId": null,
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "entityTypes": [
        {
          "name": "text",
          "description": null,
          "columns": [
            {
              "name": "text",
              "description": null,
              "dtype": "number",
              "categories": [
                "text"
              ],
              "trueSynonyms": [
                "text"
              ],
              "falseSynonyms": [
                "text"
              ],
              "unit": null,
              "examples": [
                []
              ],
              "conceptId": null,
              "ANY_ADDITIONAL_PROPERTY": "anything"
            }
          ],
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "targetName": null,
      "createdAt": null,
      "lastAppendedAt": null,
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "pendingAnnotationCount": null,
    "ontologyExcludedFields": [
      {
        "field": "text",
        "reason": "text",
        "source": "auto"
      }
    ],
    "batchRanges": [
      {
        "hash": "text",
        "fileName": "text",
        "uploadedAt": "text",
        "rowStart": 1,
        "rowEnd": 1
      }
    ],
    "currentVersionId": null,
    "latestVersionOrdinal": null,
    "linkedWorkspaceIds": [
      "text"
    ]
  }
}

List sources

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

Lists sources in the workspace. Query params: limit, cursor (for pagination), parentId (filter by parent folder), format (Tabular or Folder). Excludes virtual sources. Results from platform MongoDB.

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
parentIdstringOptional

Only return sources derived from this source.

Example: 123
formatstring · enumOptional

Filter by data format.

Example: TabularPossible values:
Responses
200

Successful response

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

{
  "data": [
    {
      "id": "text",
      "workspaceId": null,
      "organisationId": "text",
      "name": "text",
      "parentSourceId": null,
      "dataSource": "Local Upload",
      "dataFormat": "Folder",
      "description": null,
      "richDescription": {
        "markdown": "text",
        "widgets": [
          "[Circular Reference]"
        ]
      },
      "schemaEntries": [
        {
          "field": "text",
          "type": "None",
          "subtype": "Integer",
          "availableTypes": [
            "None"
          ],
          "isIndex": null,
          "categories": [
            "text"
          ],
          "aliases": [
            "text"
          ],
          "description": null,
          "displayWidth": null,
          "originalFormat": null,
          "displayFormat": null,
          "unit": null,
          "unitModifier": null,
          "dateOrderAssumed": null
        }
      ],
      "ontologyMode": "auto",
      "documentCount": null,
      "columnMetadata": {
        "ANY_ADDITIONAL_PROPERTY": {
          "dtype": null,
          "categoryOccurences": {
            "ANY_ADDITIONAL_PROPERTY": 1
          },
          "distribution": {
            "ANY_ADDITIONAL_PROPERTY": 1
          },
          "rangeFrom": "text",
          "rangeTo": "text",
          "mean": null,
          "stringPattern": null,
          "jsonObjectFraction": null,
          "cardinality": null,
          "nullFraction": null,
          "processing": null,
          "metadataStatus": "complete",
          "elementType": "None",
          "minSize": null,
          "maxSize": null,
          "avgSize": null,
          "medianSize": null,
          "p95Size": null,
          "nullCount": null,
          "emptyCount": null,
          "totalElementCount": null,
          "sizeDistribution": {
            "empty": 0,
            "oneToThree": 0,
            "fourToTen": 0,
            "elevenToFifty": 0,
            "fiftyPlus": 0
          },
          "uniqueElementCount": null,
          "avgUniquePerRow": null,
          "elementOccurences": {
            "ANY_ADDITIONAL_PROPERTY": 1
          },
          "elementMin": null,
          "elementMax": null,
          "elementMean": null,
          "elementSum": null,
          "elementStddev": null
        }
      },
      "extension": null,
      "totalSize": null,
      "createdAt": null,
      "lastSaved": null,
      "virtual": null,
      "ontologyStatus": "pending",
      "ontologyError": null,
      "extractionStatus": "pending",
      "extractionError": null,
      "pageCount": null,
      "derivedFromDatasetIds": [
        "text"
      ],
      "derivedVia": "document_tables",
      "extractionRecipe": {
        "mode": "schema",
        "sourceDocumentIds": [
          "text"
        ],
        "columns": [
          {
            "name": "text",
            "description": null,
            "dtype": "number",
            "categories": [
              "text"
            ],
            "trueSynonyms": [
              "text"
            ],
            "falseSynonyms": [
              "text"
            ],
            "unit": null,
            "examples": [
              []
            ],
            "conceptId": null,
            "ANY_ADDITIONAL_PROPERTY": "anything"
          }
        ],
        "entityTypes": [
          {
            "name": "text",
            "description": null,
            "columns": [
              {
                "name": "text",
                "description": null,
                "dtype": "number",
                "categories": [
                  "text"
                ],
                "trueSynonyms": [
                  "text"
                ],
                "falseSynonyms": [
                  "text"
                ],
                "unit": null,
                "examples": [
                  []
                ],
                "conceptId": null,
                "ANY_ADDITIONAL_PROPERTY": "anything"
              }
            ],
            "ANY_ADDITIONAL_PROPERTY": "anything"
          }
        ],
        "targetName": null,
        "createdAt": null,
        "lastAppendedAt": null,
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "pendingAnnotationCount": null,
      "ontologyExcludedFields": [
        {
          "field": "text",
          "reason": "text",
          "source": "auto"
        }
      ],
      "batchRanges": [
        {
          "hash": "text",
          "fileName": "text",
          "uploadedAt": "text",
          "rowStart": 1,
          "rowEnd": 1
        }
      ],
      "currentVersionId": null,
      "latestVersionOrdinal": null
    }
  ],
  "pagination": {
    "cursor": "text",
    "hasMore": true,
    "total": 1
  }
}

Create source

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

Creates an empty source (metadata only). Body: name, dataFormat (default Tabular), optional description, parentSourceId. No data is written; use upload, from-data, or connector import to add data. The source record is created in platform MongoDB; data-service is not called until first upload.

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
dataFormatstring · enumRequiredDefault: TabularPossible values:
descriptionstring · nullableOptional
parentSourceIdstring · nullableOptional
Responses
201

Successful response

application/json
post/api/v1/workspaces/{wsId}/sources
POST /api/v1/workspaces/{wsId}/sources HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 79

{
  "name": "text",
  "dataFormat": "Tabular",
  "description": null,
  "parentSourceId": null
}
{
  "data": {
    "id": "text",
    "workspaceId": null,
    "organisationId": "text",
    "name": "text",
    "parentSourceId": null,
    "dataSource": "Local Upload",
    "dataFormat": "Folder",
    "description": null,
    "richDescription": {
      "markdown": "text",
      "widgets": [
        {
          "id": "text",
          "evidenceId": "text",
          "type": "text",
          "explorerConfig": "[Circular Reference]"
        }
      ]
    },
    "schemaEntries": [
      {
        "field": "text",
        "type": "None",
        "subtype": "Integer",
        "availableTypes": [
          "None"
        ],
        "isIndex": null,
        "categories": [
          "text"
        ],
        "aliases": [
          "text"
        ],
        "description": null,
        "displayWidth": null,
        "originalFormat": null,
        "displayFormat": null,
        "unit": null,
        "unitModifier": null,
        "dateOrderAssumed": null
      }
    ],
    "ontologyMode": "auto",
    "documentCount": null,
    "columnMetadata": {
      "ANY_ADDITIONAL_PROPERTY": {
        "dtype": null,
        "categoryOccurences": {
          "ANY_ADDITIONAL_PROPERTY": 1
        },
        "distribution": {
          "ANY_ADDITIONAL_PROPERTY": 1
        },
        "rangeFrom": "text",
        "rangeTo": "text",
        "mean": null,
        "stringPattern": null,
        "jsonObjectFraction": null,
        "cardinality": null,
        "nullFraction": null,
        "processing": null,
        "metadataStatus": "complete",
        "elementType": "None",
        "minSize": null,
        "maxSize": null,
        "avgSize": null,
        "medianSize": null,
        "p95Size": null,
        "nullCount": null,
        "emptyCount": null,
        "totalElementCount": null,
        "sizeDistribution": {
          "empty": 0,
          "oneToThree": 0,
          "fourToTen": 0,
          "elevenToFifty": 0,
          "fiftyPlus": 0
        },
        "uniqueElementCount": null,
        "avgUniquePerRow": null,
        "elementOccurences": {
          "ANY_ADDITIONAL_PROPERTY": 1
        },
        "elementMin": null,
        "elementMax": null,
        "elementMean": null,
        "elementSum": null,
        "elementStddev": null
      }
    },
    "extension": null,
    "totalSize": null,
    "createdAt": null,
    "lastSaved": null,
    "virtual": null,
    "ontologyStatus": "pending",
    "ontologyError": null,
    "extractionStatus": "pending",
    "extractionError": null,
    "pageCount": null,
    "derivedFromDatasetIds": [
      "text"
    ],
    "derivedVia": "document_tables",
    "extractionRecipe": {
      "mode": "schema",
      "sourceDocumentIds": [
        "text"
      ],
      "columns": [
        {
          "name": "text",
          "description": null,
          "dtype": "number",
          "categories": [
            "text"
          ],
          "trueSynonyms": [
            "text"
          ],
          "falseSynonyms": [
            "text"
          ],
          "unit": null,
          "examples": [
            []
          ],
          "conceptId": null,
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "entityTypes": [
        {
          "name": "text",
          "description": null,
          "columns": [
            {
              "name": "text",
              "description": null,
              "dtype": "number",
              "categories": [
                "text"
              ],
              "trueSynonyms": [
                "text"
              ],
              "falseSynonyms": [
                "text"
              ],
              "unit": null,
              "examples": [
                []
              ],
              "conceptId": null,
              "ANY_ADDITIONAL_PROPERTY": "anything"
            }
          ],
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "targetName": null,
      "createdAt": null,
      "lastAppendedAt": null,
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "pendingAnnotationCount": null,
    "ontologyExcludedFields": [
      {
        "field": "text",
        "reason": "text",
        "source": "auto"
      }
    ],
    "batchRanges": [
      {
        "hash": "text",
        "fileName": "text",
        "uploadedAt": "text",
        "rowStart": 1,
        "rowEnd": 1
      }
    ],
    "currentVersionId": null,
    "latestVersionOrdinal": null
  }
}

Get source

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

Returns the source by id from platform MongoDB. Must belong to the workspace. Includes schemaEntries, columnMetadata, documentCount, totalSize if populated by upload or from-data.

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
get/api/v1/workspaces/{wsId}/sources/{id}
GET /api/v1/workspaces/{wsId}/sources/{id} HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": {
    "id": "text",
    "workspaceId": null,
    "organisationId": "text",
    "name": "text",
    "parentSourceId": null,
    "dataSource": "Local Upload",
    "dataFormat": "Folder",
    "description": null,
    "richDescription": {
      "markdown": "text",
      "widgets": [
        {
          "id": "text",
          "evidenceId": "text",
          "type": "text",
          "explorerConfig": "[Circular Reference]"
        }
      ]
    },
    "schemaEntries": [
      {
        "field": "text",
        "type": "None",
        "subtype": "Integer",
        "availableTypes": [
          "None"
        ],
        "isIndex": null,
        "categories": [
          "text"
        ],
        "aliases": [
          "text"
        ],
        "description": null,
        "displayWidth": null,
        "originalFormat": null,
        "displayFormat": null,
        "unit": null,
        "unitModifier": null,
        "dateOrderAssumed": null
      }
    ],
    "ontologyMode": "auto",
    "documentCount": null,
    "columnMetadata": {
      "ANY_ADDITIONAL_PROPERTY": {
        "dtype": null,
        "categoryOccurences": {
          "ANY_ADDITIONAL_PROPERTY": 1
        },
        "distribution": {
          "ANY_ADDITIONAL_PROPERTY": 1
        },
        "rangeFrom": "text",
        "rangeTo": "text",
        "mean": null,
        "stringPattern": null,
        "jsonObjectFraction": null,
        "cardinality": null,
        "nullFraction": null,
        "processing": null,
        "metadataStatus": "complete",
        "elementType": "None",
        "minSize": null,
        "maxSize": null,
        "avgSize": null,
        "medianSize": null,
        "p95Size": null,
        "nullCount": null,
        "emptyCount": null,
        "totalElementCount": null,
        "sizeDistribution": {
          "empty": 0,
          "oneToThree": 0,
          "fourToTen": 0,
          "elevenToFifty": 0,
          "fiftyPlus": 0
        },
        "uniqueElementCount": null,
        "avgUniquePerRow": null,
        "elementOccurences": {
          "ANY_ADDITIONAL_PROPERTY": 1
        },
        "elementMin": null,
        "elementMax": null,
        "elementMean": null,
        "elementSum": null,
        "elementStddev": null
      }
    },
    "extension": null,
    "totalSize": null,
    "createdAt": null,
    "lastSaved": null,
    "virtual": null,
    "ontologyStatus": "pending",
    "ontologyError": null,
    "extractionStatus": "pending",
    "extractionError": null,
    "pageCount": null,
    "derivedFromDatasetIds": [
      "text"
    ],
    "derivedVia": "document_tables",
    "extractionRecipe": {
      "mode": "schema",
      "sourceDocumentIds": [
        "text"
      ],
      "columns": [
        {
          "name": "text",
          "description": null,
          "dtype": "number",
          "categories": [
            "text"
          ],
          "trueSynonyms": [
            "text"
          ],
          "falseSynonyms": [
            "text"
          ],
          "unit": null,
          "examples": [
            []
          ],
          "conceptId": null,
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "entityTypes": [
        {
          "name": "text",
          "description": null,
          "columns": [
            {
              "name": "text",
              "description": null,
              "dtype": "number",
              "categories": [
                "text"
              ],
              "trueSynonyms": [
                "text"
              ],
              "falseSynonyms": [
                "text"
              ],
              "unit": null,
              "examples": [
                []
              ],
              "conceptId": null,
              "ANY_ADDITIONAL_PROPERTY": "anything"
            }
          ],
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "targetName": null,
      "createdAt": null,
      "lastAppendedAt": null,
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "pendingAnnotationCount": null,
    "ontologyExcludedFields": [
      {
        "field": "text",
        "reason": "text",
        "source": "auto"
      }
    ],
    "batchRanges": [
      {
        "hash": "text",
        "fileName": "text",
        "uploadedAt": "text",
        "rowStart": 1,
        "rowEnd": 1
      }
    ],
    "currentVersionId": null,
    "latestVersionOrdinal": null
  }
}

Delete source

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

Deletes the source record from platform MongoDB. Does not necessarily delete data in the data-service or object storage; cleanup may be deferred.

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}/sources/{id}
DELETE /api/v1/workspaces/{wsId}/sources/{id} HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update source

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

Updates source name and/or description only. Schema and data are not changed here.

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
Responses
200

Successful response

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

{
  "name": "text",
  "description": null
}
{
  "data": {
    "id": "text",
    "workspaceId": null,
    "organisationId": "text",
    "name": "text",
    "parentSourceId": null,
    "dataSource": "Local Upload",
    "dataFormat": "Folder",
    "description": null,
    "richDescription": {
      "markdown": "text",
      "widgets": [
        {
          "id": "text",
          "evidenceId": "text",
          "type": "text",
          "explorerConfig": "[Circular Reference]"
        }
      ]
    },
    "schemaEntries": [
      {
        "field": "text",
        "type": "None",
        "subtype": "Integer",
        "availableTypes": [
          "None"
        ],
        "isIndex": null,
        "categories": [
          "text"
        ],
        "aliases": [
          "text"
        ],
        "description": null,
        "displayWidth": null,
        "originalFormat": null,
        "displayFormat": null,
        "unit": null,
        "unitModifier": null,
        "dateOrderAssumed": null
      }
    ],
    "ontologyMode": "auto",
    "documentCount": null,
    "columnMetadata": {
      "ANY_ADDITIONAL_PROPERTY": {
        "dtype": null,
        "categoryOccurences": {
          "ANY_ADDITIONAL_PROPERTY": 1
        },
        "distribution": {
          "ANY_ADDITIONAL_PROPERTY": 1
        },
        "rangeFrom": "text",
        "rangeTo": "text",
        "mean": null,
        "stringPattern": null,
        "jsonObjectFraction": null,
        "cardinality": null,
        "nullFraction": null,
        "processing": null,
        "metadataStatus": "complete",
        "elementType": "None",
        "minSize": null,
        "maxSize": null,
        "avgSize": null,
        "medianSize": null,
        "p95Size": null,
        "nullCount": null,
        "emptyCount": null,
        "totalElementCount": null,
        "sizeDistribution": {
          "empty": 0,
          "oneToThree": 0,
          "fourToTen": 0,
          "elevenToFifty": 0,
          "fiftyPlus": 0
        },
        "uniqueElementCount": null,
        "avgUniquePerRow": null,
        "elementOccurences": {
          "ANY_ADDITIONAL_PROPERTY": 1
        },
        "elementMin": null,
        "elementMax": null,
        "elementMean": null,
        "elementSum": null,
        "elementStddev": null
      }
    },
    "extension": null,
    "totalSize": null,
    "createdAt": null,
    "lastSaved": null,
    "virtual": null,
    "ontologyStatus": "pending",
    "ontologyError": null,
    "extractionStatus": "pending",
    "extractionError": null,
    "pageCount": null,
    "derivedFromDatasetIds": [
      "text"
    ],
    "derivedVia": "document_tables",
    "extractionRecipe": {
      "mode": "schema",
      "sourceDocumentIds": [
        "text"
      ],
      "columns": [
        {
          "name": "text",
          "description": null,
          "dtype": "number",
          "categories": [
            "text"
          ],
          "trueSynonyms": [
            "text"
          ],
          "falseSynonyms": [
            "text"
          ],
          "unit": null,
          "examples": [
            []
          ],
          "conceptId": null,
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "entityTypes": [
        {
          "name": "text",
          "description": null,
          "columns": [
            {
              "name": "text",
              "description": null,
              "dtype": "number",
              "categories": [
                "text"
              ],
              "trueSynonyms": [
                "text"
              ],
              "falseSynonyms": [
                "text"
              ],
              "unit": null,
              "examples": [
                []
              ],
              "conceptId": null,
              "ANY_ADDITIONAL_PROPERTY": "anything"
            }
          ],
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "targetName": null,
      "createdAt": null,
      "lastAppendedAt": null,
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "pendingAnnotationCount": null,
    "ontologyExcludedFields": [
      {
        "field": "text",
        "reason": "text",
        "source": "auto"
      }
    ],
    "batchRanges": [
      {
        "hash": "text",
        "fileName": "text",
        "uploadedAt": "text",
        "rowStart": 1,
        "rowEnd": 1
      }
    ],
    "currentVersionId": null,
    "latestVersionOrdinal": null
  }
}

Create source from in-memory data

post
/api/v1/workspaces/{wsId}/sources/from-data

Creates a new tabular source from a JSON array of records. Body: name, data (array of objects, min length 1), optional description, parentSourceId. Platform creates the source id and record, then hands the data to the data-service, which runs full ingest (type inference, null cleaning, schema), persists to storage, then runs ontology extraction and consolidation. The response carries schemaEntries, columnMetadata, documentCount, totalSize. Use when you have in-memory data (e.g. from an API) rather than a file; avoids file upload and matches UI upload behaviour including ontology.

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

Source name

descriptionstring · nullableOptional
parentSourceIdstring · nullableOptional

Optional parent folder source to group under

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}/sources/from-data
POST /api/v1/workspaces/{wsId}/sources/from-data HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 104

{
  "name": "text",
  "data": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "description": null,
  "parentSourceId": null
}
{
  "data": "text"
}

Link sources into a workspace

post
/api/v1/workspaces/{wsId}/sources/link

Makes org-level sources visible inside this workspace. Body: sourceIds (min 1), optional parentSourceId to place them under a folder. Linking a folder brings its whole subtree. Nothing is copied or moved — one source can be linked into many workspaces. Requires write standing on the workspace, not just the sources:write scope. Returns { linked, alreadyLinked }.

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
sourceIdsstring[] · min: 1Required
parentSourceIdstring · nullableOptional
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}/sources/link
POST /api/v1/workspaces/{wsId}/sources/link HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 44

{
  "sourceIds": [
    "text"
  ],
  "parentSourceId": null
}
{
  "data": "text"
}

Unlink sources from a workspace

post
/api/v1/workspaces/{wsId}/sources/unlink

Removes sources from this workspace. Body: sourceIds (min 1). Only the link is deleted — the org-level source, its data and its ontology concepts are left intact, and other workspaces keep their links. Removing a folder takes its descendants with it. Requires write standing on 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
Body
sourceIdsstring[] · min: 1Required
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}/sources/unlink
POST /api/v1/workspaces/{wsId}/sources/unlink HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 22

{
  "sourceIds": [
    "text"
  ]
}
{
  "data": "text"
}

Extend source with additional data

post
/api/v1/workspaces/{wsId}/sources/{id}/extend

Appends data to the source from an uploaded file. Request body: raw file bytes; use header x-filename or Content-Disposition for filename. Does not run ontology processing; schema is inferred from the existing source or file. Use to add more rows without replacing existing data.

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
Header parameters
x-filenamestringRequired

Filename to store the upload under

Example: example
Body
anyOptional

Raw file bytes

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}/sources/{id}/extend
POST /api/v1/workspaces/{wsId}/sources/{id}/extend HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
x-filename: text
Content-Type: application/octet-stream
Accept: */*

{
  "data": "text"
}

Get source records

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

Returns paginated rows from the source. Query params: limit (default 50, max 1000), cursor (opaque, from the previous response's pagination.cursor). Data is read from the query engine's storage.

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}/sources/{id}/records
GET /api/v1/workspaces/{wsId}/sources/{id}/records HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

Replace source data

post
/api/v1/workspaces/{wsId}/sources/{id}/replace

Replaces all data in the source with an uploaded file. Request body: raw file bytes; x-filename or Content-Disposition for filename. Ingest (type inference, schema) is applied, then mappings for columns the file no longer contains are detached and ontology extraction is requeued in every linked workspace so each automatically maintained dataset view can adopt the replacement schema. The data replacement can succeed even if ontology reconciliation is unavailable; in that case the response includes a warning telling the client to rerun extraction. Use when you want to refresh content without creating a new source.

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
Header parameters
x-filenamestringRequired

Filename to store the upload under

Example: example
Body
anyOptional

Raw file bytes

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}/sources/{id}/replace
POST /api/v1/workspaces/{wsId}/sources/{id}/replace HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
x-filename: text
Content-Type: application/octet-stream
Accept: */*

{
  "data": "text"
}

Retry ontology processing

post
/api/v1/workspaces/{wsId}/sources/{id}/retry-ontology

Retries ontology processing for a source that previously failed (e.g. ontologyStatus extraction_failed or consolidation_failed). If extraction failed, runs extraction inline then queues consolidation; if only consolidation failed, re-queues consolidation. Returns success when the retry is accepted; processing is asynchronous.

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
post/api/v1/workspaces/{wsId}/sources/{id}/retry-ontology
POST /api/v1/workspaces/{wsId}/sources/{id}/retry-ontology HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": "text"
}

Get source schema

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

Returns source id, name, schema (schemaEntries), columnMetadata, and documentCount from platform MongoDB. No proxy; reflects the last known schema from upload or from-data. For live schema from storage, compare with 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}/sources/{id}/schema
GET /api/v1/workspaces/{wsId}/sources/{id}/schema HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": "text"
}

Sync source from its connector

post
/api/v1/workspaces/{wsId}/sources/{id}/sync

Triggers a sync for a source that is backed by a live-data connector (e.g. scheduled pull). Only meaningful for sources with a connectionConfig that supports sync; no-op or error otherwise.

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
post/api/v1/workspaces/{wsId}/sources/{id}/sync
POST /api/v1/workspaces/{wsId}/sources/{id}/sync HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": "text"
}

Upload file to source

post
/api/v1/workspaces/{wsId}/sources/{id}/upload

Uploads a file into this source (which must already exist). Request body: raw file bytes; x-filename or Content-Disposition for filename. The data-service parses the file (CSV, Excel, Parquet, etc.), runs full ingest with type inference, then runs ontology extraction and consolidation. For API-only flows, from-data is often simpler and returns the full source with schema.

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
Header parameters
x-filenamestringRequired

Filename to store the upload under

Example: example
Body
anyOptional

Raw file bytes

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}/sources/{id}/upload
POST /api/v1/workspaces/{wsId}/sources/{id}/upload HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
x-filename: text
Content-Type: application/octet-stream
Accept: */*

{
  "data": "text"
}

Export source

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

Streams the source contents as a file. Path param format: csv, json, or parquet. Response is streaming. 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}/sources/{id}/export/{format}
GET /api/v1/workspaces/{wsId}/sources/{id}/export/{format} HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": "text"
}
PreviousSimulations
NextWorkspaces

Last updated