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. The executable protocol with exact operations is at https://app.tokay.io/llms.txt.

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.

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.

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.

  1. Submit files directly or create a repository and push code.
  2. Poll repository analysis until the detected Service candidates are ready.
  3. Create the intended Services from the candidates or supply explicit configuration.
  4. Poll deployReadiness for the next action.
  5. Resolve the blocker named by readiness, such as a missing environment value or an unconfirmed database source.
  6. Start the deployment when the action is DEPLOY.
  7. 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 kind. Service override mutations also name their target kind. There is no generic kind field to flip. Replacing one kind with the other requires both write permissions and a fresh value because no plaintext or history crosses the security boundary.

Project Config and Secrets are runtime only. A name beginning with VITE_, NEXT_PUBLIC_, or REACT_APP_ usually needs a public production value committed to source and a new build. Do not place a credential in source or assume a stored runtime value changes an existing frontend bundle.

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 canonical custom domain address is also stable. A custom domain alias can move between Services and should not be stored as the identity of a Service.

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.