Connect a live source

GET    https://app.vern.so/api/v1/migrations/{migration_id}/source-connection
POST   https://app.vern.so/api/v1/migrations/{migration_id}/source-connection
DELETE https://app.vern.so/api/v1/migrations/{migration_id}/source-connection

Instead of (or in addition to) uploading files, a migration can pull its data straight from a live API source — a connector the managed agent reads from at run time. This endpoint configures, reads, and removes that connection. Once a connection exists, a generate run can extract from it with no files uploaded — see extract_via_api. If the connector still needs secrets, the run pauses at blocked and you submit credentials. {migration_id} is the id from creating a migration.

Authentication

Requires an x-api-key header. See Authentication.

Create or update a connection

POST https://app.vern.so/api/v1/migrations/{migration_id}/source-connection

Creates the connection for the migration’s workbook, or updates it in place when one already exists for the same source_key and profile.

string

required

The connector to attach, lower-cased (e.g. salesforce, hubspot). An unknown or not-yet-enabled key returns 400.

string | null

Scopes the connection to a profile. Omit to use the request’s default profile; pass null to bind it to the workbook itself rather than a profile.

object

Connector configuration (non-secret) — host, account, region, and similar fields the connector needs. Defaults to {}.

string[] | null

The streams (objects) to extract. Omit or pass null to let the connector decide.

object

Incremental-sync cursor state to resume from. Defaults to {}.

object

Secret values for the connector. Written to a secured vault and never returned, persisted on the connection row, or placed in the agent thread. You can also supply them later via Submit credentials.

Response

201 Created

{
  "source_connection": {
    "id": "9b1f2c3d-4e5a-46b7-8c9d-0e1f2a3b4c5d",
    "profile_id": null,
    "source_key": "salesforce",
    "name": "Salesforce",
    "category": "CRM",
    "config": { "instance_url": "https://acme.my.salesforce.com" },
    "selected_streams": ["contacts", "accounts"],
    "stream_state": {},
    "creds_configured": true,
    "bound_source_extractor_id": null,
    "last_snapshot": null,
    "last_sync_at": null
  }
}

Read the connection

GET https://app.vern.so/api/v1/migrations/{migration_id}/source-connection

Returns the migration’s current connection, or 404 if none is configured. The response never includes secret values — use creds_configured to tell whether credentials are on file.

string

Filter to a specific connector when more than one could match.

string

The profile to read. Pass the literal workbook to read the workbook-bound connection (the one saved with profile_id: null).

The connection object

string (uuid)

The connection ID. Echoed in a run’s credential_request so you know which connection a credential prompt belongs to.

string

The connector key you created it with.

string

The connector’s display name, suitable for your UI. Falls back to source_key.

string | null

The connector’s grouping (e.g. CRM), or null.

object

The non-secret configuration you set.

string[] | null

The streams to extract, or null for connector default.

object

The incremental-sync cursor state.

boolean

true once credentials are stored — the only signal exposed about secrets.

string | null

The authored extractor bound to this connection, once the agent has built one.

object | null

Metadata about the most recent extraction (streams, file count, timestamp), or null before the first run.

string | null

When data was last pulled, or null.

Remove the connection

DELETE https://app.vern.so/api/v1/migrations/{migration_id}/source-connection

Deletes the connection (and its stored secrets). Accepts the same optional source_key and profile_id query parameters as GET.

{ "deleted": true }

Errors

Status	Meaning
`400`	(POST) `source_key` missing, unknown, or not enabled for your account; malformed JSON.
`401`	API key missing or invalid.
`404`	(GET) no connection configured for the migration; the migration isn’t in your account.
`429`	Rate limit hit — back off and retry.
`500`	Server error.

Example

# Attach a connector and store its credentials
curl -X POST \
  https://app.vern.so/api/v1/migrations/c0a8012e-.../source-connection \
  -H "x-api-key: $VERN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_key": "salesforce",
    "config": { "instance_url": "https://acme.my.salesforce.com" },
    "selected_streams": ["contacts", "accounts"],
    "credentials": { "client_id": "…", "client_secret": "…", "refresh_token": "…" }
  }'

Start a run — set extract_via_api to pull from the connection.
Submit credentials — answer a run that paused for secrets.
Poll a run — watch the extraction and read the report.

Overview

Get started

API reference

Reference

Authentication

Create or update a connection

Response

Read the connection

The connection object

Remove the connection

Errors

Example

Next

​Authentication

​Create or update a connection

​Response

​Read the connection

​The connection object

​Remove the connection

​Errors

​Example

​Next

Authentication

Create or update a connection

Response

Read the connection

The connection object

Remove the connection

Errors

Example

Next