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

# VectorShift plugin

> AI pipelines and agents with VectorShift - run pipelines singly or in bulk, create them from a graph, create and query knowledge bases, run chatbots, and execute Python transformations in VectorShift's sandbox.

Use **VectorShift** through Corsair: one client, typed API calls.

Create a key in VectorShift: click the logo, then Profile, then the API Keys tab. Calls go to `https://api.vectorshift.ai/v1` with the key as a Bearer token.

* **The API is published as a beta.** The docs say so explicitly and warn that error codes and response formats may change. Nothing here depends on that changing, but treat any surprise in the response bodies as possible rather than impossible.
* **A 200 can still mean failure.** Every response carries a `status`, and a run that failed arrives with HTTP 200 and `status: 'failed'`. The plugin raises a `VectorshiftRunFailedError` carrying the `error` text for `failed` only. Any other value, `success` or a status the beta API adds later such as `queued`, is returned as is, so check `status` before reading outputs. A failed run is never retried, since a pipeline may already have had side effects.
* **`GET /v1` is not the API root.** `https://api.vectorshift.ai/v1` is a 404 and `https://api.vectorshift.ai/` answers `{"Ping":"Pong"}`. The routes live under `/v1`, so the base carries it.
* **Errors are `{ error: "..." }`.** A missing key sends its own messages — `Missing authorization header`, `Invalid authorization header format`, `Invalid API key` — rather than a code, and a bad key adds a parser detail after the prefix, so the plugin matches on the start of the message.
* **One knowledge base lives on the singular route.** It is fetched with `GET /knowledge-base?id=…` and queried with `POST /knowledge-base/{id}/query`, as VectorShift's reference and Python SDK do. The plural `GET /knowledge-bases` is the list, which the plugin does not wrap.
* **A knowledge base is looked up by id or by name, never both.** `username` and `org_name` narrow a name lookup and are rejected with an id.
* **Creating a chatbot needs the node names.** `input` and `output` are required, not optional — a wrong node name produces a chatbot that answers nothing, so the schema keeps them required instead of defaulting them.
* **A chatbot takes text or audio, never both**, and a reply carries a `conversation_id` to continue the thread. `stream: true` is not offered: the plugin reads JSON, and the streamed variant is server-sent events.
* **A pipeline can be run once or many times.** `pipelines.bulkRun` takes one entry per run and executes them in parallel, each with its own `run_id` and outputs.
* **A pipeline `config` is passed through unchanged.** Its shape belongs to the visual builder; the API only requires that it is present, so the plugin does not try to model it.
* **Outputs are typed but open.** A pipeline output is a string, number, boolean, list, map or file; a file arrives as base64 `raw_bytes` with `metadata`. All of them pass through as-is.

**What you get:**

* 11 typed API operations

## Setup

**1. Install**

```bash npm theme={null}
npm install corsair @corsair-dev/vectorshift better-sqlite3
npm install --save-dev @types/better-sqlite3
```

```bash yarn theme={null}
yarn add corsair @corsair-dev/vectorshift better-sqlite3
yarn add --dev @types/better-sqlite3
```

```bash pnpm theme={null}
pnpm install corsair @corsair-dev/vectorshift better-sqlite3
pnpm install --save-dev @types/better-sqlite3
```

```bash bun theme={null}
bun add corsair @corsair-dev/vectorshift better-sqlite3
bun add --dev @types/better-sqlite3
```

**2. Add the plugin**

```ts corsair.ts theme={null}
import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { vectorshift } from '@corsair-dev/vectorshift';

export const corsair = createCorsair({
	plugins: [
		vectorshift(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});
```

With `multiTenancy: true`, scope calls with `corsair.withTenant(id)`. See [Quick start](https://docs.corsair.dev/quick-start.md) for KEK + Hub keys, and [Multi-tenancy](https://docs.corsair.dev/concepts/multi-tenancy.md) for account isolation.

**3. Choose authentication**

> [tab] API Key (Recommended)
>
> No setup required yet. When you make your first request as a tenant, Corsair prompts for the API key.
>
> ```ts theme={null}
> vectorshift()
> ```
>
> More: [API Key](https://docs.corsair.dev/concepts/api-key)

**4. Connect a tenant**

Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see [Connect / OAuth](https://docs.corsair.dev/management/connect).

```ts theme={null}
const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'vectorshift',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl
```

## Example API calls

**List pipelines**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.vectorshift.api.pipelines.list({ verbose: true });
```

**Run a pipeline with a question**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.vectorshift.api.pipelines.run({
	id: 'pl_7f3a2b',
	inputs: { question: 'Where is my refund?' },
});
```

See the full list on the [API](https://docs.corsair.dev/plugins/vectorshift/api.md) page.

## What's next

> [card] [API reference](https://docs.corsair.dev/plugins/vectorshift/api.md)
>
> Every `vectorshift.api.*` operation with input and output types.

> [card] [Connect / OAuth](https://docs.corsair.dev/management/connect)
>
> createLink, Hub delivery, and tenant connect flows.

> [card] [Use with agents](https://docs.corsair.dev/mcp-adapters/mcp-adapters)
>
> Expose this plugin's operations as MCP tools.


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