> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vectorshift.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrations overview

> Connect third-party services (Slack, Postgres, Google Drive, Notion, …) once, then reference them from Agents, Pipelines, and Knowledge Bases.

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](https://docs.vectorshift.ai/sdk/agent/tools/integrations.md), a [Pipeline node](https://docs.vectorshift.ai/sdk/pipeline/nodes/integration.md), or a [Knowledge Base source](https://docs.vectorshift.ai/sdk/knowledge-base/examples/resync-integration.md).

> [!NOTE]
>
> **Prerequisites:** [Installed SDK](https://docs.vectorshift.ai/sdk/installation.md) · [API key set](https://docs.vectorshift.ai/sdk/authentication.md) · 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](https://docs.vectorshift.ai/sdk/integrations/reference.md#type-catalogue), or ask in code:

```python theme={"languages":{}}
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.

> [tab] CLI (recommended)
>
> ```bash theme={"languages":{}}
> # 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](https://docs.vectorshift.ai/sdk/integrations/cli.md) for every command and flag.

> [tab] Python — OAuth
>
> ```python theme={"languages":{}}
> 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`.

> [tab] Python — form credentials
>
> ```python theme={"languages":{}}
> 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`](https://docs.vectorshift.ai/sdk/integrations/reference#errors) 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](https://docs.vectorshift.ai/sdk/agent/tools/integrations.md) |
| **Pipeline node** | `pipeline.add(name="…").integration_slack(integration=integ, …)` | [Integration nodes](https://docs.vectorshift.ai/sdk/pipeline/nodes/integration.md) |
| **Knowledge Base source** | Attach in the dashboard, then `integration.resync()` or `kb.resync_integration(id)` to refresh | [Resync integration](https://docs.vectorshift.ai/sdk/knowledge-base/examples/resync-integration.md) |

> [!TIP]
>
> The per-service **action** references — every tool/node action and its parameters, for all 76 integration types — are auto-generated: see [Integration tools](https://docs.vectorshift.ai/sdk/agent/tools/integrations.md) (Agents) and [Integration nodes](https://docs.vectorshift.ai/sdk/pipeline/nodes/integration.md) (Pipelines). This section covers connecting and managing the integrations those actions run against.

## Manage what you've connected

```python theme={"languages":{}}
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

> [card] [CLI reference](https://docs.vectorshift.ai/sdk/integrations/cli.md)
>
> Every `vectorshift` command, flag, and example.

> [card] [Python reference](https://docs.vectorshift.ai/sdk/integrations/reference.md)
>
> `Integration`, `ConnectionRequest`, types, credentials, errors.

> [card] [Use in an Agent](https://docs.vectorshift.ai/sdk/agent/tools/integrations.md)
>
> Bind a connected integration to an agent tool.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.