Integrations overview

An Integration is a saved connection to a third-party account — a Slack workspace, a Postgres database, a Google Drive, a Notion instance. You connect it once, and every other primitive references it by id: an Agent tool, a Pipeline node, or a Knowledge Base source.

Prerequisites: Installed SDK · API key set · Python 3.10+. The vectorshift CLI ships with the SDK — pip install vectorshift installs it.

Mental model

An Integration is created once and reused. It carries a stable object_id, a type (e.g. slack), a health status, and — for OAuth types — authorized_scopes.
The CLI is the fastest way to connect interactively (it opens the browser and blocks for you); the SDK is for programmatic and server-side flows. Both do the same thing.

Two ways to authenticate

How you connect a service depends entirely on how it authenticates. There are exactly two modes:

	OAuth	Form
How you connect	Approve access on the provider’s site in a browser	Supply credentials yourself (host, keys, tokens)
Browser needed?	Yes — a consent screen	No
When it’s ready	After you finish consent (`connect().wait()` polls until then)	Instantly (`connect().wait()` returns right away)
Count	60 services	16 services
Examples	Slack, Gmail, Notion, Google Drive, HubSpot, Salesforce, Jira, GitHub	Postgres, MySQL, MongoDB, Snowflake, AWS S3, Pinecone, Elasticsearch, Twilio

Not sure which a service uses? Check the full 76-type catalogue, or ask in code:

from vectorshift import IntegrationType

IntegrationType.SLACK.auth_mode        # -> AuthMode.OAUTH
IntegrationType.POSTGRES.is_form_only  # -> True
Integration.required_fields("postgres")  # -> ('host', 'database', 'username', 'password')

Connect an integration

The quickest path is the CLI. The Python SDK does exactly the same thing when you need it in code — pick the auth mode that matches your service.

CLI (recommended)
Python — OAuth
Python — form credentials

# One-time: store your API key in ~/.vectorshift/config.toml
vectorshift login

# OAuth type — opens the browser, waits for consent, prints the new id
vectorshift connect slack

# Form type — pass credentials inline, created instantly (no browser)
vectorshift connect postgres \
  --cred host=db.example.com \
  --cred database=app \
  --cred username=reader \
  --cred password=secret

See the CLI reference for every command and flag.

from vectorshift import Integration

# Opens the browser (open_browser=True by default), then blocks until
# the user finishes consent. Returns the live Integration.
req = Integration.connect("slack")
integration = req.wait(on_status_change=lambda s: print(f"[{s.value}]"))
print(integration.object_id, integration.status)

On a headless host, pass open_browser=False and hand the user req.connect_url.

from vectorshift import Integration

# Form types are created instantly — wait() returns without polling.
integration = Integration.connect(
    "postgres",
    credentials={
        "host": "db.example.com",
        "database": "app",
        "username": "reader",
        "password": "secret",
    },
    name="prod-read-replica",
).wait()
print(integration.object_id, integration.status)

Required fields are validated client-side — a missing one raises MissingCredentials before any network call. Look them up with Integration.required_fields("postgres").

Where integrations plug in

An Integration is rarely the endpoint — you connect it, then reference it from another primitive:

Surface	How to reference it	Guide
Agent tool	Pass the `Integration` (static binding) or a `ToolInput(DYNAMIC)` (caller supplies it) to an `IntegrationXTool`	Integration tools
Pipeline node	`pipeline.add(name="…").integration_slack(integration=integ, …)`	Integration nodes
Knowledge Base source	Attach in the dashboard, then `integration.resync()` or `kb.resync_integration(id)` to refresh	Resync integration

The per-service action references — every tool/node action and its parameters, for all 76 integration types — are auto-generated: see Integration tools (Agents) and Integration nodes (Pipelines). This section covers connecting and managing the integrations those actions run against.

Manage what you’ve connected

from vectorshift import Integration

for i in Integration.list():           # optionally filter: list(type="slack")
    print(i.object_id, i.type, i.status, i.name)

integ = Integration.fetch(id="…")
print(integ.get_status())              # "done" | "loading" | "unhealthy"
integ.sync()                           # refresh metadata (revamped types)
integ.reauth().wait()                  # refresh expired/revoked OAuth in place
integ.delete()                         # disconnect

What’s next

CLI reference

Every vectorshift command, flag, and example.

Python reference

Integration, ConnectionRequest, types, credentials, errors.

Use in an Agent

Bind a connected integration to an agent tool.

​Mental model

​Two ways to authenticate

​Connect an integration

​Where integrations plug in

​Manage what you’ve connected

​What’s next

CLI reference

Python reference

Use in an Agent

Mental model

Two ways to authenticate

Connect an integration

Where integrations plug in

Manage what you’ve connected

What’s next