Integrations reference

Everything importable from vectorshift:

from vectorshift import (
    Integration, ConnectionRequest,
    IntegrationType, ConnectionStatus, IntegrationStatus,
    IntegrationError, IntegrationNotFound, UnknownIntegrationType,
    ConnectionFailed, ConnectionExpired, ConnectionTimeout,
)

Connecting

`connect`

Integration.connect(
    type: IntegrationType | str,
    credentials: Optional[dict] = None,
    name: Optional[str] = None,
    open_browser: bool = True,
    scopes: Optional[str] = None,
    share: bool = False,
    link_expires_in: Optional[int] = None,
    require_org_member: bool = False,
    integration_id: Optional[str] = None,
) -> ConnectionRequest

async Integration.aconnect(
    type: IntegrationType | str,
    credentials: Optional[dict] = None,
    name: Optional[str] = None,
    open_browser: bool = True,
    scopes: Optional[str] = None,
    share: bool = False,
    link_expires_in: Optional[int] = None,
    require_org_member: bool = False,
    integration_id: Optional[str] = None,
) -> ConnectionRequest

Passing credentials= does an instant form-based create and returns a ConnectionRequest that is already ACTIVE. Otherwise (form, OAuth, or hybrid) it opens a hosted connect page and returns a request carrying a connect_url; drive it to completion with .wait(). Parameters

IntegrationType | str

required

The integration type. Accepts an IntegrationType, a display name ("Slack"), or a route name ("slack"). Unknown values raise UnknownIntegrationType.

Optional[dict]

default:"None"

Form credentials for a credential-capable type. When present, required fields are validated client-side and the integration is created instantly. Omit to enter them / consent in the hosted page.

Optional[str]

default:"None"

A custom name for this integration instance.

bool

default:"True"

Open connect_url in the default browser. Set False on headless hosts and hand the user req.connect_url yourself.

Optional[str]

default:"None"

Space-separated OAuth scopes to request (OAuth types only).

Return a long-lived shareable connect link without waiting. Combine with link_expires_in.

Optional[int]

default:"None"

Shareable-link TTL in seconds.

bool

default:"False"

Require the person completing the connection to be a member of your org.

Optional[str]

default:"None"

Reconnect an existing integration in place instead of creating a new one. Prefer reauth.

Returns — a ConnectionRequest.

# OAuth
integ = Integration.connect("slack").wait()

# Form — instant
integ = Integration.connect(
    "postgres",
    credentials={"host": "h", "database": "d", "username": "u", "password": "p"},
).wait()

`reauth`

integration.reauth(open_browser: bool = True, scopes: Optional[str] = None) -> ConnectionRequest

async integration.areauth(open_browser: bool = True, scopes: Optional[str] = None) -> ConnectionRequest

Reconnect this integration in place to refresh expired or revoked auth, keeping the same object_id. Opens the hosted page; .wait() resolves when done.

integ = Integration.fetch(id="integ_abc123")
if integ.get_status() == "unhealthy":
    integ.reauth().wait()

Managing

`fetch`

Integration.fetch(id: Optional[str] = None, name: Optional[str] = None) -> Integration

async Integration.afetch(id: Optional[str] = None, name: Optional[str] = None) -> Integration

Fetch by id or name — at least one is required, else ValueError.

`list`

Integration.list(type: Optional[str] = None, offset: Optional[int] = None, limit: Optional[int] = None) -> list[Integration]

async Integration.alist(type: Optional[str] = None, offset: Optional[int] = None, limit: Optional[int] = None) -> list[Integration]

List integrations visible to the API key’s org, optionally filtered by type (route name, e.g. "slack").

`get_status`

integration.get_status() -> str

async integration.aget_status() -> str

Fetch the current health status — "done", "loading", or "unhealthy" (see IntegrationStatus).

`sync` / `resync`

integration.resync() -> None
integration.sync() -> None   # alias

async integration.aresync() -> None

Trigger a global metadata resync of every vectorstore that uses this integration. Fire-and-forget; only supported for revamped integration types. See the KB resync example for the KB-aware kb.resync_integration(id) wrapper.

`refresh`

integration.refresh() -> Integration

async integration.arefresh() -> Integration

Re-fetch this integration’s fields from the server, mutating it in place and returning self.

`delete`

integration.delete() -> None

async integration.adelete() -> None

Disconnect and delete the integration.

`to_dict`

integration.to_dict() -> dict   # {"object_id": ..., "object_type": ...}

The serialized reference shape (object_id + object_type) a Pipeline node / Agent tool stores. The fluent builder and tool classes accept the Integration object directly — pipeline.add(name="…").integration_slack(integration=integ, …) — so you rarely call to_dict() yourself; reach for it only when building a node config by hand.

Sessions & catalogue

`from_session`

Integration.from_session(session_id: str) -> ConnectionRequest

async Integration.afrom_session(session_id: str) -> ConnectionRequest

Rebuild a ConnectionRequest from a persisted session_id — reconcile a delegated / share=True attempt after the original process exited.

`revoke_session`

Integration.revoke_session(session_id: str) -> None

async Integration.arevoke_session(session_id: str) -> None

Kill an outstanding connect-session; subsequent opens of its link expire.

`types`

Integration.types() -> list[IntegrationType]

The authoritative catalogue of supported types.

`required_fields`

Integration.required_fields(type: IntegrationType | str) -> tuple[str, ...]

Required credential field names for a credential-capable type (empty tuple for OAuth-only types).

Integration.required_fields("postgres")   # ('host', 'database', 'username', 'password')

`Integration`

Attributes on a fetched instance:

str

The unique id. Use to_dict() / this value to reference the integration elsewhere.

Optional[str]

Display / account name.

Optional[str]

Route name, e.g. "slack".

Optional[str]

Health status — see IntegrationStatus.

Optional[str]

Creation timestamp.

Optional[list[str]]

OAuth scopes granted.

Optional[list[str]]

Actions this connection permits.

Optional[bool]

Convenience flag for a degraded connection.

`ConnectionRequest`

One in-flight connection attempt. OAuth requests start at INITIATED with a connect_url; form requests are born ACTIVE with the Integration already attached, so wait() returns instantly. Attributes

str

The connect-session id (aliased as .id). Persist it to reconcile later via from_session.

IntegrationType

The type being connected.

ConnectionStatus

Current session status.

Optional[str]

The URL the user opens to consent / enter credentials.

`wait`

req.wait(
    timeout: float = 300.0,
    poll_interval: float = 2.0,
    on_status_change: Optional[Callable[[ConnectionStatus], None]] = None,
) -> Integration

async req.await_completion(
    timeout: float = 300.0,
    poll_interval: float = 2.0,
    on_status_change: Optional[Callable[[ConnectionStatus], None]] = None,
) -> Integration

Poll until the session is ACTIVE and return the live Integration. Raises ConnectionFailed / ConnectionExpired on a terminal bad status, and ConnectionTimeout if timeout elapses first (the attempt stays live server-side — re-open connect_url or re-poll).

req = Integration.connect("slack")
integ = req.wait(timeout=180, on_status_change=lambda s: print(s.value))

`get_status`

req.get_status() -> ConnectionStatus

async req.aget_status() -> ConnectionStatus

A single non-blocking poll; updates and returns req.status.

`get_result`

req.get_result() -> Integration

async req.aget_result() -> Integration

Return the Integration if the session is already ACTIVE; raises ConnectionFailed if not yet active. Use after a get_status() confirms ACTIVE, when you don’t want to block in wait().

Enums

`IntegrationType`

A StrEnum whose value is the display name. Members carry:

str (property)

URL-safe id the backend uses (e.g. IntegrationType.SLACK.route_name == "slack").

bool (property)

True for types that connect via credentials only (no OAuth).

AuthMode (property)

AuthMode.FORM when is_form_only, else AuthMode.OAUTH.

classmethod

Resolve a route name back to a member; unknown routes raise UnknownIntegrationType.

Passing a route name where a display name is expected also resolves (IntegrationType("slack") works).

`AuthMode`

OAUTH · FORM.

`ConnectionStatus`

The lifecycle of a ConnectionRequest: INITIATED · PENDING · ACTIVE · FAILED · EXPIRED.

`IntegrationStatus`

The health of a configured integration: LOADING · DONE · UNHEALTHY.

Type catalogue

76 supported types. route_name is what you pass to connect(...) / the CLI. Auth is OAuth (browser consent), Form (credentials only — see fields below), or OAuth + form (hybrid: connect via the hosted page or by passing credentials=).

Type	`route_name`	Auth
Box	`box`	OAuth
Google Drive	`google-drive`	OAuth
Google Docs	`google-docs`	OAuth
Google Sheets	`google-sheets`	OAuth
Google Slides	`google-slides`	OAuth
Google Calendar	`google-calendar`	OAuth
Google Ads	`google-ads`	OAuth
Google Tasks	`google-tasks`	OAuth
Google Chat	`google-chat`	OAuth
Google Contacts	`google-contacts`	OAuth
Google BigQuery	`google-big-query`	OAuth
Google Workspace Admin	`google-workspace-admin`	OAuth
Google Analytics	`google-analytics`	OAuth
Google Cloud Storage	`google-cloud-storage`	OAuth
Google Firebase Realtime DB	`google-firebase-realtime-db`	OAuth
Google Cloud Firestore	`google-cloud-firestore`	OAuth
Google Perspective	`google-perspective`	Form
Slack	`slack`	OAuth
Airtable	`airtable`	OAuth
Notion	`notion`	OAuth
Microsoft	`microsoft`	OAuth
Sharepoint	`sharepoint`	OAuth
Dropbox	`dropbox`	OAuth
Hubspot	`hubspot`	OAuth
Gmail	`gmail`	OAuth
Outlook	`outlook`	OAuth
Jira	`jira`	OAuth
Zendesk	`zendesk`	OAuth
Stripe	`stripe`	OAuth
Clickup	`clickup`	OAuth
Databricks	`databricks`	OAuth + form
Github	`github`	OAuth
Asana	`asana`	OAuth
Discord	`discord`	OAuth
Linear	`linear`	OAuth
Teams	`teams`	OAuth
Twilio	`twilio`	Form
Postgres	`postgres`	Form
MongoDB	`mongodb`	Form
MySQL	`mysql`	Form
Snowflake	`snowflake`	Form
Microsoft SQL Server	`microsoft-sql-server`	OAuth + form
Aws S3	`aws-s3`	Form
Telegram	`telegram`	OAuth + form
Reddit	`reddit`	OAuth
Pinecone	`pinecone`	Form
X	`x`	OAuth
Mailchimp	`mailchimp`	OAuth
Coda	`coda`	Form
Openweathermap	`openweathermap`	OAuth + form
Elasticsearch	`elasticsearch`	Form
Trello	`trello`	OAuth
Monday	`monday`	OAuth
Salesforce	`salesforce`	OAuth
Typeform	`typeform`	OAuth
Microsoft Calendar	`microsoft-calendar`	OAuth
Microsoft Excel	`microsoft-excel`	OAuth
Zoom	`zoom`	OAuth
Servicenow	`servicenow`	OAuth
Gitlab	`gitlab`	OAuth
Apify	`apify`	Form
Supabase	`supabase`	Form
Oracle Database	`oracle-database`	Form
Microsoft Dynamics CRM	`microsoft_dynamics_crm`	OAuth
Zoho	`zoho`	OAuth
QuickBooks	`quickbooks`	OAuth
Intercom	`intercom`	OAuth
Powerbi	`powerbi`	OAuth
Youtube	`youtube`	OAuth
Datadog	`datadog`	Form
Pager Duty	`pager-duty`	OAuth
Docusign	`docusign`	OAuth
Figma	`figma`	OAuth
Smartsheet	`smartsheet`	OAuth
Sec Edgar	`sec-edgar`	Form
Fred	`fred`	Form

Credential fields

Types you can connect by passing credentials=. Required fields are validated client-side (MissingCredentials); optional fields tune the connection.

Type	Required	Optional
`postgres`	`host`, `database`, `username`, `password`	`port`, `ssl_mode`
`mysql`	`host`, `database`, `username`, `password`	`port`, `connect_timeout`, `ssl`, `ca_certificate`, `client_certificate`, `client_private_key`, `ssh_tunnel`, `ssh_host`
`microsoft-sql-server`	`server`, `database`, `username`, `password`	`port`, `domain`, `use_tls`, `ignore_ssl_issues`, `connect_timeout`, `request_timeout`, `tds_version`
`mongodb`	`database`, `connection_uri`	—
`snowflake`	`username`, `password`, `account`, `role`	—
`oracle-database`	`user`, `password`, `connection_string`	`use_ssl`, `wallet_password`, `wallet_content`
`supabase`	`host`, `service_role_secret`	—
`aws-s3`	`access_key_id`, `secret_access_key`	`region`, `bucket_name`
`databricks`	`workspace_url`, `access_token`	—
`pinecone`	`api_key`	`region`, `environment`
`elasticsearch`	`api_key_id`, `api_key_secret`, `base_url`	—
`datadog`	`api_key`, `url`	`app_key`
`telegram`	`bot_token`	—
`twilio`	`api_key_sid`, `api_key_secret`, `account_sid`, `phone_number`	—
`apify`	`api_key`	—
`coda`	`api_key`	—
`openweathermap`	`api_key`	—
`google-perspective`	`api_key`	—
`fred`	`api_key`	—
`sec-edgar`	`use_account_info`	`user_name`, `contact_email`

Errors

All inherit from IntegrationError (itself a VectorshiftError).

exception

A lookup returned no result.

exception

A type / route name is not in the catalogue. Carries .value.

exception

A form connect is missing required fields. Carries .type and .missing_fields. Raised client-side before any network call.

exception

The provider denied access or the backend errored. Carries .reason.

exception

The connect-session TTL elapsed before completion.

exception

wait() exceeded its timeout. Not a failure — the attempt is still live; re-open .connect_url or re-poll. Carries .connect_url, .last_status, .timeout. Also a TimeoutError.

from vectorshift import Integration, ConnectionTimeout, ConnectionFailed, MissingCredentials

try:
    integ = Integration.connect("slack").wait(timeout=120)
except ConnectionTimeout as e:
    print(f"still pending — resume at {e.connect_url}")
except ConnectionFailed as e:
    print(f"denied: {e.reason}")
except MissingCredentials as e:
    print(f"{e.type} needs {e.missing_fields}")

See Errors for the full SDK exception hierarchy.

What’s next

CLI reference

The vectorshift command line.

Integration tools

Per-service agent tool actions.

Integration nodes

Per-service pipeline node actions.

​Connecting

​connect

​reauth

​Managing

​fetch

​list

​get_status

​sync / resync

​refresh

​delete

​to_dict

​Sessions & catalogue

​from_session

​revoke_session

​types

​required_fields

​Integration

​ConnectionRequest

​wait

​get_status

​get_result

​Enums

​IntegrationType

​AuthMode

​ConnectionStatus

​IntegrationStatus

​Type catalogue

​Credential fields

​Errors

​What’s next

CLI reference

Integration tools

Integration nodes

Connecting

`connect`

`reauth`

Managing

`fetch`

`list`

`get_status`

`sync` / `resync`

`refresh`

`delete`

`to_dict`

Sessions & catalogue

`from_session`

`revoke_session`

`types`

`required_fields`

`Integration`

`ConnectionRequest`

`wait`

`get_status`

`get_result`

Enums

`IntegrationType`

`AuthMode`

`ConnectionStatus`

`IntegrationStatus`

Type catalogue

Credential fields

Errors

What’s next