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

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:

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

#Endpoints