STEP 1 OF 8

Connect

Everything in Vouchstone starts with a connector. This guide covers the Connectors page (/connectors), the live catalog of 68 real connectors — each backed by an actual driver, no placeholders (app/integrations/connectors/base.py::all_connectors() is the source of truth) — and the sync pipeline that pulls data in.

The catalog

/connectors renders GET /api/v1/connectors/catalog, one card per registered connector: Slack, GitHub, Jira, Confluence, Salesforce, Snowflake, and 60+ more. Each card shows a Sync or Actions-only badge (supports_sync on the connector's driver, not a frontend guess) — sync connectors can pull documents into the Vault; actions-only connectors can execute actions (e.g. posting a Slack message) but have nothing to fetch.

Click a card to open setup. There are two shapes, both handled by AuthorizeButton (components/connectors/AuthorizeButton.tsx):

• OAuth connectors (Notion, Google Drive, Gmail, Google Ads, and others) — you paste an OAuth Client ID and Secret you created in the provider's console first, then the button redirects your browser through the provider's consent screen back to /connectors/oauth/callback (GET /api/v1/connectors/oauth/callback on the backend).
• API-key connectors (most of the catalog — Slack, GitHub, Jira, Snowflake, etc.) — you paste the credential fields directly (API token, workspace URL, etc.) and the connector activates immediately, no redirect.

Materializing a connector from the catalog and authorizing it are two separate calls:

# 1. Materialize a connector instance from a catalog slug
curl -X POST https://your-control-plane-host/api/v1/connectors/from-catalog \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"slug": "github"}'
# -> { "id": "<connector_id>", "status": "disconnected", ... }

# 2. Authorize it (API-key style shown; OAuth connectors instead return a redirect URL)
curl -X POST https://your-control-plane-host/api/v1/connectors/{connector_id}/authorize \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"secrets": {"api_token": "your-source-api-token"}}'

Once status is connected, use the Health check action (POST /api/v1/connectors/{connector_id}/health-check) to confirm the credentials actually work before you sync anything.

Discover and sync

Discover what a connected source can pull in, then configure and trigger a sync:

# Discover available resources (repos, channels, spaces, etc.)
curl https://your-control-plane-host/api/v1/connectors/{connector_id}/resources \
  -H "Authorization: Bearer $TOKEN"
# -> { "resources": [{ "id": "org/repo", "name": "...", "type": "repo", ... }], "total": N }

# Configure what/how to sync
curl -X POST https://your-control-plane-host/api/v1/connectors/{connector_id}/sync-config \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "sync_mode": "bulk_review",
    "sync_frequency": "manual",
    "sync_scope": {"resource_ids": ["org/repo"]}
  }'

# Trigger the sync run
curl -X POST https://your-control-plane-host/api/v1/connectors/{connector_id}/sync \
  -H "Authorization: Bearer $TOKEN"
# -> { "id": "<sync_job_id>", "status": "running", "documents_fetched": 0, ... }

sync_mode controls what happens to fetched documents:

• bulk_review (default, recommended) — every fetched document is staged for your team to approve or reject before it goes anywhere. List and approve staged documents with GET /api/v1/connectors/{connector_id}/sync-jobs/{sync_job_id}/staged and POST .../staged/approve.
• selective — fetched documents skip staging and go straight to extraction. Use this only for sources you already trust completely.

This whole flow — from clicking Connect on a card to reviewing staged documents — is also fully driven from the /connectors dashboard page; the requests above are exactly what the UI sends, useful for scripting a repeatable setup (CI, a new-tenant bootstrap script, etc.).

What's next

Step 2 — Knowledge Graph: review staged documents, approve them into the Vault's Workspace and Canonical layers, and watch CKG extraction turn them into graph nodes.