Documentation menu

Sources API#

Source reads require data:read. Creation, changes, tests, pause state, and deletion require apps:manage.

List and create#

GET/sources

Returns non-deleted sources newest first with their latest sync summary.

POST/sources

Creates a key-configured source and returns 201 with its Location. OAuth connectors use the brokered authorization flow rather than accepting OAuth secrets in this body. Staff-only, legacy-alias, and non-syncing connectors are refused.

The JSON body names connector, connector config, and secret fields accepted by that connector. Invalid fields return 400 invalid_source_parameters with param.

Inspect and change#

GET/sources/{id}

Returns source details, latest sync, and current table configuration.

PATCH/sources/{id}

Changes supported configuration or paused. A conflicting update returns 409 source_config_unavailable or 409 source_pause_failed.

DELETE/sources/{id}

Soft-deletes the source and returns {"object":"source_deletion","deleted":true,"data_retained":true}. Existing lake data remains; deletion stops future source activity.

Test a connection#

POST/sources/{id}/test

Returns supported, ok, and a deliberately generic error. PostgreSQL supports a live connection test. Other connectors can return supported: false. Credential hostnames, usernames, and destination messages are not reflected.

An inaccessible id always returns 404 source_not_found.