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.listreturns both, separated bystage(lead, booked, fulfillment, completed). PassincludeClosed: trueto 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) takepageandpageSizeand answer{ type, items, meta }, wheremetaholdscurrentPage,totalPagesandtotalItems.pageSizeruns 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
isHtmlResponseonTaveAPIErrorrather 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.updateandtasks.updatereject a body that changes nothing before sending it. - Tasks need a list.
tasks.createrequiresnameandtaskListId. Get the list ID fromtaskLists.list. - Notes are HTML.
notes.createtakescontentHtml, not plain text. - Payment status is an enum.
payments.createaccepts 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.
- 29 typed API operations
Setup
1
Install
2
Add the plugin
corsair.ts
multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.3
Choose authentication
- API Key (Recommended)
Store the Tave API key before the first call: More: API Key
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.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.
Example API calls
List the first page of jobsWhat’s next
API reference
Every
tave.api.* operation with input and output types.Connect / OAuth
createLink, Hub delivery, and tenant connect flows.
Use with agents
Expose this plugin’s operations as MCP tools.