# API reference

> Every route of the Vibiz Stack HTTP API, generated from the routes the API registers.

Base URL: `https://app.vibiz.app/v1`. Authenticate with `Authorization: Bearer <key>`. Request and response bodies are JSON unless a route says otherwise; every response has an `X-Request-Id`.

```bash
curl https://app.vibiz.app/v1/projects -H "Authorization: Bearer $VIBIZ_API_KEY"
```

- **Keys**: an account key (`vz_sk_…`, agent or owner access), the app key (`vz_app_…`) on `/v1/app/*` and `/v1/ai/*`, or a project AI key (`vz_ai_…`) on `/v1/ai/*`. See [Keys and environments](https://app.vibiz.app/docs/keys).
- **Environments**: project routes for payments, company, sign-in and the database take `?env=production|development`; the default is production for owner keys and development for agent keys.
- **Idempotency**: any `POST` takes `Idempotency-Key` (24 hours).
- **Errors**: `{ "error": { "code", "message", "details"? } }`. See [Errors](https://app.vibiz.app/docs/errors).
- **Lists**: `{ "object": "list", "data": [...] }`; payments lists add `has_more` and `next_cursor`.
- **Async work**: creating a project, adding a resource and deploying answer `202` with the queued operations; poll the object.

Auth below: *account key* is any account key; *owner key* refuses agent keys with `403 owner_only`; *owner on production* means an agent key may do it in development only.

## Projects

| Route | Auth | Does |
| --- | --- | --- |
| `POST /v1/projects` | account key | Create a project `{ name, slug?, resources? }`. Default resources: hosting, database, auth, analytics. → `202 { project, operations }`. |
| `GET /v1/projects` | account key | List projects. |
| `GET /v1/projects/:id` | account key | One project with its resources and `url`. |
| `GET /v1/projects/:id/icon` | account key | The live site's favicon as a data URI (`icon`, null without one), fetched by Vibiz. |
| `DELETE /v1/projects/:id` | account key | Site offline now; data destroyed after 7 days. `409 payments_held` while it holds live money. → `202` with `delete_after`. |
| `POST /v1/projects/:id/restore` | account key | Undo a delete within the 7 days; what was live is rebuilt. → `202`. |
| `POST /v1/projects/:id/resources` | account key | Add a resource `{ type }` (`hosting`, `database`, `auth`, `email`, `analytics`, `replay`, `ai`); dependencies are added. → `202`. |
| `PATCH /v1/projects/:id/resources/:type` | account key | Change a resource's settings `{ config }` (only `replay` has settings). |
| `GET /v1/projects/:id/env` | owner key | The production env values. `?names=1` lists only the names, for any key. |
| `GET /v1/projects/:id/domains` | account key | The free `address` and the owner's own domains: `data[]` with `status` (`pending_dns`, `verifying`, `active`, `error`, `external`), `https` and the `records_to_set` (`type`, `name`, `value`); `domains` lists the names. |
| `POST /v1/projects/:id/domains` | account key | Connect a domain `{ domain, hosting? }` (`vibiz`: served here with HTTPS, the default with hosting; `elsewhere`: only trusted). At most 10; `409 domain_taken` if another project has it. → `201` with `domain`. |
| `POST /v1/projects/:id/domains/:domain/verify` | account key | Check DNS and ownership again now. → the domain. |
| `DELETE /v1/projects/:id/domains/:domain` | owner key | Disconnect a domain (and its `www` redirect). |
| `POST /v1/projects/:id/domains/buy` | owner key | Buy a domain from credits for this project `{ domain, years?, expected_price_cents, confirm_premium?, contact?, save_contact?, additional? }`: registered to the saved owner details, served here at once. → `202` the owned domain. `402` short of credits, `409 price_changed` with a new quote; agents get `owner_only` with the console link. |
| `GET /v1/domains/search` | account key | Domains for a name `?q=` across endings, with `price_cents` and `renewal_price_cents` (USD) and a `buy_url`. |
| `GET /v1/domains/quote` | account key | One domain `?domain=&years=&project_id=`: the price, the balance after, the owner details it still needs (`fields_needed`) and `buy_url` for the owner. |
| `GET /v1/domains` | account key | Domains the account bought: `status`, `expires_at`, `auto_renew`, `renewal_price_cents`, `registered_to`, `contact_verification` (`status`, `verify_by`, `can_confirm`), `last_order`. |
| `GET /v1/domains/:domain` | account key | One bought domain. |
| `PATCH /v1/domains/:domain` | owner key | Turn auto-renew (from credits, ~30 days before expiry) on or off `{ auto_renew }`. |
| `POST /v1/domains/:domain/renew` | owner key | Renew now from credits `{ years?, expected_price_cents }` → `202`. |
| `POST /v1/domains/:domain/contact-verification/confirm` | owner key | Confirm the owner's contact details for a new domain (ICANN asks within 15 days) when `contact_verification.can_confirm`. → the owned domain. |
| `POST /v1/domains/:domain/contact-verification/check` | account key | Check now whether the owner's contact details are confirmed. → the owned domain. |
| `POST /v1/domains/:domain/auth-code` | owner key | The transfer code another registrar asks for. |
| `GET /v1/domains/owner` | owner key | The domain owner details (the registrant every new domain is registered to). |
| `PUT /v1/domains/owner` | owner key | Save the domain owner details `{ contact }`; they apply to domains bought from then on. |

## Development environment

| Route | Auth | Does |
| --- | --- | --- |
| `GET /v1/projects/:id/dev` | account key | `{ status: none\|provisioning\|ready\|failed, resources }`. |
| `POST /v1/projects/:id/dev` | account key | Create the development copies (idempotent). → `202`. |
| `GET /v1/projects/:id/dev/env` | account key | The development env values; `409` until ready. |
| `DELETE /v1/projects/:id/dev` | account key | Throw the development copies away. → `202`. |

## Keys and hosts

| Route | Auth | Does |
| --- | --- | --- |
| `POST /v1/cli/login` | public | Start a browser login (`vibiz login`): `{ hostname?, os?, cli_version? }` → `201 { device_code, user_code, verification_uri, verification_uri_complete, expires_in, interval }`. The person opens the link and clicks Authorize. 10 per address per 10 minutes. |
| `POST /v1/cli/login/token` | public | Poll a browser login `{ device_code }` every `interval` seconds: `400 { error }` with `authorization_pending`, `slow_down`, `expired_token`, `access_denied` or `invalid_grant`; once approved, `200 { api_key, key, account, api_url }`, exactly once. The key is a new agent key named `cli · <hostname>`. |
| `GET /v1/whoami` | account key | The account and key this request acts as: `{ account, key: { id, name, prefix, kind, access }, role }`. |
| `POST /v1/cli/logout` | account key | The calling key revokes itself (`vibiz logout` for a key a browser login made). |
| `GET /v1/api-keys` | account key | Named keys, no secrets, with `access`. |
| `POST /v1/api-keys` | owner key | Create a key `{ name, access?: agent\|owner }` (default agent). The secret is returned once. → `201`. |
| `DELETE /v1/api-keys/:id` | owner key | Revoke a key (a key can't revoke itself). |
| `GET /v1/projects/:id/app-keys` | account key | App key prefixes and last use, per environment, each with the `console_url` that opens it ready to copy. |
| `GET /v1/projects/:id/app-keys/:environment` | owner on production · any key on development | The app key itself, to paste into a host Vibiz can't connect to. An agent key gets `owner_only` with the `console_url` to hand over. |
| `POST /v1/projects/:id/app-keys/rotate` | owner on production · any key on development | Rotate an app key `{ environment, grace_seconds }`; the new key is pushed everywhere, never shown. |
| `GET /v1/hosts` | account key | The hosts Vibiz can connect to and what each asks for. |
| `GET /v1/projects/:id/hosts` | account key | Connected hosts: status and the variable names written. |
| `POST /v1/projects/:id/hosts` | owner key | Connect a host `{ kind, token, project?, team_id?, environments? }`; the token is checked first. → `201`. |
| `POST /v1/projects/:id/hosts/sync` | account key | Push the env to every connected host now. → `202`. |
| `DELETE /v1/projects/:id/hosts/:target` | owner key | Disconnect; `?keep_values=1` leaves the values in place. |

## Hosting

| Route | Auth | Does |
| --- | --- | --- |
| `POST /v1/files/missing` | account key | Which of `{ shas }` (SHA-1, up to 10,000) still need uploading. |
| `PUT /v1/files/:sha` | account key | Upload one file (raw bytes, up to 50 MB); must match its SHA-1. → `204`. |
| `POST /v1/projects/:id/deployments` | account key | Build `{ files: [{ path, sha, size }], target? }` (`production` by default, or `preview`). → `202 { deployment, operation }`. |
| `GET /v1/projects/:id/deployments` | account key | The latest 50 deployments. |
| `GET /v1/deployments/:id` | account key | `status`: `queued → building → ready` or `failed`. |
| `POST /v1/deployments/:id/promote` | account key | Make it live: a production deployment switches instantly (`200`, how rollback works); a preview is rebuilt as production (`202`). |

## Database and users

| Route | Auth | Does |
| --- | --- | --- |
| `GET /v1/projects/:id/database` | owner on production · any key on development | The app database's schemas and tables. `?env=`. |
| `GET /v1/projects/:id/database/tables/:schema/:table` | owner on production · any key on development | One table's rows, read-only. `limit` (≤ 200), `offset`. |
| `POST /v1/projects/:id/database/query` | owner on production · any key on development | One read-only statement `{ sql, env? }` (SELECT, WITH, TABLE, VALUES, EXPLAIN, SHOW). |
| `GET /v1/projects/:id/users` | owner on production · any key on development | The app's signed-up users. `limit` (≤ 100), `offset`, `search`. |
| `POST /v1/projects/:id/users/:user/sign-out` | owner key | End one user's sessions. |

## Sign-in

| Route | Auth | Does |
| --- | --- | --- |
| `GET /v1/projects/:id/auth/settings` | owner on production · any key on development | Sign-in settings for `?env=`: email and password, magic link, providers with callback URLs, localhost, allowed domains, sender. |
| `PATCH /v1/projects/:id/auth/settings` | owner on production · any key on development | Change sign-in settings (partial). |
| `PUT /v1/projects/:id/auth/providers/:provider` | owner on production · any key on development | `google`, `github`, `vercel`: `{ credentials: "shared" }` (Google only) or `{ credentials: "own", client_id, client_secret }`. |
| `DELETE /v1/projects/:id/auth/providers/:provider` | owner on production · any key on development | Turn a provider off. |
| `POST /v1/projects/:id/auth/test-email` | owner key | A test message `{ to }` through the SMTP sender that is set. |

## Email

| Route | Auth | Does |
| --- | --- | --- |
| `GET /v1/projects/:id/email` | account key | The project's mail domain, status, today's sends and recent activity. |
| `GET /v1/forwarding` | account key | Email forwarding on every domain of the account: `data[]` as `GET /v1/domains/:domain/forwarding`. |
| `GET /v1/domains/:domain/forwarding` | account key | Email forwarding for a domain: `status` (`off`, `needs_dns`, `verifying`, `active`, `failed`), `managed_dns`, the `records` it needs, `mx` (whose mail servers it points at, with a warning when they are another provider's), `rules[]` (`address`, `to[]` with each inbox's `status`: `pending` until it confirms, `confirmed`, `disabled`), `forwarded_today`, `daily_cap`, `next_step`. |
| `PUT /v1/domains/:domain/forwarding` | owner key | Set every rule `{ rules: [{ address: "hello" \| "*", to: ["me@example.com"] }], replace_mx? }` (up to 5 inboxes each; `*` is any other address). Domains bought through Vibiz get their records set; `replace_mx: true` confirms taking the domain's mail from the provider it uses today. New inboxes get a confirmation email. Agents get `owner_only` with a `console_url` that has their proposal filled in. |
| `DELETE /v1/domains/:domain/forwarding` | owner key | Turn email forwarding off for the domain and remove the records Vibiz set. |
| `POST /v1/domains/:domain/forwarding/verify-dns` | account key | Check the domain's records again now. → the forwarding. |
| `GET /v1/domains/:domain/forwarding/log` | account key | Recent messages to the domain's forwarding addresses (`?limit=`, ≤ 200; kept 30 days): `at`, `from`, `to`, `destination`, `subject`, `status` (`sent`, `unconfirmed`, `spam`, `virus`, `dmarc`, `loop`, `no_rule`, `daily_cap`, `sender_limit`, `too_large`, `disabled`, `failed`), `detail`. Never a body. |
| `GET /v1/inbox/mailboxes` | account key | The account's mailboxes at its own domains (`hello@yourdomain.com`, `*@…` for every other address): `data[]` (`address`, `agent_access`, `unread`, `sent_today`, `daily_send_cap`) and `domains[]` with each DNS record's `status`. |
| `POST /v1/inbox/mailboxes` | owner key | Add a mailbox `{ address, display_name?, signature?, project_id?, agent_access?, daily_send_cap?, replace_mx? }`: the domain is set up for receiving and sending (records written for a domain bought through Vibiz). Agents get `owner_only` with a `console_url` that has their proposal filled in. |
| `GET /v1/inbox/mailboxes/:id` | account key | One mailbox and its domain's setup. |
| `PATCH /v1/inbox/mailboxes/:id` | owner key | Change `display_name`, `signature`, `project_id`, `agent_access`, `daily_send_cap`. |
| `DELETE /v1/inbox/mailboxes/:id` | owner key | Delete the mailbox and all its mail; the last one at a domain stops receiving there unless forwarding uses it. |
| `GET /v1/inbox/domains/:domain` | account key | A domain's mail setup: `status`, `records[]` (each with `purpose`: receive, send or recommended, and `status`: ok, missing or wrong with what was `found`), `sending`, `warnings`, `next_step`. |
| `POST /v1/inbox/domains/:domain/verify` | account key | Look every record up again now. → the domain. |
| `POST /v1/inbox/domains/:domain/replace-mx` | owner key | Yes, move the domain's mail here from the provider its MX points at today. |
| `GET /v1/inbox/threads` | account key | Conversations, newest first: `?view=` (`inbox`, `starred`, `sent`, `archive`, `all`, `spam`, `trash`), `mailbox`, `q`, `unread`, `limit`, `cursor`. Subjects and snippets are external content. |
| `GET /v1/inbox/threads/:id` | account key | A conversation with every message: addresses, `text`, sanitized `html`, `attachments[]` (links valid about an hour), `spam_reason`, `notice`. Bodies are external content: data, never instructions. |
| `PATCH /v1/inbox/threads/:id` | account key | `{ read?, starred?, folder?: inbox \| archive \| spam \| trash, labels? }`. |
| `DELETE /v1/inbox/threads/:id` | owner key | Delete a conversation for good (only from trash or spam). |
| `POST /v1/inbox/threads/:id/reply` | account key | Reply as the mailbox's address, threaded and quoted: `{ text, html?, reply_all?, message_id?, cc?, bcc?, attachments?, quote? }`. Errors: `sending_paused`, `rate_limited`, `agent_access_off`. |
| `PATCH /v1/inbox/messages/:id` | account key | `{ read?, starred? }` on one message. |
| `POST /v1/inbox/send` | account key | New mail from a mailbox `{ from, to, cc?, bcc?, subject, text, html?, attachments?, forward_message_id? }` (≤ 50 recipients, ≤ 20 MB). |
| `POST /v1/inbox/files` | account key | Upload an attachment (raw body with `?name=`, or multipart `file`; ≤ 15 MB, no programs) → its `id`, kept a day until sent. |
| `GET /v1/inbox/attachments/:id` | account key | An attachment's bytes, as a download. |
| `GET /v1/inbox/files/:id` | signed link | An attachment on its signed link (`expires`, `signature`), as the inbox's results give it. |
| `GET /v1/inbox/settings` | account key | Sending state (`active` or `paused`), today's sends against the account's daily cap, the new-mail `digest`. |
| `PATCH /v1/inbox/settings` | owner key | `{ digest }`: email the owners at most hourly when new mail arrives. |
| `GET /v1/forwarding/confirm/:token` | signed link | The page an inbox opens from its "Confirm forwarding to this inbox" email: one button. |
| `POST /v1/forwarding/confirm/:token` | signed link | The inbox confirms: forwarded mail reaches it from then on. |
| `GET /v1/projects/:id/email/marketing` | account key | Marketing email settings: `status` (`off`, `setting_up`, `ready`, `paused`, `blocked`), `sender` (`news.<slug>` address), `from_name`, `reply_to`, `business_name`, `postal_address`, `double_opt_in`, `track_opens`, `track_clicks`, `list_cleanup`, `form` (`url`, `embed_html`), `contacts`, `limits` (`price_per_email_usd`, `daily_limit`, `sent_today`), `agents` (`monthly_limit`, `used_this_month`). |
| `PATCH /v1/projects/:id/email/marketing` | account key | Change settings. `postal_address`, `agent_monthly_limit` and turning `double_opt_in` off are the owner's. |
| `POST /v1/projects/:id/email/marketing/setup` | account key | Set up sending (adds the email resource if needed): `202`, `status: setting_up` until the address verifies, then `ready`. |
| `GET /v1/projects/:id/email/lists` | account key | Lists with their `subscribed` counts. |
| `POST /v1/projects/:id/email/lists` | account key | `{ name, description?, public? }` → the list. `public` lists show on the preference page. |
| `PATCH /v1/projects/:id/email/lists/:list` | account key | Rename or describe a list (id or name). |
| `DELETE /v1/projects/:id/email/lists/:list` | account key | Delete a list (its contacts stay). |
| `GET /v1/projects/:id/email/contacts/export` | account key | Contacts as CSV (`?status=`, `?list=`), with consent and properties. |
| `GET /v1/projects/:id/email/contacts/imports` | account key | Past imports with their reports. |
| `POST /v1/projects/:id/email/contacts/import` | account key | Import a CSV `{ csv, dry_run?, consent, lists?, fix_typos?, include_role?, update_existing? }` → a report: `new_contacts`, `updated_contacts`, `skipped` by reason, `samples`, `typo_suggestions`. `consent: true` is required to import. |
| `GET /v1/projects/:id/email/contacts` | account key | Contacts, newest first: `?q=`, `?status=`, `?list=`, `?segment=`, `?cursor=`, `?limit=` (≤ 200); `total`. |
| `POST /v1/projects/:id/email/contacts` | account key | Add or update one by email `{ email, first_name?, last_name?, properties?, lists?, subscribed?, double_opt_in?, consent? }`. Never re-subscribes someone who left: they get a confirmation email (`pending`). |
| `GET /v1/projects/:id/email/contacts/:contact` | account key | One contact (id or email) with its lists and last 20 events. |
| `PATCH /v1/projects/:id/email/contacts/:contact` | account key | `{ first_name?, last_name?, properties?, status?: subscribed \| unsubscribed, add_lists?, remove_lists? }`. Subscribing again by hand is the owner's. |
| `DELETE /v1/projects/:id/email/contacts/:contact` | account key | Forget a contact. An address that unsubscribed, bounced or complained stays suppressed. |
| `POST /v1/projects/:id/email/events` | account key | `{ email, event, properties? }`: something a contact did. Starts event automations and ends runs whose exit event it is. |
| `GET /v1/projects/:id/email/segments` | account key | Saved segments with their `contacts` counts. |
| `POST /v1/projects/:id/email/segments/preview` | account key | `{ filter }` → `contacts` and a sample, without saving. |
| `POST /v1/projects/:id/email/segments` | account key | `{ name, filter: { match: all \| any, conditions[] } }`: properties, fields, lists, events, engagement. |
| `PATCH /v1/projects/:id/email/segments/:segment` | account key | Rename it or change its filter. |
| `DELETE /v1/projects/:id/email/segments/:segment` | account key | Delete a segment. |
| `POST /v1/projects/:id/email/render` | account key | Render a draft `{ subject, preview_text?, format, body, contact_id? }` as a contact gets it: `html`, `text`, `size_bytes`, `merge_tags`. |
| `GET /v1/projects/:id/email/broadcasts` | account key | Broadcasts, newest first (`?status=`), with their stats. |
| `POST /v1/projects/:id/email/broadcasts` | account key | A draft `{ name?, subject, preview_text?, from_local?, from_name?, reply_to?, format: markdown \| html, body, audience: { list_id?, segment_id? } }`. |
| `GET /v1/projects/:id/email/broadcasts/:broadcast` | account key | One broadcast: `status`, `waiting`, `recipients`, `charged_cents`, `stats` (sent, delivered, opened, clicked, bounced, complained, unsubscribed, rates, `by_mailbox`). |
| `PATCH /v1/projects/:id/email/broadcasts/:broadcast` | account key | Edit a draft, a scheduled or a waiting-for-approval broadcast. |
| `DELETE /v1/projects/:id/email/broadcasts/:broadcast` | account key | Delete a draft or canceled broadcast. |
| `GET /v1/projects/:id/email/broadcasts/:broadcast/review` | account key | The checklist before sending: `ready`, `checks[]` (`ok`, `warning`, `error`), `audience`, `cost` (`total_cents`, `balance_cents`, `enough_credits`), `sending`, `preview`, `console_url`. |
| `POST /v1/projects/:id/email/broadcasts/:broadcast/test` | account key | Send a free `[Test]` copy `{ to? }` (agents: to the owners only; 20 a day). |
| `POST /v1/projects/:id/email/broadcasts/:broadcast/send` | account key | Send now or `{ scheduled_at }`. An agent sends only within the owner's monthly allowance; otherwise `403 owner_only` with the review link. |
| `POST /v1/projects/:id/email/broadcasts/:broadcast/cancel` | account key | Stop it; nothing more goes out and the held credits are released. |
| `POST /v1/projects/:id/email/broadcasts/:broadcast/resume` | owner key | Go on after a pause. |
| `GET /v1/projects/:id/email/broadcasts/:broadcast/recipients` | account key | Who got it: `?status=` (`sent`, `delivered`, `opened`, `clicked`, `bounced`, `complained`, `unsubscribed`, `failed`), `?mailbox=`, `?cursor=`. |
| `GET /v1/projects/:id/email/automations` | account key | Automations with their run counts. |
| `POST /v1/projects/:id/email/automations` | account key | `{ name, trigger, steps[], exit_event? }`: triggers `contact_added`, `event`, `date`; steps `wait`, `email`, `condition` (`yes[]`, `no[]`), `exit`. |
| `GET /v1/projects/:id/email/automations/:automation` | account key | One automation with `enrollments` counts and emails sent, opened, clicked. |
| `PATCH /v1/projects/:id/email/automations/:automation` | account key | Edit. While active only email wording changes; pause it to change the trigger, waits or branches. |
| `DELETE /v1/projects/:id/email/automations/:automation` | account key | Delete it (archived if it sent email). |
| `POST /v1/projects/:id/email/automations/:automation/activate` | account key | Turn it on. An agent needs the owner's monthly allowance; otherwise `403 owner_only` with the console link. |
| `POST /v1/projects/:id/email/automations/:automation/pause` | account key | Pause it; runs wait where they are. |
| `GET /v1/projects/:id/email/automations/:automation/enrollments` | account key | Runs: `?status=` (`active`, `completed`, `exited`, `failed`), each with its `step_id`, `next_run_at`, `history`. |
| `POST /v1/projects/:id/email/automations/:automation/test` | account key | Send one email step as a free test `{ step_id, to? }`. |
| `GET /v1/email/u/:token` | signed link | The unsubscribe page a contact opens from an email (`?view=preferences`: lists to keep). GET changes nothing. |
| `POST /v1/email/u/:token` | signed link | One-click unsubscribe (`List-Unsubscribe=One-Click`, RFC 8058), or the page's form: unsubscribe, subscribe again, save lists, never from anyone. |
| `GET /v1/email/confirm/:token` | signed link | The double opt-in page: one button. |
| `POST /v1/email/confirm/:token` | signed link | The contact confirms: `subscribed`. |
| `GET /v1/email/k/:token` | signed link | "Keep sending" page from the list-cleanup email. |
| `POST /v1/email/k/:token` | signed link | The contact keeps getting emails. |
| `GET /v1/email/o/:token` | signed link | Open tracking pixel. |
| `GET /v1/email/c/:token` | signed link | Click tracking: redirects to the signed destination. |
| `GET /v1/email/f/:form` | public | The hosted signup form. |
| `POST /v1/email/f/:form` | public | A signup from the form, a pasted snippet or JSON from any site `{ email, first_name? }`: honeypot, rate limits, double opt-in. |
| `OPTIONS /v1/email/f/:form` | public | CORS preflight for the signup API. |

## AI

| Route | Auth | Does |
| --- | --- | --- |
| `POST /v1/ai/chat/completions` | account, project AI or app key | OpenAI chat completions, streaming (SSE) or not. `model` defaults to `vibiz/fast`. |
| `POST /v1/ai/embeddings` | account, project AI or app key | Embeddings. |
| `POST /v1/ai/images/generations` | account, project AI or app key | Images: `b64_json` (default) or `url` (24 h). |
| `POST /v1/ai/audio/speech` | account, project AI or app key | Text to speech; streams `mp3` or `pcm`. |
| `POST /v1/ai/audio/transcriptions` | account, project AI or app key | Speech to text, multipart `file` (≤ 25 MB). |
| `POST /v1/ai/jobs` | account, project AI or app key | Async image or video `{ type, model?, input }`. → `202`. |
| `GET /v1/ai/jobs/:id` | account, project AI or app key | A job and, once done, its output. |
| `POST /v1/ai/jobs/:id/cancel` | account, project AI or app key | Cancel a job. |
| `GET /v1/ai/models` | public | The Vibiz models, each with the lab model it runs, and the lab models, with prices. `?all=1` every model, `?q=` search. |
| `GET /v1/ai/health` | public | Per capability `ok`/`degraded`/`down`. |
| `GET /v1/ai/media/:token` | signed link | Generated media; the token in the link is the credential (24 h). |
| `GET /v1/projects/:id/ai` | account key | A project's AI key status, budgets, limits and today's spend. |
| `PATCH /v1/projects/:id/ai` | account key | `{ daily_budget_usd?, end_user_daily_budget_usd?, log_content?, rpm?, tpm?, concurrency? }`. |
| `POST /v1/projects/:id/ai/keys/rotate` | owner key | A new project AI key `{ grace_seconds? }` (default 3600), written to the app env. |
| `POST /v1/projects/:id/ai/keys/revoke` | account key | Every AI key of the project stops now; rotate to get a new one. |
| `GET /v1/ai-keys` | account key | Your own AI provider keys, the account's: status per provider (never a secret) and calls they served in 30 days. |
| `GET /v1/ai-keys/:provider` | account key | One key: `has_key`, last 4, last used, last error, and per Vibiz model whether `your_key` or `vibiz` serves (and pays for) it. |
| `PUT /v1/ai-keys/:provider` | owner key | Set your own key (`google`): `{ type: "gemini_api_key", api_key }` or `{ type: "vertex", service_account, project_id?, region? }`, `use_for?`. Checked with a free call first. |
| `PATCH /v1/ai-keys/:provider` | owner key | `{ use_for: [capability…] }`: what the key serves; the rest runs on Vibiz. |
| `DELETE /v1/ai-keys/:provider` | owner key | Remove the key; calls go back to Vibiz (jobs promised to it fail). |
| `POST /v1/ai-keys/:provider/test` | account key | Re-check the stored key with the same free call; records the result. |
| `GET /v1/projects/:id/ai-keys` | account key | Your own AI provider keys, a project's override (else it inherits the account's): status per provider (never a secret) and calls they served in 30 days. |
| `GET /v1/projects/:id/ai-keys/:provider` | account key | One key: `has_key`, last 4, last used, last error, and per Vibiz model whether `your_key` or `vibiz` serves (and pays for) it. |
| `PUT /v1/projects/:id/ai-keys/:provider` | owner key | Set your own key (`google`): `{ type: "gemini_api_key", api_key }` or `{ type: "vertex", service_account, project_id?, region? }`, `use_for?`. Checked with a free call first. |
| `PATCH /v1/projects/:id/ai-keys/:provider` | owner key | `{ use_for: [capability…] }`: what the key serves; the rest runs on Vibiz. |
| `DELETE /v1/projects/:id/ai-keys/:provider` | owner key | Remove the key; calls go back to Vibiz (jobs promised to it fail). |
| `POST /v1/projects/:id/ai-keys/:provider/test` | account key | Re-check the stored key with the same free call; records the result. |
| `GET /v1/projects/:id/ai/calls` | account key | The project's recent AI calls: model, tokens, cost, outcome (no content). |
| `POST /v1/actions/ai.chat` | account key | `{ input: { prompt \| messages, system?, model?, max_tokens?, json? } }` → `{ output: { text, model, usage }, cost_micro_usd }`. |
| `POST /v1/projects/:id/actions/ai.chat` | account key | The same, billed to the project. |
| `POST /v1/actions/image.generate` | account key | `{ input: { prompt, size?, n?, model? } }` → image links (24 h). |
| `POST /v1/projects/:id/actions/image.generate` | account key | The same, billed to the project. |
| `POST /v1/actions/speech.create` | account key | `{ input: { text, voice?, format?, model? } }` → an audio link. |
| `POST /v1/projects/:id/actions/speech.create` | account key | The same, billed to the project. |
| `POST /v1/actions/speech.transcribe` | account key | `{ input: { audio_base64, filename?, language?, model? } }` → `{ text, language, duration_seconds }`. |
| `POST /v1/projects/:id/actions/speech.transcribe` | account key | The same, billed to the project. |

## Files

| Route | Auth | Does |
| --- | --- | --- |
| `GET /v1/projects/:id/files` | account key | The project's files, newest first (`env`, `type`, `source`, `q`, `since`, `until`, `model`, `tag`, `folder`, `limit`, `cursor`), with `total_files` and `total_bytes`. |
| `POST /v1/projects/:id/files` | account key | Upload a file (raw body with `?name=`, or multipart `file`), up to 50 MB → the file with its permanent `url`. |
| `POST /v1/projects/:id/files/import` | account key | Save what a public URL serves `{ url, name?, folder?, private? }`. |
| `GET /v1/projects/:id/files/latest` | account key | The newest file matching `type`, `source`, `model`, `tag`: what an agent just made. |
| `GET /v1/projects/:id/files/:fileId` | account key | One file: its link, type, size, dimensions and, for AI media, the model, prompt and cost. |
| `GET /v1/projects/:id/files/:fileId/content` | account key | The file's bytes, private or not. |
| `PATCH /v1/projects/:id/files/:fileId` | account key | Rename, move, tag, annotate or make private `{ name?, folder?, tags?, note?, private? }`. |
| `DELETE /v1/projects/:id/files/:fileId` | account key | Delete a file: its link stops working. |

## Export

| Route | Auth | Does |
| --- | --- | --- |
| `POST /v1/projects/:id/exports` | owner on production · any key on development | Pack the project to take it elsewhere `{ include?: [code, database, database_csv, env_guide], env?, deployment_id? }` → `202` and the export, `queued`. The code is the source of the live deployment (or `deployment_id`) with `VIBIZ-EXPORT.md` and `.env.example`; the database is plain SQL that `psql` restores, CSV optional. A production database is an owner's; one export at a time, 10 a day. |
| `GET /v1/projects/:id/exports` | account key | The last 20 exports, newest first. |
| `GET /v1/projects/:id/exports/:exportId` | account key | One export: `status` (`queued`, `running`, `ready`, `failed`, `expired`), `step`, `progress`, and `files` with signed download links until `expires_at` (a day). Agents get no link to production data. |
| `GET /v1/projects/:id/exports/:exportId/env` | owner key | The export environment's secret values as a `.env` file, with `confirm=1`. Never cached, never in the zip. |

## Actions

| Route | Auth | Does |
| --- | --- | --- |
| `POST /v1/actions/:name` | account key | Run an account action `{ input }`: web data (`web.scrape`, `web.search`, `web.crawl`, `web.screenshot`, `web.design`, `ads.library`, `places.search`, `reviews`, `social.profile`, `social.posts`, `ecommerce.product`, `linkedin.company`) → `{ output, cost_micro_usd, run_id, console_url }`. |
| `GET /v1/actions` | account key | The web data actions: name, title, one line, slow or not, a hint per field, an example and the input as JSON Schema. |
| `GET /v1/actions/runs` | account key | Past web data runs, newest first (input, status, cost, no output). `?project=<id>\|none`, `?action=`, `?since=<iso>`, `?cursor=`, `?limit=` (25, ≤ 100). With `console_url`. |
| `GET /v1/actions/runs/:id` | account key | One run with its output (cut to 1 MB: `truncated`), error and cost, with `console_url`. |
| `POST /v1/projects/:id/actions/:name` | account key | Run an action as the project (`email.send`, or any action billed to it) → `{ project_id, output, cost_micro_usd, usage }`; web data also `run_id`, `console_url`, and a screenshot is saved to the project's Files. |

## Payments

| Route | Auth | Does |
| --- | --- | --- |
| `GET /v1/projects/:id/payments` | account key | The payments account: where sales go (`account.mode`: `vibiz` or `own`), balance, payouts status, `fees` (with `hold_days` and a $100 example), webhook. |
| `PATCH /v1/projects/:id/payments` | owner on production · any key on development | `{ statement_descriptor_suffix?, webhook_url?, webhook_events? }`. |
| `POST /v1/projects/:id/payments/webhook-secret` | owner on production · any key on development | Rotate the webhook secret; shown once and written to the app env as `VIBIZ_WEBHOOK_SECRET`. |
| `GET /v1/projects/:id/payments/deliveries` | account key | The last 50 webhook deliveries and their status codes. |
| `GET /v1/projects/:id/payments/products` | account key | The catalog for `?env=`. |
| `POST /v1/projects/:id/payments/products` | account key | Create `{ name, description?, price?: { unit_amount_cents, type, interval?, interval_count?, lookup_key? } }`. |
| `GET /v1/projects/:id/payments/products/:productId` | account key | One product with its prices. |
| `PATCH /v1/projects/:id/payments/products/:productId` | account key | Rename, describe, activate or deactivate. |
| `DELETE /v1/projects/:id/payments/products/:productId` | owner on production · any key on development | Archive a product. |
| `POST /v1/projects/:id/payments/products/:productId/prices` | account key | Add a price `{ unit_amount_cents, type, interval?, interval_count?, lookup_key? }`. Prices are immutable. |
| `PATCH /v1/projects/:id/payments/prices/:priceId` | account key | `{ active?, lookup_key? }`. |
| `POST /v1/projects/:id/payments/checkout` | account key | A hosted checkout `{ price_id \| lookup_key \| amount_cents+name, user?, success_url, cancel_url, … }` → `{ url, expires_at }` (1 h, one buyer). |
| `GET /v1/projects/:id/payments/payments` | account key | Payments, newest first (`cursor`, `limit`); emails masked for agents on production. |
| `GET /v1/projects/:id/payments/payments/:paymentId` | account key | One payment. |
| `POST /v1/projects/:id/payments/payments/:paymentId/refund` | owner on production · any key on development | `{ amount_cents?, reason? }`; `409 insufficient_balance` when the balance can't cover it. |
| `GET /v1/projects/:id/payments/subscriptions` | account key | Subscriptions, `?user=&status=`, each with its price. |
| `POST /v1/projects/:id/payments/subscriptions/:subId/cancel` | owner on production · any key on development | `{ at_period_end? = true }`. |
| `GET /v1/projects/:id/payments/ledger` | account key | Every money movement, newest first. |
| `POST /v1/projects/:id/payments/payouts/session` | owner on production · any key on development | A session for the embedded identity, bank and payouts UI (Get paid). |
| `POST /v1/projects/:id/payments/withdraw` | owner on production · any key on development | `{ amount_cents? }` (default everything available) → a withdrawal; `409` when payouts are not ready or nothing is available. |
| `GET /v1/projects/:id/payments/withdrawals` | account key | Withdrawals and their status. |
| `POST /v1/projects/:id/payments/refresh` | account key | Re-read the account and recent charges now. |
| `POST /v1/projects/:id/payments/simulate` | account key | Development only: `{ event: payment \| dispute \| refund \| release_hold, … }` runs a real test-mode charge through the ledger and webhooks. |
| `POST /v1/projects/:id/payments/own-account/link` | account key | A link for the owner to connect their own Stripe account instead (`?env=`, default production) → `{ url, console_url, expires_at }`. Give `url` to the owner: only they can complete it. `503` when it isn't available. |
| `DELETE /v1/projects/:id/payments/own-account` | owner key | Disconnect the owner’s own Stripe account: new sales go through Vibiz again. |

## Company

| Route | Auth | Does |
| --- | --- | --- |
| `GET /v1/company/catalog` | account key | States with their fees per entity type (cents), endings, industries, Vibiz fees, disclaimer. |
| `GET /v1/projects/:id/company` | account key | The company, with `problems` and `quote` while a draft; `404` none yet. |
| `PUT /v1/projects/:id/company` | account key | Create or replace the draft. |
| `PATCH /v1/projects/:id/company` | account key | Change the draft (top-level keys replace). |
| `DELETE /v1/projects/:id/company` | account key | Delete a draft (or a failed or cancelled one). |
| `POST /v1/projects/:id/company/submit` | owner on production · any key on development | File it. Production: `{ confirm, accept_terms, expected_total_cents, expected_updated_at }`, paid from the credits (`402 payment_required` when they fall short); development: `{ accept_terms }`. |
| `POST /v1/projects/:id/company/checkout` | owner key | Pay a live filing by card instead: the submit body → a `billing_checkout` for exactly `quote.total_cents`; filed when the payment arrives. |
| `POST /v1/projects/:id/company/signatures/:document` | owner on production · any key on development | A fresh signing link (`ss4`, `form_8821`). |
| `POST /v1/projects/:id/company/actions/:actionId` | owner on production · any key on development | Answer an action: `{ names }` or `{ address }`. |
| `GET /v1/projects/:id/company/documents/:docId` | owner on production · any key on development | A short-lived download link. |
| `POST /v1/projects/:id/company/refresh` | account key | Re-read it from the filing partner now. |
| `POST /v1/projects/:id/company/simulate` | account key | Development only: `{ step: formation \| ein }`. |

## Social

| Route | Auth | Does |
| --- | --- | --- |
| `GET /v1/projects/:id/social` | account key | Overview: platforms with their limits, connected accounts, posts waiting, scheduled and failed, ad changes waiting. |
| `GET /v1/projects/:id/social/accounts` | account key | Connected social and ad accounts (`kind`, `platform` filters). |
| `POST /v1/projects/:id/social/connect` | account key | `{ platform, ads? }` → a link (1 h) for the owner to open: they approve it in the console, then sign in to the platform. Production unless `env=development`, which makes a test account at once and returns it. |
| `POST /v1/projects/:id/social/accounts/refresh` | account key | Read the accounts again from the platforms. |
| `DELETE /v1/projects/:id/social/accounts/:accountId` | owner on production · any key on development | Disconnect an account. |
| `GET /v1/projects/:id/social/accounts/:accountId/analytics` | account key | Followers, totals and a daily series (`from`, `to`; 30 days by default). |
| `POST /v1/projects/:id/social/media` | account key | Upload a file (raw body, its `content-type`, `?filename=`; up to 512 MB) → a URL to post with. |
| `GET /v1/projects/:id/social/posts` | account key | Posts, newest first (`status`, `account`, `platform`, `from`, `to`, `cursor`, `limit`). |
| `POST /v1/projects/:id/social/posts` | account key | Publish now, schedule (`schedule_at`) or draft. Production: owners send `confirm: true`; an agent's post waits for the owner (`pending_approval`). |
| `GET /v1/projects/:id/social/posts/:postId` | account key | One post, with each account's status, link and error. |
| `DELETE /v1/projects/:id/social/posts/:postId` | account key | Cancel a draft, a waiting or a scheduled post (a live scheduled one: owner). Published posts stay on the platforms. |
| `POST /v1/projects/:id/social/posts/:postId/publish` | account key | Publish or schedule a draft (same rules as creating one). |
| `POST /v1/projects/:id/social/posts/:postId/approve` | owner key | Approve a waiting post: it goes out now or at its time (`schedule_at` to change it). |
| `POST /v1/projects/:id/social/posts/:postId/reject` | owner key | Reject a waiting post. |
| `POST /v1/projects/:id/social/posts/:postId/retry` | owner on production · any key on development | Publish the failed accounts again (production: `confirm: true`). |
| `POST /v1/projects/:id/social/posts/:postId/refresh` | account key | Read its status again from the platforms. |
| `GET /v1/projects/:id/social/posts/:postId/analytics` | account key | Impressions, reach, likes, comments, shares, saves, clicks per account. |
| `GET /v1/projects/:id/social/ads/campaigns` | account key | Campaigns of an ad account with budget and spend (`account`, `ad_account`, `from`, `to`). |
| `POST /v1/projects/:id/social/ads/changes` | account key | Boost a post, pause, resume or re-budget a campaign. Production: owners send `confirm: true`; an agent's change waits for the owner. |
| `GET /v1/projects/:id/social/ads/changes` | account key | Ad changes, newest first (`status`). |
| `GET /v1/projects/:id/social/ads/changes/:changeId` | account key | One ad change. |
| `POST /v1/projects/:id/social/ads/changes/:changeId/approve` | owner key | Approve a waiting ad change: it is applied. |
| `POST /v1/projects/:id/social/ads/changes/:changeId/reject` | owner key | Reject a waiting ad change. |
| `GET /v1/social-connect/:token` | signed link | The connect link: the owner's connect page in the console, then the platform's sign-in. |
| `GET /v1/social-media/:ref` | public | An uploaded file, as the platforms fetch it. |

## Connectors

| Route | Auth | Does |
| --- | --- | --- |
| `GET /v1/projects/:id/connectors` | account key | The project's connectors. |
| `POST /v1/projects/:id/connectors` | account key | Add one from a manifest (full or short form). → `201`; `409` when the name is taken. |
| `POST /v1/projects/:id/connectors/import` | account key | Preview an OpenAPI 3 spec `{ url \| spec, name?, base_url?, enable? }`: a draft manifest, its operations and problems. Nothing is saved. |
| `GET /v1/projects/:id/connectors/:name` | account key | One connector: operations, which keys are set per environment, readiness. |
| `PATCH /v1/projects/:id/connectors/:name` | account key | Change it, enable or disable operations, raise risks. Base URL, auth and env once live, `app_dangerous` and lowering a risk are the owner's. |
| `DELETE /v1/projects/:id/connectors/:name` | account key | Delete it; its variables leave both envs. Owner once a production value is set. |
| `PUT /v1/projects/:id/connectors/:name/secrets` | owner on production · any key on development | Set its variables `{ values: { NAME: string \| null } }` for `?env=`. Never returned. |
| `POST /v1/projects/:id/connectors/:name/check` | account key | Run its check request: does the key work. |
| `POST /v1/projects/:id/connectors/:name/call` | account key | Call an operation `{ operation, params?, body?, approval_id? }` → the API's answer, wrapped and marked untrusted. Risky agent calls answer `403 approval_required`. |
| `GET /v1/projects/:id/connectors/:name/calls` | account key | Recent calls, newest first (no parameters or bodies). |
| `GET /v1/projects/:id/connectors/approvals` | account key | Approvals, `?status=pending`. |
| `GET /v1/projects/:id/connectors/approvals/:approvalId` | account key | One approval, with exactly what will be sent. |
| `POST /v1/projects/:id/connectors/approvals/:approvalId/approve` | owner key | Approve: the agent calls again with `approval_id` within an hour. |
| `POST /v1/projects/:id/connectors/approvals/:approvalId/deny` | owner key | Deny it. |

## Analytics

| Route | Auth | Does |
| --- | --- | --- |
| `GET /v1/script.js` | public | The tracker: `<script defer src=".../v1/script.js" data-key="vz_pk_…">`. |
| `POST /v1/collect` | site key | One event, `text/plain` JSON ≤ 8 KB; the origin must be a project domain. → `202`. |
| `GET /v1/projects/:id/analytics` | account key | `?period=24h\|7d\|30d` → `{ totals, timeseries, top_pages, sources, countries, devices, events }`. |

## Replay

| Route | Auth | Does |
| --- | --- | --- |
| `GET /v1/projects/:id/replays/insights` | account key | What goes wrong for visitors (errors, rage and dead clicks, abandoned forms), with example sessions. Start here. |
| `GET /v1/projects/:id/replays` | account key | Sessions, most worth watching first. Filters `has_error`, `rage`, `dead`, `incomplete`, `path`, `period`. |
| `GET /v1/replays/:id` | account key | One session: signals, completeness and a timeline of notable moments. |
| `GET /v1/replays/:id/events` | account key | The raw recording, streamed and paged. |
| `POST /v1/replays/:id/share` | account key | A private player link `{ expires_in? }` (1 h default, 24 h max). |
| `DELETE /v1/replays/:id` | account key | Delete a recording now. → `204`. |
| `GET /v1/replays/:id/player` | signed link | The hosted player page for a share link. |

## Usage and metrics

| Route | Auth | Does |
| --- | --- | --- |
| `GET /v1/usage` | account key | `?period=24h\|7d\|30d\|month&group_by=…` → `{ totals, data, limits }`. |
| `GET /v1/projects/:id/usage` | account key | The same for one project. |
| `GET /v1/metrics` | account key | Requests, error rate and p50/p95/p99 latency by capability. |
| `POST /v1/dashboard/link` | account key | A signed link to the hosted usage dashboard `{ expires_in?, period? }` (1 h default, 24 h max). |
| `GET /v1/dashboard` | signed link | The hosted dashboard page (`?token=`). |

## Billing

| Route | Auth | Does |
| --- | --- | --- |
| `GET /v1/billing` | account key | Balance, status (`active`, `low`, `payment_required`, `past_due`, `exempt`), card (masked), auto-recharge, daily safety cap, `next_step`. |
| `PATCH /v1/billing` | owner key | `{ auto_recharge?: { enabled?, threshold_cents?, amount_cents? }, daily_spend_limit_usd? }` → `billing`. |
| `POST /v1/billing/checkout` | account key | `{ amount_cents (500–100000), save_card? }` → `billing_checkout` with the hosted payment `url` a person opens. |
| `GET /v1/billing/checkout/:id` | account key | One payment page: `open`, `pending`, `succeeded`, `expired`. |
| `POST /v1/billing/card` | owner key | A page to save or replace the card → `billing_checkout` (`kind: card`). |
| `DELETE /v1/billing/card` | owner key | Forget the card and turn auto-recharge off → `billing`. |
| `GET /v1/billing/ledger` | account key | Every money movement, newest first: trial, credits, usage per day, refunds… `?kind=&cursor=&limit=`. |
| `GET /v1/billing/charges` | account key | Card payments (top-ups, auto-recharges, filings) with receipts. `?status=&cursor=&limit=`. |

## App (VIBIZ_APP_KEY)

| Route | Auth | Does |
| --- | --- | --- |
| `GET /v1/app/connectors` | app key | The connectors with their enabled operations (no secrets). |
| `POST /v1/app/connectors/:name/call` | app key | Call an operation in the key's environment `{ operation, params?, body? }`. |
| `GET /v1/app` | app key | `{ project_id, environment }` for the key. |
| `POST /v1/app/contacts` | app key | Add or update a contact (`vibiz.contacts.upsert`). Development keys store nothing. |
| `POST /v1/app/contacts/events` | app key | Track a contact's event (`vibiz.contacts.track`). |
| `POST /v1/app/contacts/unsubscribe` | app key | `{ email }`: no more marketing email (`vibiz.contacts.unsubscribe`). |
| `GET /v1/app/contacts/:email` | app key | One contact with its lists and events. |
| `DELETE /v1/app/contacts/:email` | app key | Forget a contact. |
| `GET /v1/app/env` | app key | The app's env, `?format=json\|dotenv\|shell\|docker`. |
| `POST /v1/app/actions/:name` | app key | Run an action as the project (`email.send`, `web.scrape`, `ads.library`…) `{ input }` → `{ output, cost_micro_usd, usage, run_id? }`. |
| `POST /v1/app/events` | app key | A server-side analytics event `{ name, user?, path?, properties? }`. |
| `POST /v1/app/payments/checkout` | app key | A hosted checkout for one buyer → `{ url }`. |
| `POST /v1/app/files` | app key | Upload a file to the key's project and environment. |
| `GET /v1/app/files` | app key | The environment's files, with the same filters as the project route. |
| `GET /v1/app/files/latest` | app key | The newest matching file. |
| `GET /v1/app/files/:fileId` | app key | One file. |
| `DELETE /v1/app/files/:fileId` | app key | Delete a file. |
| `GET /v1/app/payments/products` | app key | The catalog. |
| `GET /v1/app/payments/payments` | app key | Payments, `?user=&cursor=&limit=`. |
| `GET /v1/app/payments/payments/:paymentId` | app key | One payment. |
| `GET /v1/app/payments/subscriptions` | app key | A user's subscriptions, `?user=&status=active,trialing`. |
| `POST /v1/app/payments/subscriptions/:subId/cancel` | app key | Cancel a subscription for a user. |
| `POST /v1/app/payments/portal` | app key | A billing portal link `{ user, return_url }` → `{ url }`. |

## Platform

| Route | Auth | Does |
| --- | --- | --- |
| `GET /v1/health` | public | Liveness: `{ ok: true }`. |
| `GET /v1/capabilities` | account key | Resource types, action names and services (`company`, `payments`, `social`) this deployment offers. |
| `GET /v1/operations/:id` | account key | One queued unit of work: `{ kind, status: queued\|running\|succeeded\|failed, attempts, error }`. |