Skip to content

API reference (user guide)

Generated source of truth: GET /v1/openapi.json (also committed as openapi/openapi.json, 62 operations) and the Scalar UI at http://127.0.0.1:8081/docs. This page lists what the code in crates/rt-api does.

Surfaces

Listener Default bind Routes Auth
control 127.0.0.1:8081 /v1/*, POST /mcp (MCP server), GET /v1/openapi.json, GET /docs (Scalar) Bearer root token or rtk_ key (/mcp: a tenant key only). openapi.json and /docs need none
public 0.0.0.0:8080 ANY /s/{slug}/{path…}, custom Host, {slug}.{routing.base_domain} per service access
internal unix:/data/rt.sock same routes as public, trusted (no access check, no ingress rules, x-rt-invoker honored) none
metrics 127.0.0.1:9090 GET /metrics (Prometheus), GET /healthz, GET /readyz none

There is no /v1/health: use /healthz (sysmon heartbeat < 1 s, 503 when stale) and /readyz (migrations applied, snapshot loaded, not draining) on the metrics listener.

Authentication

Credential Header Notes
Root token (operator) Authorization: Bearer <RT_ROOT_TOKEN> only (never x-rt-key) All routes. Acts on a tenant with x-rt-tenant: ten_… (required for service creation); the system tenant ten_00000000000000000000000SYS is read-only that way (403 reserved for any write)
Tenant key Authorization: Bearer rtk_<key_id>_<secret> or x-rt-key Own tenant only, limited by scopes and optional project_ids and environments. A resource of another tenant is 404, and so is a service whose project or environment the key does not admit
  • Release builds without RT_ROOT_TOKEN answer every control route 503 control_disabled. Debug builds leave the API open.
  • Failed authentications are rate-limited per IP (429 rate_limited + Retry-After). Revoking a key takes effect at once.
  • Operator-only routes (/v1/node/*, /v1/tenants*, /v1/plans) answer tenant keys 403 insufficient_scope, except GET /v1/tenants/{own id}/usage (scope logs:read). GET /v1/version and GET /v1/me take any valid credential.
Scope Allows
services:read every GET on services, versions (not build logs), env, secrets (names), hosts, schedules, queue stats, DLQ, events
services:write create / patch / delete service, hosts, schedules
deploy upload version, rebuild, PUT live
invoke call services with access: "key"
logs:read logs (JSON + SSE), build logs, stats, the tenant's own usage
env:write / secrets:write PUT env / PUT, DELETE secrets
queue:write enqueue, DLQ redrive and purge
data:admin GET data/export, DELETE objects/{name} (a durable object's storage)
sockets:write close open WebSockets (DELETE …/sockets)
keys:write POST / GET /v1/keys, DELETE /v1/keys/{key}: keys of the caller's own tenant, never more than the caller holds (self-service keys)

Conventions

Topic Rule
IDs prefixed ULIDs: ten_, svc_, prj_, key_, sch_, msg_, task_, evt_. Versions are integers (1, 2, …)
Times response timestamps are Unix ms integers (created_at, ts, next_due, expires_at). Request expires_at, since, until are RFC 3339
Bodies JSON ≤ 1 MB. Version uploads are raw bytes (≤ 64 MB at the HTTP layer; the node buffers at most 4 uploads at once, one more, or one the memory governor refuses, is 429 rate_limited; formats and limits under Deploy input)
Errors {"error":{"code","message","details"}}, details is {} unless noted (validation diagnostics, limit_exceeds_plan field/requested/max). Unknown routes: 404 not_found envelope. Bad JSON/query: 422 validation_failed
Pagination ?limit=50&cursor=… (max 200) on tenants, projects, services, events → {items, next_cursor}. Logs: limit default 100, max 1000. Keys, versions, hosts, schedules, secrets, usage are bare arrays
Idempotency Idempotency-Key (≤ 255 bytes, else 422) on POST tenants, projects, services, version upload, schedules, queue: same key + same request replays the stored response for 24 h (per principal, in memory, at most 100,000 entries per node: the oldest go first); different request → 422 idempotency_mismatch
Concurrency ETag header + etag field on service responses ("7"). If-Match on PATCH /services/{s} and PUT …/live → 412 precondition_failed. If-None-Match is not supported
Booleans in query 1, true, yes, on (case-insensitive)
Slugs ^[a-z][a-z0-9-]{1,62}$

Routes

Status = success code. Op = operator token only.

Node (Op)

Method Path Body / query Response
GET /v1/node/status {version, mode: normal\|shed\|drain, default_profile, v8_sandbox, processors, kinds, memory: {budget_bytes, committed_bytes, pressure}, inflight, sockets: {open, objects, pending, max}} (pending: accepted sockets whose client is not connected yet; max: ws.max_sockets)
GET /v1/node/config the configuration the node runs with (rt.toml sections, plans, …). Node secrets never appear (they come from env/files); [[binding]].inject_headers values other than env:NAME and URL user info are shown as <redacted>
PUT /v1/node/config {degradation_mode?, default_profile?, rate_limit?} {applied: [...], pending_restart: [...]} (rate_limit is always pending_restart; degradation_mode: "drain" starts draining)
POST /v1/node/drain 202
GET /v1/node/scheduler scheduler snapshot (P/M/queue lengths) plus admission: {queued, queued_bytes, max_inflight, max_queued, max_queued_bytes} and services: [{service_id, tenant_id, slug, …admission view}] (below)
GET /v1/node/cache cache tier sizes, hit rates

Who am I, versions, plans

Method Path Auth Response
GET /v1/version any valid credential {version, api}: node version, API document version
GET /v1/me any valid credential {principal: operator\|tenant, tenant_id, key_id, scopes, project_ids, environments, plan: {name, settings}\|null, version} (null = all); plan is the tenant's effective plan (overrides applied), null for the operator without x-rt-tenant
GET /v1/plans Op [{name, settings}]: the configured [plans.*]
GET /v1/limits any tenant key (Op: with x-rt-tenant) {plan, day, resets_at, invocations, egress_bytes, storage_bytes, services, schedules}: per quota {limit, used, remaining, period} with period day (since UTC midnight; reset at resets_at, unix ms), total or per_service (schedules: plan.max_schedules applies per service and used is the busiest one). limit and remaining are null when unlimited (invocations_per_day = 0)

Tenants and keys (Op)

Method Path Body / query Status, response
POST /v1/tenants {name, plan, overrides?} (plan must be a configured plan; built-in: free) 201 {id, name, plan, overrides, created_at, disabled}
GET /v1/tenants limit, cursor {items, next_cursor}
GET / PATCH /v1/tenants/{t} PATCH {name?, plan?, overrides?, disabled?} tenant
DELETE /v1/tenants/{t} ?purge=1 204; 409 tenant_not_empty while it owns services and purge is not set
GET /v1/tenants/{t}/usage ?from=YYYY-MM-DD&to= [{service_id, day, invocations, cpu_ms, egress_bytes, storage_bytes}]. Also a tenant key for its own tenant with logs:read (rows of the services the key may touch, by project and environment); another tenant's id is 404
POST /v1/tenants/{t}/keys {scopes: [...] (non-empty), project_ids?, environments?, expires_at?, name?} 201 {id, name, scopes, project_ids, environments, expires_at, created_at, last_used_at, secret}; secret = full rtk_<key_id>_<secret>, shown once
GET /v1/tenants/{t}/keys array of keys without secret
DELETE /v1/tenants/{t}/keys/{key} 204; already revoked → 404

Tokens: your own keys (keys:write)

A tenant key with keys:write (or the operator with x-rt-tenant) manages the keys of its own tenant. A new key never holds more than its creator: a subset of its scopes, of its project_ids and of its environments (asking for null gives the creator's own list, so a restricted creator never mints an unrestricted key) and not past its expires_at (asking for none gives the creator's own); anything more is 403 insufficient_scope with details.reason: "escalation". A key lists and revokes only keys whose project and environment lists are within its own.

Method Path Body Status, response
POST /v1/keys {scopes: [...] (non-empty), project_ids?, environments?, expires_at?, name?} 201 {id, name, scopes, project_ids, environments, expires_at, created_at, last_used_at, secret}, the full rtk_… secret once; 422 on a bad scope, past expiry, a project that is not a prj_… id of the tenant, or a bad environment label; 403 quota_exceeded at 200 live keys
GET /v1/keys array of live keys without secret
DELETE /v1/keys/{key} 204, effective at once; revoked, unknown or out-of-reach → 404

Projects

A project groups a tenant's services and lists their environments. Every tenant has a default project; a service is in one project and one of its environments. {p} is a slug or a prj_… id. Reading needs services:read, changing services:write and a key with no project or environment restriction (create, update and delete alike). Deleting a project removes it from every key's project_ids. The operator needs x-rt-tenant.

Method Path Body / query Status, response
POST /v1/projects {slug (^[a-z][a-z0-9-]{1,62}$), name?, environments? (1 to 20 labels, default ["production"])}; Idempotency-Key 201 {id, tenant_id, slug, name, environments, created_at, updated_at}; 409 project_slug_taken; 403 quota_exceeded at 100 projects; 422
GET /v1/projects limit, cursor {items, next_cursor} ordered by slug
GET / PATCH /v1/projects/{p} PATCH {name?, environments?} (the complete new list) project; 409 environment_in_use when the new list drops an environment a service is in
DELETE /v1/projects/{p} 204; 409 project_not_empty while a service is in it
GET /v1/projects/{p}/environments {project, environments}

Services

Method Path Scope Body / query Status, response
POST /v1/services services:write {slug, runtime: deno\|wasm, name?, profile?, project?, environment?, limits?, scaling?, access?, triggers?, ingress?, egress?, call?, deno?, wasm?} 201 service; 409 slug_taken; 422 validation_failed / limit_exceeds_plan; 403 quota_exceeded
GET /v1/services services:read limit, cursor, slug (exact filter: 0 or 1 item), project (slug or prj_…), environment {items, next_cursor}
GET /v1/services/{s} services:read service + ETag
PATCH /v1/services/{s} services:write any of name, profile, environment, limits, scaling, access, triggers, ingress, egress, call, deno, wasm; If-Match service. Each provided block replaces that block
DELETE /v1/services/{s} services:write ?keep_data=1 204
PUT /v1/services/{s}/live deploy {version, close_sockets?}; If-Match service; 409 version_not_ready for a failed version (pending is accepted); rollback = point it at an older version. Open WebSockets stay and their next events run the new version; close_sockets: true closes them with 1012
GET /v1/services/{s}/data/export data:admin SQLite snapshot (application/vnd.sqlite3)

WebSockets and objects

Method Path Scope Body / query Status, response
GET /v1/services/{s}/objects services:read prefix, limit (1-1000, default 100), cursor {items: [{name, sockets, storage}], next_cursor}: objects holding sockets, and for a durable service the objects with storage (keys or an alarm)
GET /v1/services/{s}/objects/{name}/sockets services:read tag, limit, cursor {items: [{id, object, tags, protocol, created_at, last_message_at, auto_response_at, buffered_amount, remote_ip}], next_cursor} (attachments are never shown)
DELETE /v1/services/{s}/objects/{name}/sockets/{ws} sockets:write code (1000 default, or 3000-4999), reason (≤ 123 bytes) 204; the guest gets webSocketClose
DELETE /v1/services/{s}/objects/{name}/sockets sockets:write code, reason, tag {closed}: every socket of the object (or with the tag)
DELETE /v1/services/{s}/objects/{name} data:admin 204: drops a durable object's storage and alarm (its sockets stay; close them first); 404 when it had none or the service is not durable

The default object of a service is default. The service's stats (GET …/stats) add sockets: {open, objects}.

Service object: {id, tenant_id, slug, runtime, name, profile, project_id, project, environment, live_version, etag, limits, scaling, access, triggers, ingress, egress, call, deno?, wasm?, status: {build_state, tier: T1\|T2\|T3, inflight, last_error, admission}, effective}; effective lists each resolved value with its source ({"cpu_ms": {"value": 1000, "source": "profile:balanced"}}); deno / wasm appear once a knob is set.

status.admission is the service's queueing and autoscaler state, null while it has none (never run, or idle past its idle TTL): {kind: deno|wasm|build, limit, min, max, running, queued, queued_bytes, max_queued, queue_wait_ms, queue_timeouts, demand, latency_baseline_ms, warm_per_proc, instances, min_instances, max_instances, target_instances, rps, last_change, idle_ms}. limit is the adaptive concurrency limit within [min, max] (the ceiling and the plan's tenant cap); queue_wait_ms is the smoothed wait of requests that had to queue (it fades to 0 while requests start without waiting); queue_timeouts counts 503 queue_timeout since the state was created; demand is the decaying peak of running tasks and warm_per_proc the warm instances the autoscaler asks each processor to keep. An instance is one concurrently running copy of the service: instances is how many run now (the same as running), min_instances / max_instances the bounds of the limit (max_instances equals max; min_instances is scaling.min_instances within the plan), target_instances the warm instances wanted in total (warm_per_proc times the processors of the kind, at least min_instances while the service is known), rps the smoothed arrival rate and last_change the latest move of limit as {reason: queue|trend|latency|memory|cpu|idle|bounds, from, to, ago_ms} (null if it never moved). status.inflight equals admission.running.

Block Fields (all optional; unknown fields → 422) Default
access public | key | internal public
limits wall_ms, cpu_ms, memory_mb, max_body_bytes (above plan maximum → 422 limit_exceeds_plan) profile / plan
scaling min_instances (kept warm, never scaled to zero; 0 = scale to zero), max_instances (hard cap of the adaptive limit, excess requests queue; ≥ 1, 0 = unset), max_queued (queue bound, over it 503 overloaded), keep_resident. Both instance bounds above the plan's max_instances are clamped to it (effective shows source plan); min_instances above max_instances → 422 validation_failed. max_concurrency is the old name of max_instances (accepted on input, never returned) min_instances 0; max_instances the plan's limit, else the profile ceiling; adaptive in between
triggers http, interval, cron, queue, call, websocket (booleans) all true
durable true: a durable service (its default export is a class, one instance per object; handlers). A WASM durable service must export std:host/socket-handler (422 missing_export on upload, on PATCHing durable: true when the live version lacks it, and on moving live to such a version) false
ws allowed_origins[] (exact origins such as https://app.example.com, case-insensitive; empty = any Origin; a missing or other Origin gets 403 origin_not_allowed at the upgrade), warm (bool: keep the isolate or instance of an event for the next event of the service), max_sockets (the service's own cap on open sockets, within the plan's) any origin, warm: true, no own cap
ingress allowed_methods[], allow_paths[] (prefix*), ip_allow[] (CIDRs), rate_limit {rps, burst}. A request passes allow_paths only if both its raw path and that path with dot segments resolved (., .., also as %2e, and \ as /) match none
egress allowed_hosts[], denied_hosts[] plan default
profile max_density | balanced | min_latency node default
environment label ^[a-z][a-z0-9-]{0,31}$ (e.g. staging, pr-42); must be one of the service's project's environments (422 listing them otherwise). project (slug or id, create only; default default) cannot change: a PATCH naming another project is 422 production
call allowed_callers[]: who may call (and std:queue-enqueue to) this service. Each entry is a service slug, a svc_… id (stored in canonical form) or env:<environment> (the environment of the target's own project, never another project's); empty = services of the same project in the same environment; a non-empty list names every admitted caller. Another tenant's service (its plan must allow cross-tenant calls) is admitted only by its id. A slug entry admits whichever service holds the slug at call time; prefer ids where that matters. Others get call_not_allowed (see handlers). Changing environment needs the operator or a key with no project or environment restriction []
deno reuse_isolates (bool): reuse an isolate with its evaluated module for the next request of the same version node config, then profile (min_latency: on)
wasm reuse_instances (bool): reuse a component instance for the next request of the same version profile (min_latency: on)

Versions and builds

Method Path Scope Notes
POST /v1/services/{s}/versions deploy Raw body, Content-Type selects the format: application/typescript, text/javascript, application/json ({entry, files, imports?}), application/zip, application/x-tar, application/wasm. ?activate=1 sets live to the new version (&close_sockets=1 also closes the service's WebSockets with 1012; without it they stay); ?compile=lazy\|eager. 201 (lazy, build_state: pending) or 202 (eager, building). Errors: 422 validation_failed (details.diagnostics: [{file,line,col,message}]), 422 invalid_artifact, 413 too_large, 429 build_quota
GET /v1/services/{s}/versions services:read array
GET /v1/services/{s}/versions/{v} services:read {version, source_digest, lock_digest, build_state: pending\|building\|ready\|failed, failure, created_at}; failure is null or {reason: syntax\|resolve\|fetch\|lock_mismatch\|timeout\|oom\|too_large\|internal, message, diagnostics}
GET /v1/services/{s}/versions/{v}/source services:read uploaded bytes
POST /v1/services/{s}/versions/{v}/rebuild deploy 202; clears a failed build
GET /v1/services/{s}/versions/{v}/build/logs logs:read SSE until the build is ready or failed
GET /v1/services/{s}/types services:read ?version= (default live): the .d.ts of a Deno service's rpc export (text/plain), 21ci types; 422 no_rpc_surface without one or for WASM

Deploy input

Runtime Content-Type Shape Limits
deno application/typescript, text/javascript one file, entry main.ts / main.js ≤ 1 MB
deno application/zip, application/x-tar files plus an optional rt.json {entry, imports} (import map) ≤ 10 MB total, ≤ 1,000 files, ≤ 1 MB per file; archives with .., absolute paths or links, or an inflate ratio over 100, are refused
deno application/json {entry, files: {path: content}, imports?} same
wasm application/wasm a WASI P2 component exporting wasi:http/incoming-handler ≤ 50 MB

The upload is validated synchronously, without network: Deno sources must parse (422 validation_failed with details.diagnostics), the entry must exist, and only relative files, std:, allowed sdk:, npm: / jsr: and allowlisted https: specifiers are accepted; a WASM file must be a component with the right export and only allowed imports (422 invalid_artifact). Plan builds_per_hour is checked here (429 build_quota). The version starts as pending. With compile=lazy (the max_density and balanced default) it goes live at once and the first request builds it (that request waits); with compile=eager (min_latency) the build runs now (202) and live flips only when it is ready, so a failed build leaves live unchanged.

Operator SDKs

Runtime services of the system tenant; tenants get the contract and a per-call binding (handlers).

Method Path Scope Notes
POST /v1/sdks Op {name, version, source: base64, runtime?, content_type?, contract?, members?, description?, channel?} → 201 {sdk, version, version_no, members, channels, created_at}. The release is a new version of the SDK's service, built at once; the first one becomes stable. 409 sdk_release_exists, 422 sdk_contract_missing (no defineSdk methods and no contract/members), 422 sdk_unchecked_caller (a method never reads ctx.caller), the upload errors of a version
GET /v1/sdks Op [{name, state: active\|removed, description, service_id, channels: {<ch>: {channel, version, previous, updated_at}}, releases, latest, created_at}]
GET /v1/sdks/{name}/releases Op [{sdk, version, version_no, members, channels, created_at}], oldest first
PUT /v1/sdks/{name}/channels/{channel} Op {version} → {channel, version, previous, updated_at}: promote or roll back; 404 for an unknown release
DELETE /v1/sdks/{name} Op 204: calls answer sdk_unavailable; publishing again restores it
GET / PUT /v1/sdk-grants Op PUT {scope: node\|plan:<name>\|tenant:ten_…\|project:prj_…\|environment:prj_…/<env>, sdk: <name>\|*, effect?: allow\|deny, version_req?, channel?} → 200 grant, or 204 when every field is empty (deleted). An allow without version_req is pinned to the stable major
GET /v1/sdks/effective services:read ?project&environment (default default / production): [{name, description, version, channel, version_reqs, members, reason}], the SDKs the key's grants allow and the release each runs
GET /v1/sdks/{name}/contract services:read the .d.ts of the release the key's grants select (text/plain); the operator may pass ?version=. 404 when not granted

Env, secrets, hosts

Method Path Scope Body → response
GET / PUT /v1/services/{s}/env services:read / env:write bare map {"A":"1"}; PUT replaces the whole map (≤ 100 entries, values ≤ 32 KB)
GET /v1/services/{s}/secrets services:read [{name, updated_at}] (values are write-only)
PUT / DELETE /v1/services/{s}/secrets/{NAME} secrets:write PUT {"value":"…"} (≤ 32 KB; name [A-Z_][A-Z0-9_]*, no RT_ prefix) → 204
GET /v1/services/{s}/hosts services:read [{host, status: pending_verification\|active, verify_token, created_at, expires_at}] (unix ms; expires_at is null once active)
GET /v1/services/{s}/hosts/{host} services:read one host, same shape (the host is normalised: lowercase, no trailing dot); 404 when it is not mapped to this service
PUT / DELETE /v1/services/{s}/hosts/{host} services:write operator: active at once; tenant: pending_verification and only if the plan's custom_host_suffixes allow it (403 host_not_allowed otherwise). Publish the token as TXT at _rt-verify.<host>: the node checks pending claims every hosts.verify_interval and activates a match. A re-PUT of your own pending claim keeps its token and expiry, and so does a DELETE + PUT. A pending claim expires after hosts.pending_ttl (7 days) and then no longer blocks others; the same tenant gets 409 host_cooldown for that host for one more TTL. At most hosts.max_pending_per_tenant (10) pending claims per tenant (403 quota_exceeded). 409 host_taken

Env and secret changes apply to the next task; no redeploy.

Schedules and queue

Method Path Scope Body → response
GET / POST /v1/services/{s}/schedules services:read / services:write POST {kind: "interval", every_seconds (1 s to 10 years), payload?, enabled?} or {kind: "cron", cron: "*/5 * * * *", timezone?: "UTC", payload?, enabled?} → 201 {id, kind, every_seconds, cron, timezone, payload, enabled, next_due}. Payload ≤ 64 KB. A cron follows the wall clock of timezone: a time that a DST change skips fires just after the gap (02:30 on a 02:00 → 03:00 day fires at 03:30), a time that happens twice fires once. Its plan minimum (min_schedule_seconds) applies to the shortest gap between fires
PATCH / DELETE /v1/services/{s}/schedules/{id} services:write PATCH: same body as POST (kind required), the same trigger and plan checks → 200 with the schedule; DELETE → 204
POST /v1/services/{s}/queue queue:write {body: <any JSON>, delay_seconds?: ≤ 7 d, dedup_id?} → 202 {id}; body ≤ 1 MB (413 too_large); 429 queue_full; 403 trigger_not_allowed when the service's queue trigger is off or the tenant's plan does not allow queue
GET /v1/services/{s}/queue services:read {depth, in_flight, oldest_age_ms, dlq}
GET / DELETE /v1/services/{s}/dlq services:read / queue:write GET {items: [{id, body, attempts, failed_at}]} (≤ 100); DELETE 204
POST /v1/services/{s}/dlq/redrive queue:write {redriven: N}

A disabled trigger (triggers.cron=false, plan allowed_triggers) → 403 trigger_not_allowed. Interval below the plan minimum → 422 schedule_too_frequent; schedule count above the plan → 403 quota_exceeded.

Logs, stats, events

Method Path Scope Notes
GET /v1/services/{s}/logs logs:read ?since&until&level=debug\|info\|warn\|error&kind=runtime\|build\|system&task_id&limit&cursor → {items: [{seq, ts, level, service_id, version, task_id, trigger, kind, msg, truncated}], next_cursor}
GET /v1/services/{s}/logs?follow=1 logs:read SSE: id: <seq>, event: log, data: <log JSON>; resume with Last-Event-ID. At most ingress.sse_streams_per_key streams per key (429 rate_limited)
GET /v1/services/{s}/stats logs:read ?window=5m\|1h\|24h (default 5m): counts, error rate, p50/p95/p99, plus admission (the service's queueing / autoscaler state, as in the service object)
GET /v1/services/{s}/events services:read limit, cursor → {items: [{id, ts, kind, data}], next_cursor} (deploy, rollback, key.created, …)

Control error codes

Each code is explained in Error reasons: what it means and what to do about it.

code HTTP
unauthorized 401
insufficient_scope, quota_exceeded, trigger_not_allowed, binding_not_allowed, host_not_allowed, reserved (the system tenant) 403
not_found 404
slug_taken, host_taken, host_cooldown, version_not_ready, tenant_not_empty, project_slug_taken, project_not_empty, environment_in_use, sdk_release_exists 409
precondition_failed 412
too_large, storage_quota, egress_quota 413
sql_error, sql_not_authorized, sql_result_too_large, kv_not_integer, kv_overflow (guest data, e.g. on export) 422
sql_busy, sql_timeout 503
validation_failed, invalid_artifact, missing_export (a durable WASM service without socket-handler), limit_exceeds_plan, schedule_too_frequent, idempotency_mismatch, no_rpc_surface, sdk_contract_missing, sdk_unchecked_caller 422
rate_limited, build_quota, queue_full 429 (Retry-After when known)
not_implemented 501
control_disabled 503
anything else (internal) 500

MCP

POST /mcp on the control listener is a Model Context Protocol server for AI assistants: 26 tools that call the routes above as the key that connects (whoami, get_limits, projects, SDKs, services, deploy_code, versions and rollback, schedules, objects and WebSockets, logs and stats, env and secrets, tokens). It takes a tenant key as a Bearer token, answers JSON, and speaks the initialize handshake of 2024-11-05 to 2025-11-25 and the stateless 2026-07-28 revision. See mcp.md for the tools, the transport rules and how to connect Claude Code, Claude Desktop and Cursor.

Invoke API

ANY /s/{slug} and ANY /s/{slug}/{path…} on public (or internal). The handler sees /{path}?query; the prefix is passed as x-rt-base-path. With a custom host or {slug}.{base_domain} the path is unchanged.

Order of checks: route → the tenant's plan allows http (else 403 trigger_not_allowed) → access (key: root token or key with invoke for this service, else 401; 10 wrong rtk_ keys per minute from one client, then 429 rate_limited) → ingress rules (405 method_not_allowed, 403 forbidden, 429) → quotas → admission → run.

Added Header
to the guest request x-rt-trigger: http, x-rt-base-path, x-rt-invoker (internal only), x-rt-client-ip (the client address behind ingress.trusted_proxies; none on the Unix socket), traceparent (generated if absent). Client x-rt-* (including x-rt-client-ip and x-rt-key), hop-by-hop headers and an Authorization carrying an rtk_… key or the root token are stripped; any other Authorization reaches the guest unchanged
to the response x-rt-task-id, x-rt-version, server-timing: queue;dur=…, wait_runtime;dur=…, init;dur=…, exec;dur=…. The guest's hop-by-hop headers (connection, transfer-encoding, keep-alive, upgrade, …) are dropped, and so is a content-length that does not match the body

Failures are text/plain with the reason as body and in x-rt-reason (never JSON). Each reason is explained in Error reasons.

x-rt-reason HTTP
not_found (unknown slug, no live version, triggers.http=false) 404
unauthorized 401
forbidden (path / IP rule) 403
trigger_not_allowed (the tenant's plan does not allow http) 403
method_not_allowed 405
too_large (request body over limits.max_body_bytes, default 10 MB) 413
rate_limited, quota_exceeded (plan quotas), tenant_concurrency, service_concurrency (legacy, no longer produced: capacity waits in a queue instead) 429 (+ Retry-After)
guest_error (uncaught exception; body never contains the message, see logs) 500
cpu_limit, oom, build_failed 502
draining, shed, overloaded, queue_timeout, memory, restarting (a request that waits for memory ends as queue_timeout; memory refuses a WebSocket upgrade while the node is short of memory) 503
route_stale (a control change is being applied; retry after 1 s) 503
timeout (wall limit) 504
call_depth 508

WebSocket upgrades (GET with Upgrade: websocket, HTTP/1.1) take the same path, plus, before any task runs: triggers.websocket and the plan allow it (403 trigger_not_allowed), the node is not draining (503 draining) or short of memory (503 memory), and the Origin is one of ws.allowed_origins (403 origin_not_allowed). For access: "key" a browser, which cannot set Authorization, may pass the key as the first subprotocol (new WebSocket(url, ["rtk_…", "chat"])); it is removed before the guest sees the request. The guest answers with sockets.accept(req) (101); any other response goes out as it is. A 101 that the guest did not accept is 502 bad_upgrade. Socket caps (ws.max_sockets, the plan's max_sockets and max_sockets_per_object, the service's ws.max_sockets) fail the guest's accept with limit_exceeded. See handlers.

Plans (built-in free; more under [plans.<name>])

max_services 10, max_concurrency 10, max_instances 4 (per service, 0 = node default), rps 50, invocations_per_day 100,000, storage_mb 100, egress_mb_per_day 1,000, max_schedules 3, min_schedule_seconds 60, max_queue_depth 10,000, builds_per_hour 20, allowed_triggers http interval queue call websocket (no cron), limits_max wall 30 s / CPU 1 s / 128 MB, custom_host_suffixes none, allow_cross_tenant_calls false, max_sockets 1,000 (open sockets of the tenant; 0 = only the node cap), max_sockets_per_object 1,000, ws_max_message_bytes 1 MiB.

Example

API=http://127.0.0.1:8081; KEY=rtk_…                       # tenant key with services:read, services:write, deploy
H=(-H "Authorization: Bearer $KEY")

SVC=$(curl -sS "${H[@]}" -H 'Content-Type: application/json' -d '{"slug":"hello","runtime":"deno"}' $API/v1/services | jq -r .id)
printf 'export default () => new Response("hi")\n' > hello.ts
curl -sS "${H[@]}" -H 'Content-Type: application/typescript' --data-binary @hello.ts "$API/v1/services/$SVC/versions?activate=1"
# 201 {"version":1,"source_digest":"sha256:…","lock_digest":null,"build_state":"pending","failure":null,"created_at":…}
curl http://127.0.0.1:8080/s/hello/                          # hi  (first request compiles)

curl -sS "${H[@]}" -X PUT -H 'Content-Type: application/json' -d '{"version":1}' $API/v1/services/$SVC/live   # roll back / pin
curl -sSN "${H[@]}" "$API/v1/services/$SVC/logs?follow=1"                                                     # SSE

sample/scripts/deploy.sh does the same (find/create service, upload, activate, optional RT_COMPILE=eager wait); invoke.sh wraps the invoke call.