HTTP API - Tinycloud

The control-plane API is JSON over HTTP. In a production control-plane process it listens on 0.0.0.0:8787 by default; TINY_BIND_HOST and TINY_API_PORT override that. The embedded application gateway separately defaults to port 8080 (TINY_GATEWAY_PORT). Start both with pnpm api and terminate TLS at the deployment’s reverse proxy.

Conventions

Except for health/readiness/metrics, platform capabilities, and organization bootstrap, routes require Authorization: Bearer <token>. Human sessions and service-account tokens are both resolved to an organization-scoped actor.

In organization paths, the literal self refers to the token’s organization. An explicit ID from another organization returns 404 — not 403, which would confirm the ID exists.

Header	Direction	Meaning
`X-Request-Id`	both	supplied for correlation, always returned
`X-Tiny-Service`	response	which service answered
`ETag`	response	on ordinary JSON `200`s
`Cache-Control: no-store`	response	on everything
`Idempotency-Key`	request	on retryable mutations, notably deploys and broker calls

Errors

Errors have a stable envelope:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "...",
    "remediation": "...",
    "retryable": false,
    "requestId": "req_..."
  }
}

Branch on code and retryable, never on message. See Error codes.

Body size

The API accepts bodies up to 70 MiB, leaving room for a 50 MiB artifact encoded as base64 JSON.

Meta and bootstrap

Method	Route	Auth	Purpose
`GET`	`/v1/health`	no	process liveness
`GET`	`/v1/ready`	no	database and runtime-provider readiness
`GET`	`/v1/metrics`	no	Prometheus text metrics
`GET`	`/v1/platform/capabilities`	no	provider, manifest, policy, catalog, and meter capabilities
`POST`	`/v1/organizations`	no	bootstrap `{slug, displayName, ownerEmail}`

Organization bootstrap returns the organization, runtime target, a once-visible apiToken, and a human sessionToken.

GET /v1/platform/capabilities is the call to make before generating or deploying an app. It is what lets a plan refuse upfront instead of a deploy failing halfway.

Artifacts and deployments

Remote clients upload source bytes before planning or deploying. The server never accepts a caller-selected filesystem path.

Method	Route	Purpose
`POST`	`/v1/artifacts`	store `{sha256, files:[{path, content}]}`; `content` is canonical base64
`POST`	`/v1/apps:plan`	non-mutating plan from `{artifactUri, manifest, environment?}`
`POST`	`/v1/apps:deploy`	persist and enqueue `{artifactUri, manifest, environment?, planId?, approve?}`
`GET`	`/v1/deployments/:deploymentId`	deployment state and failure detail
`POST`	`/v1/deployments/:deploymentId/approve`	enqueue a previously gated deployment
`POST`	`/v1/deployments/:deploymentId/rollback`	repoint traffic to that deployment
`GET`	`/v1/deployments/:deploymentId/logs?limit=&since=`	bounded runtime logs

Deploy returns 202 after desired state and a durable job have been stored. The background reconciler provisions resources, applies migrations, starts and health-checks the candidate, then switches traffic. Poll GET /v1/deployments/:deploymentId for the outcome.

Apps, environments, and access

Method	Route	Purpose
`GET`	`/v1/organizations/:orgId/apps?limit=&cursor=`	paginated app list
`GET`	`/v1/apps/:appId`	app detail
`GET`	`/v1/apps/:appId/deployments?limit=`	recent deployments
`GET`	`/v1/apps/:appId/environments`	production, named, and preview environments
`GET`	`/v1/apps/:appId/access`	access bindings
`PUT`	`/v1/apps/:appId/access/:subject`	grant `{role?, kind?}`
`DELETE`	`/v1/apps/:appId/access/:subject`	revoke a binding
`POST`	`/v1/organizations/:orgId/members`	add `{email, role, groups?}`
`POST`	`/v1/apps:preview`	create from `{artifactUri, manifest, name?, ttlHours?}`
`DELETE`	`/v1/environments/:environmentId`	delete a preview

Lifecycle

Method	Route	Purpose
`POST`	`/v1/apps/:appId/archive`	stop environments and snapshot resources
`POST`	`/v1/apps/:appId/restore`	restore an archived app and its snapshots
`DELETE`	`/v1/apps/:appId?confirm=<exact-slug>`	schedule deletion after a seven-day grace period
`GET`	`/v1/organizations/:orgId/lifecycle-recommendations`	current idle/archive/delete recommendations

Restore does not deploy a worker. Deploy again to resume traffic.

Connections, capabilities, and secrets

Method	Route	Purpose
`POST`	`/v1/organizations/:orgId/connections`	store `{name, provider, credential, environmentClass?}`; credential is never echoed
`GET`	`/v1/capabilities`	list the operation catalog
`POST`	`/v1/apps/:appId/capability-grants`	request `{connection, operations, constraints?}`
`POST`	`/v1/capability-grants/:grantId/approve`	approve as an organization admin
`POST`	`/v1/capabilities/:provider/:resource/:action`	workload-token broker endpoint
`POST`	`/v1/organizations/:orgId/secrets`	create a version from `{name, value}`
`GET`	`/v1/organizations/:orgId/secrets`	list metadata without values

The broker route requires an app workload token, not a human API token. It accepts an optional Tiny-User-Token and Idempotency-Key from the runtime SDK.

Data

These routes serve running applications, not operators. They authenticate with an app workload token alone — no organization is named in the path, because the token is what decides which database the caller may address. A token bound to a deployment that is no longer live is refused.

Method	Route	Purpose
`POST`	`/v1/data/query`	run `{sql, params?}` and return `{rows, rowCount, fields}`
`POST`	`/v1/data/execute`	run `{sql, params?}` and return `{changes}`
`POST`	`/v1/data/transaction`	open a leased transaction, returning `{transactionId, expiresAt}`
`POST`	`/v1/data/transaction/commit`	commit the transaction named by `Tiny-Transaction`
`POST`	`/v1/data/transaction/rollback`	roll it back

Statements inside a transaction carry a Tiny-Transaction header. A transaction not committed before expiresAt is rolled back and its session released. Statement size, parameter count, result rows, and result bytes are all bounded; exceeding one returns RESOURCE_LIMIT_EXCEEDED rather than a truncated answer.

Object storage

The same rules as Data: a workload token alone, and the token decides which namespaces the caller may address. Keys travel in the query string because they contain slashes, and object bodies are raw application/octet-stream rather than base64 in JSON.

Method	Route	Purpose
`PUT`	`/v1/storage/:namespace/object?key=`	store the request body and return `{key, size, etag, lastModified}`
`GET`	`/v1/storage/:namespace/object?key=`	return the object bytes, with `ETag`, `Tiny-Object-Size`, and `Tiny-Object-Modified`
`DELETE`	`/v1/storage/:namespace/object?key=`	delete it, returning `{deleted}`
`GET`	`/v1/storage/:namespace/objects?prefix=`	list up to 1000 keys as `{objects, usedBytes, maxSizeBytes, truncated}`

An object is at most 32 MiB and a key at most 1024 bytes; exceeding either returns PAYLOAD_TOO_LARGE or VALIDATION_FAILED. Filling the namespace quota returns RESOURCE_LIMIT_EXCEEDED.

A missing object returns 404 with details.reason = "object-not-found", which is what lets a client tell an absent key apart from an unreachable namespace. Failures are always JSON, even on the routes that carry bytes.

Audit, usage, and webhooks

Method	Route	Purpose
`GET`	`/v1/organizations/:orgId/audit-events?limit=&targetId=&since=`	audit query
`GET`	`/v1/organizations/:orgId/usage?appId=&since=`	usage samples
`POST`	`/v1/organizations/:orgId/webhooks`	create `{url, eventTypes?}` and return the signing secret once
`GET`	`/v1/organizations/:orgId/webhooks`	list endpoints without secrets
`DELETE`	`/v1/organizations/:orgId/webhooks/:webhookId`	delete an endpoint

Verifying a webhook

Webhook URLs must be public HTTPS destinations. Deliveries include:

X-Tiny-Event-Id: evt_...
X-Tiny-Event-Type: deployment.succeeded
X-Tiny-Signature: t=1756483200,v1=<hex-hmac>

The HMAC-SHA256 input is <timestamp>.<raw-json-body>.

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody: string, header: string, secret: string): boolean {
  const parts = Object.fromEntries(
    header.split(',').map((p) => p.split('=') as [string, string]),
  );
  const expected = createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');

  return timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Sign against the raw body, before any JSON parse-and-restringify. Reserializing changes the bytes and the signature will not match.

​Conventions

​Errors

​Body size

​Meta and bootstrap

​Artifacts and deployments

​Apps, environments, and access

​Lifecycle

​Connections, capabilities, and secrets

​Data

​Object storage

​Audit, usage, and webhooks

​Verifying a webhook

Conventions

Errors

Body size

Meta and bootstrap

Artifacts and deployments

Apps, environments, and access

Lifecycle

Connections, capabilities, and secrets

Data

Object storage

Audit, usage, and webhooks

Verifying a webhook