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

## 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](agent-identity.md) 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.

```sh
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](platform-mcp.md) 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](machine-tokens.md) instead. It reaches only the apps in its Project and can't manage Tokay.

## Go further

[Our agent instructions](https://app.tokay.io/llms.txt) 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.

- [For AI agents](for-ai-agents.md). Credentials, the deploy loop, and what's stable to rely on.
- [Operating and recovering services for agents](agent-operations.md). Logs, diagnosis, rollback, and restore.
- [Managed databases for agents](agent-databases.md). Queries, imports, exports, and snapshots.
- [App access control for agents](agent-access.md). Who can open each app, and Machine credentials.
