# API Reference

Base URL: `https://vatio.ai`. All request bodies below are JSON; send
`Content-Type: application/json` on requests with a body. Replace `:slug`,
`:id`, and other path placeholders with the actual value.

Your customers do not use this API. A browser talks to Vatio through the
[SDK](https://vatio.ai/docs/sdk/) with a publishable token, over a separate surface that exposes one
conversation and nothing else about the workspace.

## Getting a token

Every request below is authorized by a **developer token**, which looks like
`vat_…`. There is no token page in the inbox to copy one from: a developer
token is minted by device authorization, where a human approves this machine in
a browser once.

Start the flow, and read `device_code`, `user_code`, `verification_uri_complete`
and `interval` off the response:

```http
POST /api/developer/v1/device_authorizations
Content-Type: application/json
```

Send the person to `verification_uri_complete`, then poll at `interval` seconds
until it answers with the token instead of `authorization_pending`:

```http
POST /api/developer/v1/device_authorizations/token
Content-Type: application/json

{ "device_code": "..." }
```

Neither path is workspace-scoped and neither takes a token — they are how you
obtain one. [Device authorization](https://vatio.ai/docs/api/device-authorization) has the full
flow, including how to list and create workspaces with the result.

If you have a terminal in front of you, `vatio login` runs exactly these two
calls and writes the token to `~/.vatio/config.json`, where you can read it.

## Credentials

Send the token as `Authorization: Bearer TOKEN`. Every path below is relative
to `/api/developer/v1/:slug`, where `:slug` is the workspace.

One token reaches every workspace its user owns. It can deploy, read secrets,
start conversations and mint publishable tokens, so it belongs on a server or
in a CI secret — never in a page, a mobile app, or a repository.

Errors carry `error_key` and `error_message`, or `error` and
`error_description` on authentication failures. See [Errors](https://vatio.ai/docs/api/errors).

## Endpoints

- [Deployments](https://vatio.ai/docs/api/deployments) — Check, deploy, publish, roll back, and read deployment history.
- [Secrets](https://vatio.ai/docs/api/secrets) — Write-only workspace secrets your tools read as $env.KEY.
- [Knowledge bases](https://vatio.ai/docs/api/knowledge) — Bases and the entries you write into them.
- [Business](https://vatio.ai/docs/api/business) — The business name, description and opening hours.
- [Publishable tokens](https://vatio.ai/docs/api/tokens) — Mint and revoke the vatpub_ tokens a page carries.
- [Channels](https://vatio.ai/docs/api/channels) — Where WhatsApp and Instagram are set up for a workspace.
- [Chats](https://vatio.ai/docs/api/chats) — Your own developer conversations, with the full debug view.
- [Contacts](https://vatio.ai/docs/api/contacts) — Export everything about one person, or delete it for good.
- [Messages](https://vatio.ai/docs/api/messages) — Have the agent write to a WhatsApp contact first, from your backend, with a server key.