HTTP API overview

Tilecast’s application API is served by Tilecast Server. Most application routes are under /api/v1. Use the health routes and platform provisioning URLs for their specific purpose; they are not general application API routes.

Response format

Successful JSON responses wrap their result in data:

Successful response

{ "data": {} }

Errors use an error object with a machine-readable code and a human-readable message:

Error response

{
  "error": {
    "code": "machine_readable_code",
    "message": "Human-readable explanation."
  }
}

The HTTP status carries the success or failure result. Do not infer success from the presence of a response body alone.

Retry requests safely

Do not retry every failure immediately. A 429 response means a Tilecast rate limiter refused the request and includes a Retry-After header in seconds. Wait at least that long before trying again. Operations that affect screens are also rate-limited; the default server limit is 60 such requests per user and address per minute.

Retry reads after transient network errors or 502/503 responses when appropriate. For writes, use the endpoint’s documented concurrency or idempotency mechanism before retrying after an unknown result. Player commands carry idempotency keys, and resumable media uploads continue from the server-reported offset. Do not assume every create or update route is idempotent.

A 409 usually means current server state conflicts with the request, such as a stale revision or upload offset. Re-read that state and reconcile before retrying. A 422 is a validation or compatibility failure; waiting and sending the same request again does not fix it.

Use the right authentication

Tilecast has separate credentials for each kind of client. One credential cannot be used in another client’s place.

Client	Authentication	Purpose
Studio browser	Server session cookie; unsafe requests also send the session’s CSRF token.	User actions in Tilecast Studio.
CLI, MCP, scripts, and CI	Authorization: Bearer tcp_... (personal access token) or a CLI sign-in	User actions as the token’s account, limited by its scopes.
Tilecast Player	Authorization: Bearer tc_device_<public-id>.<secret>	Authenticated Player communication after pairing and enrollment.
External integration	Authorization: Bearer tci_<public-id>.<secret>	The specific capability granted when the Owner created the token.

A personal access token reaches the same management routes as Studio. Tilecast Server checks the account’s current role and screen access on every request, and the token’s read, write, and admin scopes limit it further. Bearer requests don’t send a CSRF token. The tilecast CLI and MCP server use this same API.

Integration tokens are intentionally limited. The supported capabilities are Write Manual Table rows and Read fleet health. They do not provide general Studio access. See Create an integration token for token lifecycle and supported integration requests for examples.

Handle limits and retries

Some authentication, pairing, installation, and operator-action routes are rate-limited. A limited request returns HTTP 429 with the error code rate_limited and a Retry-After header in seconds. Wait at least that long before retrying. Do not loop immediately on a 429.

Tilecast does not expose one global request quota for the whole API. Limits are attached to sensitive route groups. Management operations that use the shared operator limiter currently allow 60 requests per minute for the same address and signed-in user; other route groups use different limits.

For write requests, follow the concurrency or idempotency field documented by that endpoint when one exists. If a connection fails after sending a write, read the resource before repeating the request blindly. For example, Layout draft writes use expectedDraftRevision, and Player commands carry their own idempotency keys.

Health and readiness

• GET /healthz checks that the server process responds.
• GET /readyz returns ready only when the database and media storage/processing tools are available. It returns 503 when those dependencies are unavailable or a restore is in progress.

Use these endpoints for service health checks. They do not authenticate as a Studio user or Player.

Inspect expected playback

GET /api/v1/screens/{id}/playback-plan explains which presentation the server selects for a Screen. Use a management credential with the read scope and access to that Screen. Omit the at query parameter to use server time, or provide one RFC 3339 instant with a time zone.

For example, ?at=2026-10-02T16:15:00Z asks about that exact instant. Current and future requests evaluate the configuration that exists when you inspect it. Past requests read recorded expectations. A gap in those records stays visible as historical_expectation_unavailable; today’s assignments do not fill it.

Current evidence includes the selected source, alternatives, schedule precedence, the next reevaluation boundary, manifest synchronization, and reported Widget presentation support. A reevaluation boundary does not promise that the content changes. Synchronization and capability reports describe the latest known state, including when you ask about the future.

Selected content also includes its current name and known revision. Layout revisions refer to the published version. Historical responses keep recorded identities and revisions; they do not borrow today’s names.

This response describes expected selection. It does not prove what appeared on the physical display, report media readiness, or reproduce device decoder behavior. The Screen playback explanation uses this endpoint in Studio. See the Playback Plan engineering contract for evidence boundaries and error codes.

OpenAPI description

The endpoint reference in this section is generated from Tilecast’s OpenAPI description and lists each route’s parameters and responses. The source is the repository’s OpenAPI YAML. Human-written integration workflows are on Integrations; Player setup and pairing are on Players.