VectorShift plugin

• 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.

• 11 typed API operations

​

Setup

npm install corsair @corsair-dev/vectorshift better-sqlite3
npm install --save-dev @types/better-sqlite3

yarn add corsair @corsair-dev/vectorshift better-sqlite3
yarn add --dev @types/better-sqlite3

pnpm install corsair @corsair-dev/vectorshift better-sqlite3
pnpm install --save-dev @types/better-sqlite3

bun add corsair @corsair-dev/vectorshift better-sqlite3
bun add --dev @types/better-sqlite3

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!,
	},
});

vectorshift()

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

​

Example API calls

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

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

​

What’s next