---
title: Sources API
description: List, inspect, create, change, test, pause, and delete data sources through scoped endpoints.
species: reference
---
# Sources API

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

## List and create

```endpoint
GET /sources
```

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

```endpoint
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

```endpoint
GET /sources/{id}
```

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

```endpoint
PATCH /sources/{id}
```

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

```endpoint
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

```endpoint
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`.