API: Data Sources

Create, test, and sync connections. All endpoints require authentication unless noted. 58 endpoints.

GET /api/oauth/callback

Browser hop: the vendor’s redirect after sign-in

Query parameters

Name	Type	Required	Description
code	string	no
state	string	no
error	string	no
error_description	string	no

Responses: 200

GET /api/oauth/connections/{id}

A REST connector sign-in: its connector and non-secret values

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 200 · 400 · 401 · 404

GET /api/oauth/go

Browser hop: bind the browser to the sign-in, then redirect to the vendor

Query parameters

Name	Type	Required	Description
state	string	yes

Responses: 200

GET /api/oauth/redirect-uri

The redirect URL an OAuth client for a REST connector must allow

Responses: 200 · 400 · 401 · 404

POST /api/oauth/start

Start signing in to a REST connector’s app (OAuth); open the returned goUrl in the browser

Request body (JSON)

Field	Type	Required	Description
connector	string	yes
config	object	yes
returnTo	string	no	An app path to come back to (default /data-sources)

Responses: 200 · 400 · 401 · 404

GET /api/sources

List data sources (all of them unless limit/offset page it)

Returns every source unless paged. Pass limit (1-1000) and/or offset to page: offset without limit uses the default page size of 50.

Query parameters

Name	Type	Required	Description
limit	integer	no
offset	integer	no

Responses: 200 · 400 · 401

POST /api/sources

Create a new data source

Request body (JSON)

Field	Type	Required	Description
name	string	yes
type	"postgresql" | "redshift" | "cockroachdb" | "timescaledb" | "greenplum" | "yugabytedb" | "risingwave" | "questdb" | "hologres" | "neon" | "supabase" | "alloydb" | "materialize" | "azure_postgres" | "rds_postgres" | "cloudsql_postgres" | "paradedb" | "mysql" | "mariadb" | "tidb" | "singlestore" | "starrocks" | "doris" | "oceanbase" | "planetscale" | "azure_mysql" | "rds_mysql" | "cloudsql_mysql" | "mssql" | "azure_sql" | "azure_synapse" | "fabric_warehouse" | "snowflake" | "bigquery" | "s3" | "azure_blob" | "adls_gen2" | "gcs" | "minio" | "ceph" | "cloudflare_r2" | "backblaze_b2" | "wasabi" | "digitalocean_spaces" | "scaleway_object_storage" | "ovh_object_storage" | "ibm_cos" | "sftp" | "webhook" | "salesforce" | "hubspot" | "stripe" | "ga4" | "shopify" | "jira" | "clickhouse" | "oracle" | "ibm_db2" | "trino" | "presto" | "starburst" | "elasticsearch" | "opensearch" | "druid" | "databend" | "cratedb" | "tinybird" | "dremio" | "pinot" | "drill" | "sap_hana" | "exasol" | "vertica" | "amazon_athena" | "databricks" | "duckdb" | "motherduck"	yes
config	object	yes

Responses: 201 · 400 · 401 · 409

GET /api/sources/{id}

Get data source by ID

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 200 · 400 · 401 · 404

PUT /api/sources/{id}

Update a data source

409 when another live source in the workspace already has the new name, or when the source was changed by someone else since it was read (reload it and try again).

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
name	string	no
type	"postgresql" | "redshift" | "cockroachdb" | "timescaledb" | "greenplum" | "yugabytedb" | "risingwave" | "questdb" | "hologres" | "neon" | "supabase" | "alloydb" | "materialize" | "azure_postgres" | "rds_postgres" | "cloudsql_postgres" | "paradedb" | "mysql" | "mariadb" | "tidb" | "singlestore" | "starrocks" | "doris" | "oceanbase" | "planetscale" | "azure_mysql" | "rds_mysql" | "cloudsql_mysql" | "mssql" | "azure_sql" | "azure_synapse" | "fabric_warehouse" | "snowflake" | "bigquery" | "s3" | "azure_blob" | "adls_gen2" | "gcs" | "minio" | "ceph" | "cloudflare_r2" | "backblaze_b2" | "wasabi" | "digitalocean_spaces" | "scaleway_object_storage" | "ovh_object_storage" | "ibm_cos" | "sftp" | "webhook" | "salesforce" | "hubspot" | "stripe" | "ga4" | "shopify" | "jira" | "clickhouse" | "oracle" | "ibm_db2" | "trino" | "presto" | "starburst" | "elasticsearch" | "opensearch" | "druid" | "databend" | "cratedb" | "tinybird" | "dremio" | "pinot" | "drill" | "sap_hana" | "exasol" | "vertica" | "amazon_athena" | "databricks" | "duckdb" | "motherduck"	no
config	object	no

Responses: 200 · 400 · 401 · 404 · 409

DELETE /api/sources/{id}

Delete a data source

Path parameters

Name	Type	Required	Description
id	string	yes

Query parameters

Name	Type	Required	Description
cascade	boolean	no

Responses: 204 — No content · 401 · 404

PUT /api/sources/{id}/connector

Update an app connector source’s credentials (tested first)

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
config	object	yes

Responses: 200 · 400 · 401 · 404

POST /api/sources/{id}/discover

Start async schema discovery (returns jobId to poll)

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 202 · 400 · 401

GET /api/sources/{id}/discover/{jobId}

Poll schema discovery job status

Path parameters

Name	Type	Required	Description
id	string	yes
jobId	string	yes

Responses: 200 · 400 · 401 · 404

GET /api/sources/{id}/iceberg

An Apache Iceberg source’s settings

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 200 · 400 · 401 · 404

PUT /api/sources/{id}/iceberg

Edit an Apache Iceberg source’s tables or catalog credentials and re-stage it

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
tables	array of object	no	Catalog mode: { namespace, table }; folder mode: { location } (a URI or a folder in the storage connection, or one metadata file). name is the staged table’s name.
catalog	object	no
allowRemoved	boolean	no

Responses: 200 · 400 · 401 · 404

GET /api/sources/{id}/iceberg/namespaces

List one page of namespaces in an Iceberg source’s catalog

Path parameters

Name	Type	Required	Description
id	string	yes

Query parameters

Name	Type	Required	Description
parent	array of string	no
pageToken	string	no

Responses: 200 · 400 · 401 · 404

GET /api/sources/{id}/iceberg/tables

List one page of a namespace’s tables in an Iceberg source’s catalog

Path parameters

Name	Type	Required	Description
id	string	yes

Query parameters

Name	Type	Required	Description
namespace	array of string	yes
pageToken	string	no

Responses: 200 · 400 · 401 · 404

GET /api/sources/{id}/mongodb

A MongoDB source’s mapping

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 200 · 400 · 401 · 404

PUT /api/sources/{id}/mongodb

Edit a MongoDB source’s mapping and re-stage it

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
collections	array of object	no
uri	string	no	mongodb:// or mongodb+srv:// connection string (credentials stored encrypted; use a read-only user)
allowRemoved	boolean	no

Responses: 200 · 400 · 401 · 404

GET /api/sources/{id}/mongodb/collections

List a MongoDB source’s collections

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 200 · 400 · 401 · 404

POST /api/sources/{id}/mongodb/propose

Propose a mapping for a collection of a MongoDB source

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
collection	string	yes
sampleSize	integer	no	Documents sampled with $sample (default 1,000)
unwind	string	no	One array path to unwind: one row per element
pipeline	array of object	no	Read-only pre-filter ($match, $project …); stages that write, run JavaScript or read other collections are refused

Responses: 200 · 400 · 401 · 404

GET /api/sources/{id}/objects

List objects in a registered object store (importable ones flagged), one page at a time

Path parameters

Name	Type	Required	Description
id	string	yes

Query parameters

Name	Type	Required	Description
prefix	string	no
limit	integer	no
cursor	string	no

Responses: 200 · 400 · 401 · 404

POST /api/sources/{id}/replace

Replace the uploaded file behind a csv/excel/sqlite/parquet/json source (atomic table swap, same source id)

Multipart form with a file part (same format as the source’s original upload; json_file may add a recordsPath field; csv/excel may add a numberFormat, else the one stated at first upload applies). The file is parsed as on first upload, staged into temp tables and swapped into the source’s staging schema in one transaction. Models and dashboards keep their bindings.

Path parameters

Name	Type	Required	Description
id	string	yes

Query parameters

Name	Type	Required	Description
mode	"sync" | "async"	no	async: spool the file, queue a durable ingest job and answer 202 with it; poll GET /api/sources/ingest-jobs/{jobId}.

Responses: 200 · 202 · 400 · 401 · 404

POST /api/sources/{id}/replace-preview

Preview table, column, and model impact before replacing an uploaded source

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 200 · 400 · 401 · 404

POST /api/sources/{id}/resync

Re-pull a staged source now (atomic table swap; MongoDB collections with a watermark merge only what changed unless full)

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
allowEmpty	boolean	no
full	boolean	no

Responses: 200 · 400 · 401 · 404

GET /api/sources/{id}/schemas

List discovered schemas for a data source

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 200 · 400 · 401

GET /api/sources/{id}/schemas/{schema}/tables

List tables for a discovered schema

Path parameters

Name	Type	Required	Description
id	string	yes
schema	string	yes

Responses: 200 · 400 · 401

GET /api/sources/{id}/schemas/{schema}/tables/{table}/columns

List columns for a discovered table

Path parameters

Name	Type	Required	Description
id	string	yes
schema	string	yes
table	string	yes

Responses: 200 · 400 · 401 · 404

GET /api/sources/{id}/sync-logs

Get schema sync history

Path parameters

Name	Type	Required	Description
id	string	yes

Query parameters

Name	Type	Required	Description
limit	integer	no
offset	integer	no

Responses: 200 · 400 · 401

GET /api/sources/{id}/sync-runs

Re-sync run history

Path parameters

Name	Type	Required	Description
id	string	yes

Query parameters

Name	Type	Required	Description
limit	integer	no
offset	integer	no

Responses: 200 · 400 · 401

PUT /api/sources/{id}/sync-schedule

Schedule automatic re-sync (hourly/daily/weekly; null clears)

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
schedule	"hourly" | "daily" | "weekly"	yes

Responses: 200 · 400 · 401 · 404

POST /api/sources/{id}/sync-trigger

Signed inbound refresh trigger (no auth — HMAC verified)

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 200 · 400 · 401 · 404

PUT /api/sources/{id}/sync-trigger

Enable, disable or rotate the signed inbound refresh trigger

Enable is idempotent and preserves an existing secret. A secret is returned only on first enable or explicit rotation. Rotation requires an enabled trigger and immediately invalidates the previous secret.

Path parameters

Name	Type	Required	Description
id	string	yes

Request body (JSON)

Field	Type	Required	Description
enabled	boolean	yes
rotate	boolean	no	Explicitly replace an enabled trigger’s secret. Requires enabled: true.

Responses: 200 · 400 · 401 · 403 · 404 · 409

POST /api/sources/{id}/test

Test a saved data source connection

Path parameters

Name	Type	Required	Description
id	string	yes

Responses: 200 · 400 · 401 · 404

GET /api/sources/connector-availability

Server-dependent connector availability on this API server

Checks whether the Db2, HANA and Exasol clients load with the expected entry point, and whether the SaaS pipeline runner (Salesforce, HubSpot, Stripe, GA4, Shopify, Jira) is enabled. Does not test credentials, network access or connectivity. Results apply to this server process until restart.

Responses: 200 · 400 · 401 · 404

POST /api/sources/iceberg/namespaces

Connect to an Iceberg REST catalog and list one page of namespaces (connection test)

Request body (JSON)

Field	Type	Required	Description
catalog	object	yes
parent	array of string	no
pageToken	string	no

Responses: 200 · 400 · 401 · 404

POST /api/sources/iceberg/plan

Plan an Iceberg import: data files, bytes, rows and columns per table, or the refusal — no data file is read

Request body (JSON)

Field	Type	Required	Description
catalog	object	no
storeSourceId	string	yes	The object-store connection every file is read through
tables	array of object	yes	Catalog mode: { namespace, table }; folder mode: { location } (a URI or a folder in the storage connection, or one metadata file). name is the staged table’s name.

Responses: 200 · 400 · 401 · 404

POST /api/sources/iceberg/tables

List one page of an Iceberg catalog namespace’s tables

Request body (JSON)

Field	Type	Required	Description
catalog	object	yes
namespace	array of string	yes
pageToken	string	no

Responses: 200 · 400 · 401 · 404

POST /api/sources/import-object

Import one object from a store into a staged, queryable data source

Request body (JSON)

Field	Type	Required	Description
name	string	yes
sourceId	string	yes
key	string	yes
recordsPath	string	no

Responses: 201 · 400 · 401 · 409

POST /api/sources/import-object-prefix

Import every object under a prefix as one staged, queryable data source

Refused before anything is fetched when the objects are past the import budgets; that refusal’s details.reason is too_large_for_import (with details.objects and details.complete), so a client can offer a pipeline instead.

Request body (JSON)

Field	Type	Required	Description
name	string	yes
sourceId	string	yes
prefix	string	yes
recordsPath	string	no
hivePartitioning	boolean	no	Read key=value folders (year=2026/month=10/) as columns, as a pipeline’s Files extract does. Values are text unless typed in hiveTypes; markers, hidden folders and Delta, Hudi or Iceberg table folders are refused.
hiveTypes	object	no	Partition column types (needs hivePartitioning): partition key → string, integer, double, boolean, date or timestamp.

Responses: 201 · 400 · 401 · 409

POST /api/sources/ingest-google-sheets

Create a data source from a Google Sheet

Request body (JSON)

Field	Type	Required	Description
name	string	yes
spreadsheetId	string	yes
credentials	string	yes

Responses: 201 · 400 · 401 · 409

POST /api/sources/ingest-iceberg

Create an Apache Iceberg source — each table’s current snapshot becomes a staged table (delete files refused)

Request body (JSON)

Field	Type	Required	Description
name	string	yes
catalog	object	no
storeSourceId	string	yes	The object-store connection every file is read through
tables	array of object	yes	Catalog mode: { namespace, table }; folder mode: { location } (a URI or a folder in the storage connection, or one metadata file). name is the staged table’s name.

Responses: 201 · 400 · 401 · 409

GET /api/sources/ingest-jobs

List your recent file-import jobs

Query parameters

Name	Type	Required	Description
active	boolean	no	Only queued and running jobs.
limit	integer	no

Responses: 200 · 401

GET /api/sources/ingest-jobs/{jobId}

Get a file-import job (status, phase, rows staged, result or error)

Path parameters

Name	Type	Required	Description
jobId	string	yes

Responses: 200 · 400 · 401 · 404

POST /api/sources/ingest-jobs/{jobId}/cancel

Cancel a file-import job

A queued job is cancelled at once. A running job stops at its next row batch, or before publishing, and ends cancelled with nothing created or replaced. A job that already finished answers 409.

Path parameters

Name	Type	Required	Description
jobId	string	yes

Responses: 200 · 400 · 401 · 404 · 409

POST /api/sources/ingest-mongodb

Create a MongoDB source — each mapped collection becomes a staged table

Request body (JSON)

Field	Type	Required	Description
name	string	yes
uri	string	yes	mongodb:// or mongodb+srv:// connection string (credentials stored encrypted; use a read-only user)
database	string	yes
collections	array of object	yes

Responses: 201 · 400 · 401 · 409

POST /api/sources/ingest-rest

Create a data source from a JSON REST endpoint

Request body (JSON)

Field	Type	Required	Description
name	string	yes
url	string	yes
headers	object	no
recordsPath	string	no
tableName	string	no
pagination	object	no	How the endpoint pages (the pipelines REST extract’s schema). Omit for a single request; a response that signals more pages is then refused. Every page is fetched before anything is staged — hitting maxPages or the total size/row limit fails the import instead of truncating it. Next URLs (Link header or a URL cursor) must stay on the endpoint URL’s origin.

Responses: 201 · 400 · 401 · 409

POST /api/sources/ingest-rest-connector

Create a data source from a REST connector (one table per stream)

Request body (JSON)

Field	Type	Required	Description
name	string	yes
connector	string	yes	The manifest kind (contracts REST_CONNECTORS), e.g. ‘gitlab’
config	object	no	The connector’s field values by key. Secrets are stored encrypted and never returned. Not needed with oauthConnectionId.
oauthConnectionId	string	no	A sign-in from /api/oauth (instead of pasted credentials)
streams	array of string	no	The streams (tables) to import by name — or, for a connector that discovers them, by the table ids /rest-connector-streams returned (up to 128 characters: an OData entity set’s name); omitted = the defaults (all discovered tables, unless the connector starts with none picked; more than 200 found are refused — pick them)

Responses: 201 · 400 · 401 · 409

POST /api/sources/mongodb/collections

Connect to MongoDB and list the readable collections (connection test)

Request body (JSON)

Field	Type	Required	Description
uri	string	yes	mongodb:// or mongodb+srv:// connection string (credentials stored encrypted; use a read-only user)
database	string	yes

Responses: 200 · 400 · 401 · 404

POST /api/sources/mongodb/propose

Sample a MongoDB collection and propose a column mapping (states its sample size)

Request body (JSON)

Field	Type	Required	Description
uri	string	yes	mongodb:// or mongodb+srv:// connection string (credentials stored encrypted; use a read-only user)
database	string	yes
collection	string	yes
sampleSize	integer	no	Documents sampled with $sample (default 1,000)
unwind	string	no	One array path to unwind: one row per element
pipeline	array of object	no	Read-only pre-filter ($match, $project …); stages that write, run JavaScript or read other collections are refused

Responses: 200 · 400 · 401 · 404

POST /api/sources/rest-connector-streams

List the tables a REST connector finds in the account (connectors that discover them)

Request body (JSON)

Field	Type	Required	Description
connector	string	yes	The manifest kind (contracts REST_CONNECTORS), e.g. ‘gitlab’
config	object	no	The connector’s field values by key. Secrets are stored encrypted and never returned. Not needed with oauthConnectionId.
oauthConnectionId	string	no	A sign-in from /api/oauth (instead of pasted credentials)

Responses: 200 · 400 · 401 · 404

POST /api/sources/test

Test a data source connection

Request body (JSON)

Field	Type	Required	Description
type	"postgresql" | "redshift" | "cockroachdb" | "timescaledb" | "greenplum" | "yugabytedb" | "risingwave" | "questdb" | "hologres" | "neon" | "supabase" | "alloydb" | "materialize" | "azure_postgres" | "rds_postgres" | "cloudsql_postgres" | "paradedb" | "mysql" | "mariadb" | "tidb" | "singlestore" | "starrocks" | "doris" | "oceanbase" | "planetscale" | "azure_mysql" | "rds_mysql" | "cloudsql_mysql" | "mssql" | "azure_sql" | "azure_synapse" | "fabric_warehouse" | "snowflake" | "bigquery" | "s3" | "azure_blob" | "adls_gen2" | "gcs" | "minio" | "ceph" | "cloudflare_r2" | "backblaze_b2" | "wasabi" | "digitalocean_spaces" | "scaleway_object_storage" | "ovh_object_storage" | "ibm_cos" | "sftp" | "webhook" | "salesforce" | "hubspot" | "stripe" | "ga4" | "shopify" | "jira" | "clickhouse" | "oracle" | "ibm_db2" | "trino" | "presto" | "starburst" | "elasticsearch" | "opensearch" | "druid" | "databend" | "cratedb" | "tinybird" | "dremio" | "pinot" | "drill" | "sap_hana" | "exasol" | "vertica" | "amazon_athena" | "databricks" | "duckdb" | "motherduck"	yes
host	string	no
port	integer	no
database	string	no
user	string	no
username	string	no
password	string	no
encrypt	boolean	no
trustServerCertificate	boolean	no
account	string	no
warehouse	string	no
role	string	no
schema	string	no
httpPath	string	no
token	string	no
catalog	string	no
projectId	string	no
credentials	string	no
location	string	no
dataset	string	no
tenantId	string	no
clientId	string	no
clientSecret	string	no

Responses: 200 · 400 · 401 · 404

POST /api/sources/test-rest-connector

Test a REST connector’s credentials (one page of its test stream)

Request body (JSON)

Field	Type	Required	Description
connector	string	yes	The manifest kind (contracts REST_CONNECTORS), e.g. ‘gitlab’
config	object	no	The connector’s field values by key. Secrets are stored encrypted and never returned. Not needed with oauthConnectionId.
oauthConnectionId	string	no	A sign-in from /api/oauth (instead of pasted credentials)

Responses: 200 · 400 · 401 · 404

POST /api/sources/upload

Create a data source by uploading a CSV file

Multipart form with a file (CSV), a name field and an optional numberFormat (dot reads 1,234.56, comma reads 1.234,56 — currency symbols, % and accounting negatives included; without it only unambiguous numbers type as numbers). The file’s rows are loaded into a managed staging table and registered as a ‘csv’ data source.

Query parameters

Name	Type	Required	Description
mode	"sync" | "async"	no	async: spool the file, queue a durable ingest job and answer 202 with it; poll GET /api/sources/ingest-jobs/{jobId}.

Responses: 201 · 202 · 400 · 401 · 409

POST /api/sources/upload-excel

Create a data source by uploading an Excel (.xlsx) workbook

Multipart form with a file (.xlsx), a name field and an optional numberFormat (dot or comma; applies to numbers stored as text). Every visible non-empty sheet is loaded into a per-source staging schema and registered as an ‘excel’ data source; hidden sheets are not imported.

Query parameters

Name	Type	Required	Description
mode	"sync" | "async"	no	async: spool the file, queue a durable ingest job and answer 202 with it; poll GET /api/sources/ingest-jobs/{jobId}.

Responses: 201 · 202 · 400 · 401 · 409

POST /api/sources/upload-json

Create a data source by uploading a JSON/NDJSON file

Multipart form with a file (.json/.ndjson), a name field, and an optional recordsPath (dot path to the record array). Staged as one ‘json_file’ data source.

Query parameters

Name	Type	Required	Description
mode	"sync" | "async"	no	async: spool the file, queue a durable ingest job and answer 202 with it; poll GET /api/sources/ingest-jobs/{jobId}.

Responses: 201 · 202 · 400 · 401 · 409

POST /api/sources/upload-parquet

Create a data source by uploading a Parquet (.parquet) file

Multipart form with a file (.parquet) and a name field. The file is decoded in memory and staged as one table registered as a ‘parquet’ data source.

Query parameters

Name	Type	Required	Description
mode	"sync" | "async"	no	async: spool the file, queue a durable ingest job and answer 202 with it; poll GET /api/sources/ingest-jobs/{jobId}.

Responses: 201 · 202 · 400 · 401 · 409

POST /api/sources/upload-sqlite

Create a data source by uploading a SQLite database file

Multipart form with a file (.sqlite/.db) and a name field. Every table in the file is loaded into a per-source staging schema and registered as a ‘sqlite’ data source.

Query parameters

Name	Type	Required	Description
mode	"sync" | "async"	no	async: spool the file, queue a durable ingest job and answer 202 with it; poll GET /api/sources/ingest-jobs/{jobId}.

Responses: 201 · 202 · 400 · 401 · 409