Sources

Manage data source connections programmatically.

The Sources API lets you list available integrations, create connections, and manage sync operations.

List Available Sources

GET /api/v1/sources

List all available integration types.

Response:

{
  "success": true,
  "sources": [
    {
      "id": "src_123",
      "name": "PostgreSQL",
      "shortName": "postgresql",
      "description": "Connect to PostgreSQL databases",
      "authMethods": ["credentials"],
      "labels": ["database"],
      "supportsContinuous": false
    }
  ]
}

Get Source Details

GET /api/v1/sources/:shortName

Get details for a specific source type, including required authentication fields.

Response:

{
  "success": true,
  "source": {
    "shortName": "postgresql",
    "name": "PostgreSQL",
    "authMethods": ["credentials"],
    "authFields": [
      {"name": "host", "type": "string", "required": true},
      {"name": "port", "type": "number", "required": true},
      {"name": "database", "type": "string", "required": true},
      {"name": "username", "type": "string", "required": true},
      {"name": "password", "type": "password", "required": true}
    ]
  }
}

Create Source Connection

POST /api/v1/source-connections

Create a new source connection for a collection.

Request:

{
  "collectionId": "col_abc123",
  "sourceShortName": "postgresql",
  "name": "Production Database",
  "credentials": {
    "host": "db.example.com",
    "port": 5432,
    "database": "myapp",
    "username": "readonly",
    "password": "..."
  }
}

Response:

{
  "success": true,
  "sourceConnection": {
    "id": "sc_xyz789",
    "name": "Production Database",
    "status": "pending",
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

List Source Connections

GET /api/v1/source-connections

List source connections, optionally filtered by collection.

Query Parameters:

Parameter	Description
`collectionId`	Filter by collection

Get Source Connection

GET /api/v1/source-connections/:id

Get details for a specific source connection.

Test Connection

POST /api/v1/source-connections/:id/test

Test that credentials are valid and the source is reachable.

Response:

{
  "success": true,
  "status": "connected",
  "message": "Connection successful"
}

Run Sync

POST /api/v1/source-connections/:id/run

Trigger an immediate sync for a source connection.

Response:

{
  "success": true,
  "syncId": "sync_123",
  "status": "started"
}

Update Credentials

PUT /api/v1/source-connections/:id/credentials

Update the credentials for a source connection.

Update Configuration

PUT /api/v1/source-connections/:id/config

Update sync configuration (tables, folders, etc.).

Delete Source Connection

DELETE /api/v1/source-connections/:id

Remove a source connection and optionally its indexed data.

Clear Indexed Data

DELETE /api/v1/source-connections/:id/data

Clear all indexed data for a source without removing the connection.

Error Responses

Status	Error	Description
`400`	`invalid_credentials`	Credential validation failed
`401`	`unauthorized`	Invalid authentication
`403`	`forbidden`	No permission for this collection
`404`	`not_found`	Source connection doesn’t exist
`409`	`sync_in_progress`	Cannot modify while syncing