Skip to main content
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.
​
source_key
string
required
The connector to attach, lower-cased (e.g. salesforce, hubspot). An unknown or not-yet-enabled key returns 400.
​
profile_id
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.
​
config
object
Connector configuration (non-secret) — host, account, region, and similar fields the connector needs. Defaults to {}.
​
selected_streams
string[] | null
The streams (objects) to extract. Omit or pass null to let the connector decide.
​
stream_state
object
Incremental-sync cursor state to resume from. Defaults to {}.
​
credentials
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.
​
source_key
string
Filter to a specific connector when more than one could match.
​
profile_id
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

​
id
string (uuid)
The connection ID. Echoed in a run’s credential_request so you know which connection a credential prompt belongs to.
​
source_key
string
The connector key you created it with.
​
name
string
The connector’s display name, suitable for your UI. Falls back to source_key.
​
category
string | null
The connector’s grouping (e.g. CRM), or null.
​
config
object
The non-secret configuration you set.
​
selected_streams
string[] | null
The streams to extract, or null for connector default.
​
stream_state
object
The incremental-sync cursor state.
​
creds_configured
boolean
true once credentials are stored — the only signal exposed about secrets.
​
bound_source_extractor_id
string | null
The authored extractor bound to this connection, once the agent has built one.
​
last_snapshot
object | null
Metadata about the most recent extraction (streams, file count, timestamp), or null before the first run.
​
last_sync_at
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

StatusMeaning
400(POST) source_key missing, unknown, or not enabled for your account; malformed JSON.
401API key missing or invalid.
404(GET) no connection configured for the migration; the migration isn’t in your account.
429Rate limit hit — back off and retry.
500Server 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": "…" }
  }'

​
Next