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

# Tave plugin

> Studio management with Tave, the VSCO Workspace API - manage jobs and their stages, the product price list, payments against a job, tasks and notes, and read the job types, lead sources and brands they reference.

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

Tave is VSCO Workspace. Create a key at workspace.vsco.co/settings/api and send it as `X-API-KEY`. A key is scoped to one studio.

Things to know before you call:

* **Amounts are integers, not decimals.** Every money field (`price`, `amount`, balances and totals) is a whole number in the studio currency, so 25000 for a 250.00 price. The schemas reject a decimal, which the API would otherwise round or refuse.
* **A job is a lead or a job.** `jobs.list` returns both, separated by `stage` (lead, booked, fulfillment, completed). Pass `includeClosed: true` to see closed ones, which are hidden by default.
* **Paging is on the query.** List routes other than `products.list` (which has no paging and returns the whole price list) take `page` and `pageSize` and answer `{ type, items, meta }`, where `meta` holds `currentPage`, `totalPages` and `totalItems`. `pageSize` runs from 10 to 100 and defaults to 100.
* **A wrong path answers 200 with a web page.** A route that does not exist returns the documentation HTML instead of a JSON 404, so the plugin checks the content type and reports `isHtmlResponse` on `TaveAPIError` rather than handing back a page. This is the first thing to check when a call looks like it succeeded but has no data.
* **Update needs at least one field.** `jobs.update`, `products.update`, `payments.update` and `tasks.update` reject a body that changes nothing before sending it.
* **Tasks need a list.** `tasks.create` requires `name` and `taskListId`. Get the list ID from `taskLists.list`.
* **Notes are HTML.** `notes.create` takes `contentHtml`, not plain text.
* **Payment status is an enum.** `payments.create` accepts future, confirmed-future, posted, failed or pending, and the API defaults it to posted.
* **Deletes cannot be undone.** A job delete removes its orders, invoices and notes with it, and a payment delete changes the job balance.
* **The 5xx replay rule.** The plugin retries a 5xx only on a GET. A repeated POST makes a second job, payment or note, and a repeated PUT can overwrite a newer edit.

**What you get:**

* 29 typed API operations

## Setup

**1. Install**

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

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

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

```bash bun theme={null}
bun add corsair @corsair-dev/tave 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 { tave } from '@corsair-dev/tave';

export const corsair = createCorsair({
	plugins: [
		tave(),
	],
	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)
>
> Store the Tave API key before the first call: `pnpm corsair setup --plugin=tave --tenant=acme api_key=<your-key>` (leave out `--tenant` without `multiTenancy`), or pass it as `key` in the plugin options. With Hub, each tenant enters their own key on the connect page. See [API key auth](https://docs.corsair.dev/concepts/api-key).
>
> ```ts theme={null}
> tave()
> ```
>
> 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: 'tave',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl
```

## Example API calls

**List the first page of jobs**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.tave.api.jobs.list({ page: 1 });
```

**Record a deposit against a job**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.tave.api.payments.create({ jobId: '01h35ccwymj5ctckp8px1azhg6', amount: 75000, memo: 'Deposit' });
```

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

## What's next

> [card] [API reference](https://docs.corsair.dev/plugins/tave/api.md)
>
> Every `tave.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.