Platform operations. Substrio docs

`app`

`app.get`

Read this app's own record: slug, hosts, domains, suspended, readonly, live_by_promote, account_id, created_at and its limits. The app is the one the request names (X-Substrio-Tenant or its host).

Route: GET /v1/_app
Auth: App key tenant
MCP tool: substrio_app_get
CLI: substrio op app.get

Parameters

No parameters.

Response

Field	Type	Present	Description
`suspended`	`boolean`	Always
`suspend_reason`	`"billing" \| "abuse" \| "owner_request" \| "maintenance"`	When set	present only while suspended is true.
`suspend_note`	`string`	When set	present only while suspended is true.
`readonly`	`boolean`	Always
`live_by_promote`	`boolean`	Always	the live version changes only by promote (`version.live.set`): a function is changed in a version, never deployed straight to live.
`hosts`	`array of string`	Always
`_id`	`integer`	Always
`account_id`	`integer`	Always	the account that owns the app (`account.get`); 0: the platform.
`slug`	`string`	Always
`subdomain`	`string`	Always
`createdAt`	`integer`	Always
`customDomain`	`string`	Always
`domains`	`array of string`	Always
`flags`	`integer`	Always
`active`	`boolean`	Always
`storageBytesLimit`	`integer`	Always
`storageBytesUsed`	`integer`	Always
`documentsLimit`	`integer`	Always
`documentsCount`	`integer`	Always
`requestsPerMinute`	`integer`	Always
`maxDocumentSize`	`integer`	Always
`cfCpuLimitMs`	`integer`	Always
`cfMemoryLimitMb`	`integer`	Always
`cfTenantMemoryLimitMb`	`integer`	Always
`cfConcurrentLimit`	`integer`	Always
`cfTimeoutS`	`integer`	Always

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_app" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

Read everything a dashboard's first paint needs for this app in one call: app (slug, tenant_id, created_at, hosts, domains, suspended, live_by_promote, is_sandbox), usage (the same body as tenant.usage.self), storage (database_bytes on disk and backups: count, bytes, latest_at), versions (live, rollback_to, count, sandboxes), functions (count, names), collections (count), cron (count), queues (count), alerts (log alerts fired in their last window), audit (the last 5 entries, newest first) and mesh (this app's mesh position, in short).

Route: GET /v1/_overview
Auth: App key tenant
MCP tool: substrio_app_overview
CLI: substrio op app.overview

Parameters

No parameters.

Response

Field	Type	Present	Description
`app`	`object`	Always
`usage`	`object`	Always	the same body as `tenant.usage.self`.
`storage`	`object`	Always
`versions`	`object`	Always
`functions`	`object`	Always
`collections`	`object`	Always
`cron`	`object`	Always
`queues`	`object`	Always
`alerts`	`array`	Always	log alerts that fired in their last window.
`audit`	`array`	Always	the last 5 entries, newest first.
`mesh`	`object`	Always	the servers this app runs on, for the operator.

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_overview" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`documentation`

`documentation.agent_guide`

Read the guide for AI agents building on substrio (text/plain); a tenant's own /llms.txt function route or site file is served instead.

Route: GET /llms.txt
Auth: None none
CLI: substrio op documentation.agent_guide

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/llms.txt"

`documentation.brief`

Start here, in at most 3 KB. Answers the app, what this key is, the live version number, the goals an app is built for (website, api, database, auth, events: each with its summary, its skill and the tools it needs), the build loop's tools in order, and how to reach every other tool. Takes no input; substrio_tools {area: <goal>} answers a goal's full definitions, substrio_start every area's tools.

Route: GET /v1/_brief
Auth: App key tenant
MCP tool: substrio_brief
CLI: substrio op documentation.brief

Parameters

No parameters.

Response

Field	Type	Present	Description
`tenant`	`string`	Always	the app's slug.
`key_scope`	`"system" \| "tenant" \| "user"`	Always	what the calling key is: system (the master key), tenant (this app's administrator key) or user.
`live_version`	`integer or null`	Always	the version number live on this app (a sandbox: on this sandbox); null when none was made live.
`goals`	`array of object`	Always	what an app is built for; substrio_tools {area: <goal name>} answers a goal's full tool definitions.
`next_steps`	`array of string`	Always	the build loop in order, by MCP tool name.
`more`	`string`	Always	how to reach every other tool and the full guide.

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_brief" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`documentation.capabilities`

Describe typed capabilities.

Route: GET /v1/_capabilities
Auth: None none
CLI: substrio op documentation.capabilities

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_capabilities"

`documentation.openapi`

Read generated OpenAPI.

Route: GET /v1/_openapi
Auth: None none
CLI: substrio op documentation.openapi

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_openapi"

`documentation.page.get`

Read one doc page by name (the route's {name}): its Markdown. 404 when no such page. No key needed.

Route: GET /v1/_docs/pages/{name}
Auth: None none
MCP tool: substrio_docs_page
CLI: substrio op documentation.page.get

Parameters

Name	In	Type	Required	Description
`name`	path	`string`	Yes	the page or skill name, as the list answers it.

Response

Field	Type	Present	Description
`name`	`string`	Always
`title`	`string`	Always
`description`	`string`	Always
`markdown`	`string`	Always	the page or skill as written (Markdown; a skill starts with its frontmatter).

Errors

KEY_NOT_FOUND: call documentation.page.list to find the right one.

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_docs/pages/$NAME"

`documentation.page.list`

List every doc page compiled into this server (name, title, one line); read one with documentation.page.get. No key needed.

Route: GET /v1/_docs/pages
Auth: None none
MCP tool: substrio_docs_pages
CLI: substrio op documentation.page.list

Parameters

No parameters.

Response

Field	Type	Present	Description
`pages`	`array of object`	Always

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_docs/pages"

`documentation.registry`

Describe the typed operation registry.

Route: GET /v1/_operation_registry
Auth: None none
CLI: substrio op documentation.registry

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_operation_registry"

`documentation.runtime_types`

Read the TypeScript declarations of the function runtime (text/plain): every global a function can call; a tenant's own /runtime.d.ts function route or site file is served instead.

Route: GET /runtime.d.ts
Auth: None none
CLI: substrio op documentation.runtime_types

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/runtime.d.ts"

`documentation.skill.get`

Read one agent skill by name (the route's {name}): its SKILL.md, frontmatter first. 404 when no such skill. No key needed.

Route: GET /v1/_docs/skills/{name}
Auth: None none
MCP tool: substrio_skill
CLI: substrio op documentation.skill.get

Parameters

Name	In	Type	Required	Description
`name`	path	`string`	Yes	the page or skill name, as the list answers it.

Response

Field	Type	Present	Description
`name`	`string`	Always
`title`	`string`	Always
`description`	`string`	Always
`markdown`	`string`	Always	the page or skill as written (Markdown; a skill starts with its frontmatter).

Errors

KEY_NOT_FOUND: call documentation.skill.list to find the right one.

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_docs/skills/$NAME"

`documentation.skill.list`

List every agent skill (name, title, what it does and when to use it); start with start-here. Read one with documentation.skill.get; substrio skills install writes them where your agent reads them. No key needed.

Route: GET /v1/_docs/skills
Auth: None none
MCP tool: substrio_skills
CLI: substrio op documentation.skill.list

Parameters

No parameters.

Response

Field	Type	Present	Description
`skills`	`array of object`	Always

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_docs/skills"

`documentation.start`

Start here. Answers what this key can do on this app: the tenant, the key's scope, the live version number, every area of tools (functions, deploy, data, query, schema, schedule, files, config, access, observability, backup, ai, platform) with each tool's id, name and one-line summary, and the next steps of the build loop in order. Takes no input; read substrio://guide or GET /llms.txt for the long form.

Route: GET /v1/_start
Auth: App key tenant
MCP tool: substrio_start
CLI: substrio op documentation.start

Parameters

No parameters.

Response

Field	Type	Present	Description
`tenant`	`string`	Always	the app's slug.
`key_scope`	`"system" \| "tenant" \| "user"`	Always	what the calling key is: system (the master key), tenant (this app's administrator key) or user.
`live_version`	`integer or null`	Always	the version number live on this app (a sandbox: on this sandbox); null when none was made live.
`areas`	`array of object`	Always
`next_steps`	`array of object`	Always	the build loop in order.
`skills`	`array of object`	When set	the agent skills (start with start-here): each read at its path, or as the MCP resource substrio://skills/<name>.

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_start" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`documentation.tools`

The full definitions of one area's tools: the area is a name documentation.start lists (functions, deploy, data, query, schema, schedule, files, config, access, realtime, observability, backup, ai, account, platform). Answers each tool this key may call in that area as an MCP tool definition (name, title, description, inputSchema, outputSchema, annotations). The default tool list holds only the everyday tools; call any other by its own name, or through substrio_call.

Route: GET /v1/_start/{area}
Auth: App key tenant
MCP tool: substrio_tools
CLI: substrio op documentation.tools

Parameters

Name	In	Type	Required	Description
`area`	path	`string`	Yes	The area whose tool definitions to answer, as `documentation.start` names it: functions, deploy, data, query, schema, schedule, files, config, access, realtime, observability, backup, ai, account or platform.

Response

Field	Type	Present	Description
`area`	`string`	Always
`summary`	`string`	Always
`tools`	`array of object`	Always	every tool of the area this key may call, as an MCP tool definition: name, title, description, inputSchema, outputSchema and annotations (readOnlyHint, destructiveHint).

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_start/$AREA" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`documentation.ui`

Read Swagger documentation UI.

Route: GET /v1/_docs
Auth: None none
CLI: substrio op documentation.ui

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_docs"

`edge`

`edge.domain.check`

Say whether a hostname is attached to a tenant.

Route: GET /v1/_edge/domain
Auth: None none
CLI: substrio op edge.domain.check

Parameters

Name	In	Type	Required	Description
`domain`	query	`string`	No	the domain to check.

Response

Field	Type	Present	Description
`domain`	`string`	Always
`status`	`"attached"`	Always

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_edge/domain"

`plans`

`plans.catalog`

Read every plan sold, with no account and no person data: the Substrio plans (each with the jet plan it bundles per jet) and every featured app's (jet's) own plans, each with its limits and standalone price, each plans file as plans.get answers it. The sites build their prices from this. No key needed.

Route: GET /v1/_billing/catalog
Auth: None none
MCP tool: substrio_plans_catalog
CLI: substrio op plans.catalog

Parameters

No parameters.

Response

Field	Type	Present	Description
`substrio`	`object or null`	Always	the identity app's plans file as `plans.get` answers it: every Substrio plan, each with the jet plan it bundles per jet (apps); null when none is set.
`apps`	`object`	Always	each featured app (jet) by slug: its plans file as `plans.get` answers it, every plan with its limits and standalone price.

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_billing/catalog"

`system`

`system.async_ping`

Check liveness through the worker path.

Route: GET /sping_async
GET /v1/sping_async
Auth: None none
CLI: substrio op system.async_ping

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/sping_async"

`system.health`

Read health state.

Route: GET /health
Auth: None none
CLI: substrio op system.health

Parameters

No parameters.

Response

Field	Type	Present
`status`	`"ok"`	Always
`protocol_version`	`integer`	Always
`registry_version`	`integer`	Always
`uptime_seconds`	`integer`	Always

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/health"

`system.ping`

Check process liveness.

Route: GET /ping
Auth: None none
CLI: substrio op system.ping

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/ping"

`tenant`

`tenant.domain.attach`

Attach a domain to the app: it routes at once; a domain another app holds is refused.

Route: POST /v1/_tenant/domains
Auth: App key tenant
MCP tool: substrio_tenant_domain_attach
CLI: substrio op tenant.domain.attach

Parameters

Name	In	Type	Required	Description
`domain`	body	`string`	Yes

Response

Field	Type	Present	Description
`domain`	`string`	Always
`status`	`"attached"`	Always

Errors

A failed call answers the error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_tenant/domains" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"domain"}'

`tenant.domain.detach`

Detach one custom domain from this app by hostname.

Route: DELETE /v1/_tenant/domains/{domain}
Auth: App key tenant
MCP tool: substrio_tenant_domain_detach
CLI: substrio op tenant.domain.detach

Parameters

Name	In	Type	Required	Description
`domain`	path	`string`	Yes

Response

204 No Content: success has no body.

Errors

A failed call answers the error envelope with a typed code.

Example

curl -X DELETE "$SUBSTRIO_URL/v1/_tenant/domains/$DOMAIN" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`tenant.domain.list`

List the custom domains attached to this app.

Route: GET /v1/_tenant/domains
Auth: App key tenant
MCP tool: substrio_tenant_domain_list
CLI: substrio op tenant.domain.list

Parameters

No parameters.

Response

Field	Type	Present	Description
`domains`	`array of object`	Always

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_tenant/domains" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`tenant.key.list`

List the tenant's keys: ids, when each was made, when it expires, and whether it is current, previous (still in its overlap) or expired; never a key.

Route: GET /v1/_tenant/keys
Auth: App key tenant
MCP tool: substrio_tenant_key_list
CLI: substrio op tenant.key.list

Parameters

No parameters.

Response

Field	Type	Present	Description
`slug`	`string`	Always
`keys`	`array of object`	Always

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_tenant/keys" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`tenant.key.revoke`

End the previous key's overlap now, by key id; the current key is replaced with tenant.key.rotate.

Route: DELETE /v1/_tenant/keys/{id}
Auth: App key tenant
MCP tool: substrio_tenant_key_revoke
CLI: substrio op tenant.key.revoke

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	The key's id, as `tenant.key.list` or the call that issued the key returned it.

Response

Field	Type	Present
`slug`	`string`	Always
`key_id`	`string`	Always
`revoked`	`any`	Always
`sandboxes`	`array of object`	Always

Errors

A failed call answers the error envelope with a typed code.

Example

curl -X DELETE "$SUBSTRIO_URL/v1/_tenant/keys/$ID" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`tenant.key.rotate`

Replace the tenant's key and return the new one once; the old key stops now, or after overlap_seconds so a deploy can switch over.

Route: POST /v1/_tenant/key
Auth: App key tenant
MCP tool: substrio_tenant_key_rotate
CLI: substrio op tenant.key.rotate

Parameters

Name	In	Type	Required	Description
`overlap_seconds`	body	`integer`	No	how long the old key keeps working beside the new one, so a deploy can switch over; 0 (the default) stops it at once; at most 7 days. Minimum 0. Maximum 604800. Default `0`.
`expires_in_days`	body	`integer`	No	the new key stops working after this many days (a request with it then answers 401 KEY_EXPIRED); 0 or absent: it never expires. Minimum 0.
`requests_per_minute`	body	`integer`	No	the new key's own request limit, independent of the tenant's; 0 or absent: no limit of its own. Minimum 0.
`request_budget`	body	`integer`	No	the new key's own request budget: a lifetime total of requests with no period, which never refills and is never reset (rotate the key for a new budget); 0 or absent: no budget. Minimum 0.

Response

Field	Type	Present	Description
`slug`	`string`	Always
`key`	`string`	Always	the new key, shown once; no other call returns it.
`key_id`	`string`	Always	the new key's id (16 hex digits), not secret.
`expires`	`integer or null`	Always	epoch seconds the new key stops working; null: never.
`requests_per_minute`	`integer or null`	Always	the new key's own request limit; null: none.
`request_budget`	`integer or null`	Always	the new key's own lifetime request budget; null: none.
`previous`	`object or null`	Always	the old key while its overlap runs; null when it stopped at once.
`sandboxes`	`array of object`	Always

Errors

A failed call answers the error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_tenant/key" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`tenant.key.update`

Set or clear a key's own requests_per_minute and request_budget, by key id; a field left out keeps its current value. Rotating or revoking the key is unaffected.

Route: PATCH /v1/_tenant/keys/{id}
Auth: App key tenant
MCP tool: substrio_tenant_key_update
CLI: substrio op tenant.key.update

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	The key's id, as `tenant.key.list` or the call that issued the key returned it.
`requests_per_minute`	body	`integer`	No	sets the key's own request limit; 0 clears it; absent keeps the current value. Minimum 0.
`request_budget`	body	`integer`	No	sets the key's own request budget: a lifetime total of requests with no period, which never refills and is never reset; raising it is what gives a spent key more; 0 clears it; absent keeps the current value. Minimum 0.

Response

Field	Type	Present	Description
`slug`	`string`	Always
`key_id`	`string`	Always
`requests_per_minute`	`integer or null`	Always	the key's own request limit after the update; null: none.
`request_budget`	`integer or null`	Always	the key's own lifetime request budget after the update; null: none.

Errors

A failed call answers the error envelope with a typed code.

Example

curl -X PATCH "$SUBSTRIO_URL/v1/_tenant/keys/$ID" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`tenant.limits`

Read a tenant's quota, document and request limits and their live usage.

Route: GET /v1/_tenants/{slug}/limits
GET /v1/_limits
Auth: App key tenant
MCP tool: substrio_tenant_limits
CLI: substrio op tenant.limits

Parameters

Name	In	Type	Required	Description
`slug`	path	`string`	Yes	The app's slug, as `account.app.list` names it.

Response

Field	Type	Present
`tenant_id`	`integer`	Always
`slug`	`string`	Always
`storage_bytes_limit`	`integer`	Always
`documents_limit`	`integer`	Always
`requests_per_minute`	`integer`	Always
`max_document_size`	`integer`	Always
`max_request_bytes`	`integer`	Always
`usage`	`object`	Always

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_tenants/$SLUG/limits" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"