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 destructive database changes automatically.

Last updated July 14, 2026

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.

Use the credential intended for Tokay management

An API token acts as the identity that created it and carries explicit action grants. It can reach only the Workspaces, Projects, and code available through that identity's live memberships.

An agent identity is a first class Workspace member with its own Project and repository roles and its own tokens. Prefer this model for a durable agent owned by a team.

Authority is the intersection of identity membership and token grants on every request. A revoked membership narrows the token immediately.

A value beginning with tokay_machine_ is different. It authenticates requests to a deployed app 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. Stored secret values are write only and cannot be read back.

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.

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.

A destructive database migration is different. Tokay rehearses it and returns the impact, then waits for confirmation. Surface that decision to the human. Do not confirm it on your own.