Tokay API

The Tokay API is a public GraphQL API for your scripts and CI, and it's the same API our web interface uses. Manage Projects, Services, deploys, and managed databases from your own code. Deploy after every merge, roll back a bad release, or export a database every night.

Last updated

AI agent? Start with llms.txt.

Get a token

For a script you run yourself, open Connections in Tokay, choose Connect, then Your own script. Name the token, choose what it can do, and set when it expires. The script works as you and never gets more access than you have.

For CI or anything your team shares, create a Bot under CI and deploys instead. A Bot has its own name and access, so its work keeps running when people come and go. Identity and permissions for agents covers Bots and grants in detail.

Make your first call

The endpoint is https://api.tokay.io/graphql. Send each request with your token as a bearer credential. Our agent instructions and error messages call this same API the Platform API.

curl https://api.tokay.io/graphql \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ viewer { id } }"}'

Field and argument names use camelCase. Introspect the schema for exact fields rather than relying on remembered ones, and ask for one type at a time, since the whole schema is large. Lists hang off the workspace, project, repository, or service that owns them, and every list is paginated.

Tokay MCP uses the same API

Tokay MCP gives AI assistants the same platform through tools, usually with a browser sign in instead of a pasted token. Its tools cover the common workflows, and two general tools, one for reads and one for routine changes, reach the rest of the API. MCP and API tokens are separate, so use an API token for direct calls.

Files and large transfers

Large files never travel through GraphQL. A mutation returns a short lived URL, and you upload or download the bytes over plain HTTP. Source archives, saved files, and database imports and exports work this way.

Calling your own apps is different

A Tokay API token manages Tokay. To call one of your deployed apps that sits behind Tokay sign in, use a Machine credential instead. It reaches only the apps in its Project and can't manage Tokay.

Go further

Our agent instructions give the exact deploy sequence, with every query, mutation, and recovery step. They suit any script, not only AI agents. The reference pages below go deeper on each area.