For AI agents
This page is for an agent operating Tokay on behalf of a user. Use the API schema and current resource state as the source of truth. Do not infer deployment state from timing, parse human logs for platform status, or confirm a paused database migration without an explicit user decision.
Last updated
AI agent? Start with llms.txt.
The GraphQL endpoint is https://api.tokay.io/graphql. Field and argument names use camelCase on the wire.
curl https://api.tokay.io/graphql \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json" \
-d '{"query": "{ __schema { queryType { name } } }"}'
Introspect the schema rather than relying on remembered fields. Ask for one type by name, such as __type(name: "DeployServiceInput") for a mutation's arguments, since introspecting the whole Mutation type returns about 80,000 characters. The executable protocol with exact operations is at https://app.tokay.io/llms.txt. Read it in full before your first call; afterwards Tokay MCP's search_tokay_docs finds a detail in it or in the reference pages it links.
Lists hang off the workspace, project, repository, or service that owns them, so read them from workspace(id:) or another node you hold. The only root lists are workspaces, manageablePlatformCredentials, and the global catalogs. Always paginate.
When the client supports remote MCP, use the official Tokay MCP at https://mcp.tokay.io/mcp for the source, deployment, diagnosis, usage, and reviewed action workflows. MCP and API tokens use separate audiences. Use an API token for direct GraphQL and REST, and for every script or automation: MCP is for the interactive agent, and its OAuth needs a person. Unattended automation uses a Bot's token (below); a person's own token fits a script they run themselves.
Use the credential intended for Tokay management
Your API or MCP credential acts for a durable Person or Bot and carries explicit action grants. It can reach only the Workspaces, Projects, and code available through that principal's live memberships. Each destination is exact. API credentials work at GraphQL and REST, while MCP credentials work only at Tokay MCP.
A Bot is a full Workspace identity with its own Project and repository roles and independently managed credentials. Prefer a Bot for durable, isolated, or unattended automation. A tool operated by a person normally connects as that Person through OAuth.
Authority is the intersection of live membership, explicit credential grants, and accepted destination on every request. Revoking membership or the credential changes the next protected call.
Use viewer for the acting Person or Bot Principal, currentPerson for the human Person when one exists, and currentCredential for the exact credential admitted on this request. currentCredential includes its destination and grants and may be a browser session.
A value beginning with tokay_machine_ is different. It is one credential of a durable Tokay Access Machine, authenticates only to deployed apps in that Project, and cannot manage Tokay resources.
Follow the asynchronous deploy loop
Deployment is an act and poll workflow.
- Submit files directly or create a repository and push code.
- Poll repository analysis until the detected Service candidates are ready.
- Create the intended Services from the candidates or supply explicit configuration.
- Poll
deployReadinessfor the next action. - Resolve the blocker named by readiness, such as a missing environment value or an unconfirmed database source.
- Start the deployment when the action is
DEPLOY. - Poll until readiness reports the Service is up to date and the runtime state is healthy.
WAIT means Tokay is already doing work, including a queued auto-deploy. Do not start a duplicate operation. Service creation for the same unchanged intent is idempotent, so retrying after an uncertain network result is safe.
Ask the user for private values when required, then write them through the API. New or ambiguous values belong in a Project Secret. Use Project Config only when the user explicitly treats the value as nonsecret. Stored Secret values are write only and cannot be read back, while Config is inspectable when your identity can read source or write Config.
Use the typed value mutations in the protocol. setProjectSecretValueByName and setProjectConfigValueByName create or update each type. Service override mutations also name their target type. There is no generic type field to flip. Replacing one type with the other requires both write permissions and a fresh value because no plaintext or history crosses the security boundary. The Workspace Size bounds values: runtimeEnvValueMaxBytes per value (VALUE_TOO_LARGE, at most 127 KB) and runtimeEnvTotalMaxBytes for everything the workspace's running services receive (RUNTIME_ENV_BUDGET_EXCEEDED). One service receives at most 1 MB of names and values (also RUNTIME_ENV_BUDGET_EXCEEDED), since every value becomes an environment variable of its process.
Changing what a running Service receives (a value, override, declared variable, database connection or password, or Saved Files path) redeploys the build it already runs, the same way a push does: no downtime unless its Saved files hold an embedded database such as SQLite (Deploys and rollback), readiness reports it deploying, and History records it. If the new value stops the app, that deployment fails with a diagnosis and the previous one keeps serving with its old values. Fix or revert the value. A rollback restores code, never values.
Project Config and Secrets reach a Service when it starts, and a variable its code reads while it builds (envVarNeed.readAtBuild) gets its value at build time too, as a BuildKit secret, so changing it rebuilds the Service. A name beginning with VITE_, NEXT_PUBLIC_, or REACT_APP_ usually needs a public production value committed to source and a new build, except a sibling Service's address, which Tokay builds in as a same-origin path. Such a variable's need reads isBuildValue: true, and a Config or Secret of its name never clears its MISSING_ENV_VAR_VALUE blocker, because none reaches the bundle. When the variable is another Service's address, route it to that Service with setServiceEnvVarOverrideToService, which builds the address in. Otherwise commit the value. Do not place a credential in source or assume a stored runtime value changes an existing frontend bundle.
Tokay tells every running Service which commit it runs: TOKAY_COMMIT holds the full commit SHA of its current deployment. A rollback reports the commit it rolled back to, and a Service a push left unchanged keeps reporting the commit it runs. Read it for a version display or error reports instead of committing a version file such as build.json or _version.py: a file rewritten on every push makes each push a change Tokay analyzes, builds and deploys. It is set at runtime only, not during the build, and a Service deployed before Tokay set it has none until its next deploy, so treat it as optional.
TOKAY_PROCESS says which kind of container runs the code: service in the Service itself (a scheduled run included), task in a one-off task, and release in a release command. Tasks and release commands run the Service's code with its values and storage, so code that starts work when it loads, such as a trading loop, a queue consumer, or an in-app scheduler, should skip it when TOKAY_PROCESS is task or release. Check for those two values rather than for service: the variable is unset when you run the code locally and in a Service built before Tokay set it, and both should behave as the Service.
Use diagnoses for failures
Analysis, build, deployment, and runtime failures expose a diagnosis with a category, human readable message, and next action. Use the Service's current diagnosis field to find the issue that matters now.
Do not classify a platform failure by scraping logs. Read logSnapshot when recent application output is useful. For a crash, use the preserved incident tail. A diagnosis can also include a proposed code fix that should be reviewed before application.
Operate the deployed Service through supported primitives
Run maintenance commands with runServiceTask. A task uses the deployed Service environment and records output and exit status, replacing the need for SSH.
Service files can be listed, downloaded, and uploaded through ticket operations. A file written outside persistent storage can be rescued from the current instance into Saved storage before a restart. Use the instance guard from the protocol so a replacement instance cannot be mistaken for the one inspected.
Repository source is a separate API surface. Use the current source snapshot to list paths and fetch individual text files at an exact commit. See Repository source for agents.
Store stable identifiers rather than presentation names
Treat IDs as opaque strings returned by the API. Do not construct or decode them.
Use publicUrl as the stable Tokay address for a Service. A custom domain alias can move between Services and should not be stored as the identity of a Service. Renaming a WEB Service changes its publicUrl, and the old address keeps redirecting to it. So a WEB Service can be renamed at most three times, and a fourth rename fails with SERVICE_RENAME_LIMIT_REACHED.
Pace bulk work within platform limits
Pipeline triggering pushes are limited to 60 per minute per account, and no more than 10 pipelines can be active at once. Poll readiness rather than sending additional pushes or deploy mutations while work is in flight.
Preserve the human approval boundary
Deployments are designed to recover from ordinary agent mistakes. Failed web versions do not receive traffic, deletions are recoverable for 30 days, and actions are attributed.
If release safety pauses a database migration, Tokay returns the rehearsal impact and waits for the user's decision. Surface that evidence and do not confirm the migration on your own.