Account operations. Substrio docs

`account`

`account.app.create`

Create an app owned by the account. A region (a slug region.choices lists) places it there; one that is not listed is refused with REGION_UNAVAILABLE.

Route: POST /v1/_accounts/{id}/apps
Auth: Account key account
MCP tool: substrio_account_app_create
CLI: substrio op account.app.create

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`slug`	body	`string`	Yes
`region`	body	`string`	No	A slug `region.choices` lists: the region to create the app in. Refused with REGION_UNAVAILABLE when it is not listed.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_accounts/$ID/apps" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slug":"slug"}'

`account.app.delete`

Delete one of the account's apps and its data.

Route: DELETE /v1/_accounts/{id}/apps/{slug}
Auth: Account key account
MCP tool: substrio_account_app_delete
CLI: substrio op account.app.delete

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`slug`	path	`string`	Yes

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X DELETE "$SUBSTRIO_URL/v1/_accounts/$ID/apps/$SLUG" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`account.app.list`

List the apps an account owns.

Route: GET /v1/_accounts/{id}/apps
Auth: Account key account
MCP tool: substrio_account_app_list
CLI: substrio op account.app.list

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`limit`	query	`integer (0 or more)`	No	the most items per page (positive); absent returns every item.
`cursor`	query	`string`	No	resume after the previous page: its next_cursor.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_accounts/$ID/apps" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`account.app.open.get`

Read whether other accounts' keys may be scoped to one of the account's apps.

Route: GET /v1/_accounts/{id}/apps/{slug}/keys-open
Auth: Account key account
MCP tool: substrio_account_app_open_get
CLI: substrio op account.app.open.get

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`slug`	path	`string`	Yes

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_accounts/$ID/apps/$SLUG/keys-open" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`account.app.open.set`

Open one of the account's apps to other accounts' keys, or close it.

Route: PUT /v1/_accounts/{id}/apps/{slug}/keys-open
Auth: Account key account
MCP tool: substrio_account_app_open_set
CLI: substrio op account.app.open.set

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`slug`	path	`string`	Yes
`open`	body	`boolean`	Yes

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X PUT "$SUBSTRIO_URL/v1/_accounts/$ID/apps/$SLUG/keys-open" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"open":true}'

Set the order the account's apps run in: apps lists every app id of the account once (any other list is refused, INVALID_ARGUMENT naming apps). The first max_apps run; the rest are paused, keeping every byte, and their requests answer APP_OVER_PLAN until they move up, an app is deleted or the plan allows more. Answers each app in order with active, and max_apps (0: no limit).

Route: PUT /v1/_accounts/{id}/apps/order
Auth: Account key account
MCP tool: substrio_account_apps_order
CLI: substrio op account.apps.order

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`apps`	body	`array of integer`	Yes	Every app id of the account (`account.app.list`'s id), each once, in the order they run: the first max_apps run, the rest are paused (APP_OVER_PLAN).

Response

Field	Type	Present	Description
`apps`	`array of object`	Always
`max_apps`	`integer`	Always	the apps the account may run; 0: no limit.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X PUT "$SUBSTRIO_URL/v1/_accounts/$ID/apps/order" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"apps":[]}'

`account.console.link`

Mint the person you act for a one-time console sign-in, then open its url in their browser: it lands them signed in on their dashboard. Only a person mints one (an agent session for its own person, or the person signed in to the console); a key, the master key or an agent token is refused CONSOLE_LINK_NEEDS_PERSON. The link lives 5 minutes (the server's --console-link-seconds), signs in once, and a new one replaces the last; its token rides in the url's fragment, so no server receives or logs it. Answers {url, expires_at}.

Route: POST /v1/_accounts/console/link
Auth: Account key account
MCP tool: substrio_account_console_link
CLI: substrio op account.console.link

Parameters

No parameters.

Response

Field	Type	Present	Description
`url`	`string`	Always	The console address with the one-time link in its fragment (#link=...): open it in the person's browser.
`expires_at`	`integer`	Always	Unix seconds.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_accounts/console/link" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`account.delete`

Delete an account that owns no apps, with its members and keys.

Route: DELETE /v1/_accounts/{id}
Auth: Account key account
MCP tool: substrio_account_delete
CLI: substrio op account.delete

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`with_apps`	query	`boolean`	No	true deletes every app the account owns first (each app with its data, one at a time), then the account; without it an account that owns apps is refused.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X DELETE "$SUBSTRIO_URL/v1/_accounts/$ID" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`account.get`

Read an account.

Route: GET /v1/_accounts/{id}
Auth: Account key account
MCP tool: substrio_account_get
CLI: substrio op account.get

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_accounts/$ID" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`account.invite.accept`

Accept an invite as the signed-in person and join its account.

Route: POST /v1/_accounts/invites/accept
Auth: Account key account
MCP tool: substrio_account_invite_accept
CLI: substrio op account.invite.accept

Parameters

Name	In	Type	Required	Description
`token`	body	`string`	Yes	The token of the invite link.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_accounts/invites/accept" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token":"token"}'

`account.invite.create`

Invite someone to join an account with a role; the link is returned once.

Route: POST /v1/_accounts/{id}/invites
Auth: Account key account
MCP tool: substrio_account_invite_create
CLI: substrio op account.invite.create

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`role`	body	`"developer" \| "admin" \| "owner"`	No
`email`	body	`string`	No	Only this person, signed in with this verified email, may accept.
`expires_in_seconds`	body	`integer`	No	How long the invite works (default account_invite_seconds, at most account_invite_max_seconds). Minimum 1.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_accounts/$ID/invites" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`account.invite.list`

List an account's open and expired invites.

Route: GET /v1/_accounts/{id}/invites
Auth: Account key account
MCP tool: substrio_account_invite_list
CLI: substrio op account.invite.list

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_accounts/$ID/invites" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`account.invite.revoke`

Revoke an invite; its link stops working at once.

Route: DELETE /v1/_accounts/{id}/invites/{invite_id}
Auth: Account key account
MCP tool: substrio_account_invite_revoke
CLI: substrio op account.invite.revoke

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`invite_id`	path	`string`	Yes

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X DELETE "$SUBSTRIO_URL/v1/_accounts/$ID/invites/$INVITE_ID" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`account.key.create`

Create an account key (live or test); the secret is returned once.

Route: POST /v1/_accounts/{id}/keys
Auth: Account key account
MCP tool: substrio_account_key_create
CLI: substrio op account.key.create

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`name`	body	`string`	Yes
`mode`	body	`"live" \| "test"`	No
`apps`	body	`array of string`	No	Scope the key to these apps of the account (slugs); it then works only there, as an app customer.
`requests_per_minute`	body	`integer`	No	the key's own request limit, independent of the app's; 0 or absent: no limit of its own. Minimum 0.
`request_budget`	body	`integer`	No	the key's own request budget, a lifetime total of requests with no period, which never refills and is never reset; 0 or absent: no budget. Minimum 0.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_accounts/$ID/keys" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"name"}'

`account.key.list`

List an account's keys.

Route: GET /v1/_accounts/{id}/keys
Auth: Account key account
MCP tool: substrio_account_key_list
CLI: substrio op account.key.list

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`limit`	query	`integer (0 or more)`	No	the most items per page (positive); absent returns every item.
`cursor`	query	`string`	No	resume after the previous page: its next_cursor.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_accounts/$ID/keys" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`account.key.publish`

Create a publishable account key, safe in a web page's source: it answers only a browser request from one of its origins, at its apps; the secret is returned once.

Route: POST /v1/_accounts/{id}/publishable-keys
Auth: Account key account
MCP tool: substrio_account_key_publish
CLI: substrio op account.key.publish

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`name`	body	`string`	Yes
`mode`	body	`"live" \| "test"`	No
`apps`	body	`array of string`	Yes	The apps of the account (slugs) the key works at, as an app customer.
`origins`	body	`array of string`	Yes	The only web origins the key answers, exactly as a browser sends its Origin header (https://host or https://host:port, lowercase, no path; http://localhost or http://127.0.0.1 for development).
`requests_per_minute`	body	`integer`	No	the key's own request limit, independent of the app's; 0 or absent: no limit of its own. Minimum 0.
`request_budget`	body	`integer`	No	the key's own request budget, a lifetime total of requests with no period, which never refills and is never reset; 0 or absent: no budget. Minimum 0.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_accounts/$ID/publishable-keys" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"name","apps":[],"origins":[]}'

`account.key.revoke`

Revoke an account key; it stops working at once.

Route: DELETE /v1/_accounts/{id}/keys/{key_id}
Auth: Account key account
MCP tool: substrio_account_key_revoke
CLI: substrio op account.key.revoke

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`key_id`	path	`string`	Yes

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X DELETE "$SUBSTRIO_URL/v1/_accounts/$ID/keys/$KEY_ID" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`account.key.update`

Set or clear an account key's own requests_per_minute and request_budget, by key id; a field left out keeps its current value.

Route: PATCH /v1/_accounts/{id}/keys/{key_id}
Auth: Account key account
MCP tool: substrio_account_key_update
CLI: substrio op account.key.update

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`key_id`	path	`string`	Yes
`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; 0 clears it; absent keeps the current value. Minimum 0.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X PATCH "$SUBSTRIO_URL/v1/_accounts/$ID/keys/$KEY_ID" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`account.list`

List the accounts the caller belongs to (every account for the system key).

Route: GET /v1/_accounts
Auth: Account key account
MCP tool: substrio_account_list
CLI: substrio op account.list

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_accounts" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`account.member.list`

List an account's members and their roles.

Route: GET /v1/_accounts/{id}/members
Auth: Account key account
MCP tool: substrio_account_member_list
CLI: substrio op account.member.list

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_accounts/$ID/members" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`account.member.remove`

Remove a person from an account.

Route: DELETE /v1/_accounts/{id}/members/{user_id}
Auth: Account key account
MCP tool: substrio_account_member_remove
CLI: substrio op account.member.remove

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`user_id`	path	`integer`	Yes	Minimum 1.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X DELETE "$SUBSTRIO_URL/v1/_accounts/$ID/members/$USER_ID" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`account.member.set`

Add a person to an account, or change their role.

Route: PUT /v1/_accounts/{id}/members/{user_id}
Auth: Account key account
MCP tool: substrio_account_member_set
CLI: substrio op account.member.set

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`user_id`	path	`integer`	Yes	Minimum 1.
`role`	body	`"developer" \| "admin" \| "owner"`	No

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X PUT "$SUBSTRIO_URL/v1/_accounts/$ID/members/$USER_ID" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`account.mfa.set`

Require every member of an account to sign in with 2FA, or stop requiring it.

Route: PUT /v1/_accounts/{id}/mfa
Auth: Account key account
MCP tool: substrio_account_mfa_set
CLI: substrio op account.mfa.set

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`required`	body	`boolean`	Yes	Every member signs in with 2FA; one without it enrols at sign-in.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X PUT "$SUBSTRIO_URL/v1/_accounts/$ID/mfa" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"required":true}'

`account.overview`

Read every app of the account with slug, tenant_id, suspended, live version and calls (invocations, status classes, p95_under_ms, from memory); stored_bytes and documents are present only when open is true (the app's database was already open: never opened here to total it), then the account's totals (apps, suspended, open, calls, stored_bytes, documents) across every app.

Route: GET /v1/_accounts/{id}/overview
Auth: Account key account
MCP tool: substrio_account_overview
CLI: substrio op account.overview

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.

Response

Field	Type	Present	Description
`apps`	`array of object`	Always
`totals`	`object`	Always

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_accounts/$ID/overview" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`account.plan.change`

Move the account to a free plan at once when its usage fits (else refused with the limit and by how much). The Substrio plan's items leave the account's subscription first (prorated); the subscription ends when they were all it paid for. A paid plan is bought through account.plan.checkout.

Route: PUT /v1/_accounts/{id}/plan
Auth: Account key account
MCP tool: substrio_account_plan_change
CLI: substrio op account.plan.change

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`plan`	body	`string`	Yes	a plan id from `account.plan.summary`.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X PUT "$SUBSTRIO_URL/v1/_accounts/$ID/plan" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan":"plan"}'

`account.plan.checkout`

Make a cart of a paid Substrio plan and return its checkout_url (and cart) to hand to the person, who pays on that page (billing.checkout.start). Nothing is sent to the provider and nothing changes until the payment is confirmed; the agent never handles payment details.

Route: POST /v1/_accounts/{id}/plan/checkout
Auth: Account key account
MCP tool: substrio_account_plan_checkout
CLI: substrio op account.plan.checkout

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`plan`	body	`string`	Yes	a plan id from `account.plan.summary`.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_accounts/$ID/plan/checkout" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan":"plan"}'

`account.plan.summary`

Read what the account's plan allows beside what it uses, and every plan with what it adds and its price. An agent explains the plans and the upgrade from this alone.

Route: GET /v1/_accounts/{id}/plan
Auth: Account key account
MCP tool: substrio_account_plan_summary
CLI: substrio op account.plan.summary

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_accounts/$ID/plan" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`account.storage`

Read what each app of the account holds on disk (disk_bytes: its database, files, logs, backups, code and the rest, as of its last fold, open or not), the account's total (its apps and their sandboxes, the figure its space is held against) and the space in force (null while none). Supersedes account.overview's stored_bytes, which counts only open apps' document bytes.

Route: GET /v1/_accounts/{id}/storage
Auth: Account key account
MCP tool: substrio_account_storage
CLI: substrio op account.storage

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.

Response

Field	Type	Present	Description
`apps`	`array of object`	Always
`total_bytes`	`integer`	Always	what the account's apps hold on disk, their sandboxes included: the figure its space is held against.
`space_bytes`	`integer or null`	Always	the account's space in force; null while it has none.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_accounts/$ID/storage" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`account.update`

Rename an account; the system key also sets its services, space and max_apps, and suspends it.

Route: PATCH /v1/_accounts/{id}
Auth: Account key account
MCP tool: substrio_account_update
CLI: substrio op account.update

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`name`	body	`string`	No
`services`	body	`integer`	No	System key only. Minimum 0.
`suspended`	body	`boolean`	No	System key only.
`space_bytes`	body	`integer or null`	No	System key only: the bytes the account's apps may hold together, records and files; 0 is unlimited, null returns the account to the server-wide account_space_bytes (1 GiB by default). The account makes apps while they fit. Minimum 0.
`max_apps`	body	`integer or null`	No	System key only: the apps the account may own, beside its space; 0 is unlimited, null returns the account to the server-wide account_max_apps (unlimited by default). Minimum 0. Maximum 4294967295.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X PATCH "$SUBSTRIO_URL/v1/_accounts/$ID" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`account.usage`

Read the account's plan and usage counters at each app it has a plan or usage at.

Route: GET /v1/_accounts/{id}/usage
Auth: Account key account
MCP tool: substrio_account_usage
CLI: substrio op account.usage

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_accounts/$ID/usage" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`account.usage.cpu`

Read the CPU the account's apps used in each of the last 60 finished minutes, the hour's mean, the last 15 minutes' mean, the peak minute, the plan's CPU slices and the hour against them (used, of_share), the requests and calls held back while the server was saturated (holds) and each app's minutes and holds, each in CPU slices (1 is the Free plan's CPU under load; Standard holds 4). Explains how close the account runs to its plan's share and who waited for it.

Route: GET /v1/_accounts/{id}/usage/cpu
Auth: Account key account
MCP tool: substrio_account_usage_cpu
CLI: substrio op account.usage.cpu

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.

Response

Field	Type	Present	Description
`account`	`integer`	Always
`minutes`	`array of object`	Always	the last 60 finished minutes, oldest first; a minute with no CPU is 0.
`mean_used`	`number`	Always	the hour's mean, in CPU slices.
`recent_used`	`number`	Always	the mean of its last 15 minutes, the trend against the hour.
`peak`	`object or null`	Always	the busiest minute (the latest of equal ones); null in an hour with no CPU.
`share`	`number or null`	Always	the CPU slices of the account's plan, the Free plan's 1 (the identity app's plans file, cpu_share); null when the plan sets none or no plans are set.
`plan`	`string or null`	Always	the account's plan id; null when no plans are set.
`used`	`number`	Always	the hour's mean in CPU slices (mean_used).
`of_share`	`number or null`	Always	used over share: 1 is the plan's whole slices on average; null when share is.
`holds`	`integer`	Always	the hour's requests and function calls queued behind other accounts' work while the server's CPU was saturated (CPU slices are a priority, never a cap); 0 on a server never saturated.
`apps`	`array of object`	Always	each of the account's apps with CPU or holds this hour.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_accounts/$ID/usage/cpu" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`agent`

`agent.alert.list`

List the account's agent alerts (a spent key used again revokes its session and leaves one), newest first.

Route: GET /v1/_accounts/{id}/agent/alerts
Auth: Account key account
MCP tool: substrio_agent_alert_list
CLI: substrio op agent.alert.list

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_accounts/$ID/agent/alerts" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`agent.enroll.exchange`

Exchange a one-time enrollment code (substrio_ae_...) for an agent session acting as the member who made it: a bearer one unless a kind is named or a public key is sent (key-bound). Answers the credential once and next, what to do with it; the code is spent. Over MCP it is the tool substrio_connect on any /mcp, with no credential.

Route: POST /v1/_agent/exchange
Auth: App key or user session; your security rules apply none
CLI: substrio op agent.enroll.exchange

Parameters

Name	In	Type	Required	Description
`kind`	body	`"key_bound" \| "ratcheted" \| "bearer"`	No	bearer: one static secret (substrio_ab_...), short-lived (agent_bearer_max_seconds), for an agent that can hold only one string; absent: key_bound with a public_key, else bearer. ratcheted: a key that changes on every request.
`code`	body	`string`	Yes	The one-time enrollment code (substrio_ae_...).
`public_key`	body	`string`	No	Makes a key-bound session: the agent's public key, base64url (32 bytes Ed25519, or the 65-byte uncompressed P-256 point); absent: a bearer session, or the kind named.
`algorithm`	body	`"ed25519" \| "p256"`	No	The public key's algorithm (default ed25519).
`durable`	body	`boolean`	No	kind ratcheted only: every key rotation is made durable before the reply leaves.
`key_count`	body	`integer`	No	kind ratcheted only: how many keys to start with, at most agent_ratchet_window (default 1). Minimum 1.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_agent/exchange" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code":"code"}'

`agent.login.begin`

Start an agent sign-in with no key: a sign-in request for the person's email, with no mail sent. Answers {intent_id, intent_secret (shown once), match_code, url, expires_at}. Show the person the match_code and have them open url: the page shows the same match code, runs a bot check, and only then mails them a code. Then agent.login.finish with the code they give you. Limited per address, per network and in all (RATE_LIMIT_EXCEEDED with Retry-After).

Route: POST /v1/_agent/login/begin
Auth: App key or user session; your security rules apply none
CLI: substrio op agent.login.begin

Parameters

Name	In	Type	Required	Description
`email`	body	`string`	Yes	The person's email; no mail is sent yet.
`agent_name`	body	`string`	No	What the person will see the agent called (default agent).
`loopback_port`	body	`integer`	No	The CLI's listener on 127.0.0.1: once the person types the code in the page, the page sends the browser there with a one-time grant (RFC 8252). Minimum 1024. Maximum 65535.

Response

Field	Type	Present	Description
`intent_id`	`string`	Always
`intent_secret`	`string`	Always	Shown once; finish sends it back.
`match_code`	`string`	Always	Shown to the person in the terminal and on the page, so they can tell the two belong together.
`url`	`string`	Always	The page the person opens; it carries only the intent id.
`dashboard_url`	`string`	Always	Where the CLI's listener sends the signed-in browser.
`expires_at`	`integer`	Always	Unix seconds.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_agent/login/begin" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"email"}'

`agent.login.challenge`

For the sign-in page: the Cloudflare Turnstile token the person's check gave. The platform verifies it once with Cloudflare, then mails the code to the request's email (once a request). Answers {accepted, expires_at}; TURNSTILE_FAILED, TURNSTILE_UNREACHABLE, LOGIN_INTENT_UNKNOWN, LOGIN_INTENT_EXPIRED, RATE_LIMIT_EXCEEDED.

Route: POST /v1/_agent/login/challenge
Auth: App key or user session; your security rules apply none
CLI: substrio op agent.login.challenge

Parameters

Name	In	Type	Required	Description
`intent_id`	body	`string`	Yes	The request's id, from the link.
`turnstile_token`	body	`string`	Yes	The token the page's Cloudflare Turnstile check gave.

Response

Field	Type	Present	Description
`accepted`	`any`	Always
`expires_at`	`integer`	Always	When the mailed code stops working, Unix seconds.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_agent/login/challenge" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"intent_id":"intent_id","turnstile_token":"turnstile_token"}'

`agent.login.finish`

Finish an agent sign-in. The agent sends the request's id and secret with the code the person gives it, or with the grant its loopback listener received; the sign-in page sends the id and the code alone, which signs the browser in and answers the loopback grant. The mailed code works once in the browser and once for the agent; a third use is LOGIN_CODE_SPENT. The agent's answer is agent.signup.finish's, with a refreshable session: session.credentials holds the access secret, then the refresh secret (substrio_ar_...), shown once. Refresh before session.secret_expires_at with agent.login.refresh. The person sees the session under the agent's name and can end it at once. Refusals: LOGIN_INTENT_UNKNOWN, LOGIN_INTENT_EXPIRED, LOGIN_INTENT_NOT_CHALLENGED, LOGIN_CODE_SPENT, LOGIN_GRANT_INVALID, LOGIN_GRANT_EXPIRED, then agent.signup.finish's reasons.

Route: POST /v1/_agent/login/finish
Auth: App key or user session; your security rules apply none
CLI: substrio op agent.login.finish

Parameters

Name	In	Type	Required	Description
`intent_id`	body	`string`	Yes	The request's id, from `agent.login.begin`.
`intent_secret`	body	`string`	No	The request's secret, from `agent.login.begin`'s answer; the agent sends it, the person's browser does not.
`code`	body	`string`	No	The code mailed to the person after they passed the check. It works once in the browser and once for the agent.
`grant`	body	`string`	No	The CLI's loopback exchange: the one-time grant the browser brought to the CLI's listener, with intent_secret and no code.
`account_id`	body	`integer`	No	One of the person's accounts to act in; absent: their personal account (one is made for a person with none). Minimum 1.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_agent/login/finish" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"intent_id":"intent_id"}'

`agent.login.refresh`

Swap a signed-in agent's refresh secret for a new access secret and a new refresh secret; the old access secret stops at once. Sending the last refresh secret again answers the same pair (a lost answer). LOGIN_REFRESH_REFUSED when the session was revoked or the secret is not its own.

Route: POST /v1/_agent/login/refresh
Auth: App key or user session; your security rules apply none
CLI: substrio op agent.login.refresh

Parameters

Name	In	Type	Required	Description
`refresh_token`	body	`string`	Yes	The session's refresh secret (substrio_ar_...), from `agent.login.finish` or the last refresh.

Response

Field	Type	Present	Description
`access_token`	`string`	Always
`refresh_token`	`string`	Always	Replaces the one sent; keep it.
`access_expires_at`	`integer`	Always
`refresh_expires_at`	`integer`	Always

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_agent/login/refresh" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"refresh_token"}'

`agent.login.show`

For the sign-in page: what a sign-in request shows its person (the email masked, the agent's name, the match code, the Turnstile site key, whether the check passed). LOGIN_INTENT_UNKNOWN or LOGIN_INTENT_EXPIRED when there is no live request.

Route: POST /v1/_agent/login/show
Auth: App key or user session; your security rules apply none
CLI: substrio op agent.login.show

Parameters

Name	In	Type	Required	Description
`intent_id`	body	`string`	Yes	The request's id, from `agent.login.begin` (the link's intent parameter).

Response

Field	Type	Present	Description
`email`	`string`	Always	Masked, as p***@example.com.
`agent_name`	`string`	Always
`match_code`	`string`	Always
`site_key`	`string`	Always	The Turnstile site key; empty when the platform runs no check.
`challenged`	`boolean`	Always
`browser_used`	`boolean`	Always
`loopback_port`	`integer`	Always	The CLI's listener on 127.0.0.1; 0: none.
`dashboard_url`	`string`	Always
`expires_at`	`integer`	Always

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_agent/login/show" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"intent_id":"intent_id"}'

`agent.session.delegate`

An agent session makes a narrower child session for a sub-agent: the child's capabilities and apps are within the caller's, it ends no later than the caller, and it dies with the caller. Returns the child's credentials once.

Route: POST /v1/_accounts/{id}/agent/delegations
Auth: Account key account
MCP tool: substrio_agent_session_delegate
CLI: substrio op agent.session.delegate

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	The account the calling session acts in. Minimum 1.
`kind`	body	`"key_bound" \| "ratcheted" \| "bearer"`	No	bearer: one static secret (substrio_ab_...), short-lived (agent_bearer_max_seconds), for an agent that can hold only one string; absent: key_bound with a public_key, else bearer. ratcheted: a key that changes on every request.
`name`	body	`string`	Yes	What the sub-agent is called.
`apps`	body	`array of string`	No	Narrow the child to these apps (slugs, each reachable by the caller); absent: the caller's apps.
`capabilities`	body	`array of string`	No	Narrow the child to these capabilities (each held by the caller); absent: the caller's.
`expires_in_seconds`	body	`integer`	No	How long the child lives, never past the caller's own end (default agent_max_seconds). Minimum 1.
`requests_per_minute`	body	`integer`	No	A rolling limit on the child's requests (the caller's limits apply too) per minute; absent: none. Minimum 1.
`request_budget`	body	`integer`	No	The most requests the session makes in its life; absent: none. Minimum 1.
`public_key`	body	`string`	No	Makes a key-bound child: the sub-agent's public key, base64url; absent: a bearer child, or the kind named.
`algorithm`	body	`"ed25519" \| "p256"`	No	The public key's algorithm (default ed25519).
`durable`	body	`boolean`	No	kind ratcheted only: every key rotation is made durable before the reply leaves.
`key_count`	body	`integer`	No	kind ratcheted only: how many keys to start with, at most agent_ratchet_window (default 1). Minimum 1.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_accounts/$ID/agent/delegations" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"name"}'

`agent.session.list`

List the account's live agent sessions (an ended one leaves the list; its log is still read by id), oldest first, a page at a time (limit, cursor; next_cursor), or only those reaching one app (app); never a key.

Route: GET /v1/_accounts/{id}/agent/sessions
Auth: Account key account
MCP tool: substrio_agent_session_list
CLI: substrio op agent.session.list

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`app`	query	`string`	No	only this app's rows: its slug, as `account.app.list` names it; a session whose grant names no app reaches every app.
`limit`	query	`integer (0 or more)`	No	the most items per page (positive); absent returns every item.
`cursor`	query	`string`	No	resume after the previous page: its next_cursor.
`limit`	query	`integer`	No	Rows a page: 100 by default, capped at 1000. Minimum 1.
`cursor`	query	`string`	No	The next_cursor of the page before: the walk resumes past it.
`app`	query	`string`	No	Only the rows that reach this app (its slug): those naming it and those naming no app.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_accounts/$ID/agent/sessions" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`agent.session.log`

List the requests an agent session made, oldest first, each with its operation, outcome (ran, refused, approval asked, approved, denied, spent), status, app and time; pages by limit and cursor (a member sees their own agents, an admin or owner the account's). Kept for agent_log_retention_seconds.

Route: GET /v1/_accounts/{id}/agent/sessions/{session_id}/log
Auth: Account key account
MCP tool: substrio_agent_session_log
CLI: substrio op agent.session.log

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`session_id`	path	`string`	Yes	The session's id, as `agent.session.list` returned it.
`limit`	query	`integer (0 or more)`	No	the most items per page (positive); absent returns every item.
`cursor`	query	`string`	No	resume after the previous page: its next_cursor.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_accounts/$ID/agent/sessions/$SESSION_ID/log" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`agent.session.revoke`

Revoke one agent session (and every session it made); its keys fail at once.

Route: DELETE /v1/_accounts/{id}/agent/sessions/{session_id}
Auth: Account key account
MCP tool: substrio_agent_session_revoke
CLI: substrio op agent.session.revoke

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`session_id`	path	`string`	Yes	The session's id, as `agent.session.list` returned it.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X DELETE "$SUBSTRIO_URL/v1/_accounts/$ID/agent/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`agent.session.revoke_all`

Revoke every agent session of the account; their keys fail at once.

Route: DELETE /v1/_accounts/{id}/agent/sessions
Auth: Account key account
MCP tool: substrio_agent_session_revoke_all
CLI: substrio op agent.session.revoke_all

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X DELETE "$SUBSTRIO_URL/v1/_accounts/$ID/agent/sessions" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`agent.signup.finish`

Prove the email with the mailed code and get an agent session acting as that person in account_id, else their personal account (one is made for a person with none): the person is made when nobody holds the address. Answers {account_id, account_created, person_created, user_id, account, app_defaults, session (credentials, shown once), next_steps}; a refusal names its reason: a code that proves nothing as auth.email.code_verify (MISSING, USED, EXPIRED, TOO_MANY_ATTEMPTS, WRONG and attempts_remaining), then MFA_REQUIRED, ACCOUNT_REQUIRED (with account_ids), NOT_MEMBER, PERSON_DISABLED, ACCOUNT_SUSPENDED, ACCOUNT_LIMIT.

Route: POST /v1/_agent/signup/finish
Auth: App key or user session; your security rules apply none
CLI: substrio op agent.signup.finish

Parameters

Name	In	Type	Required	Description
`email`	body	`string`	Yes	The address `agent.signup.start` mailed the code to.
`code`	body	`string`	Yes	The code from that mail.
`account_id`	body	`integer`	No	One of the person's accounts to act in; absent: their personal account (one is made for a person with none; a person with accounts but no personal one is refused ACCOUNT_REQUIRED with account_ids). Minimum 1.
`name`	body	`string`	No	What the person will see the agent called (default agent).
`public_key`	body	`string`	No	Makes a key-bound session: the agent's public key, base64url (32 bytes Ed25519, or the 65-byte uncompressed P-256 point); absent: a ratcheted session.
`algorithm`	body	`"ed25519" \| "p256"`	No	The public key's algorithm (default ed25519).
`durable`	body	`boolean`	No	Ratcheted: every key rotation is made durable before the reply leaves.
`key_count`	body	`integer`	No	Ratcheted: how many keys to start with, at most agent_ratchet_window (default 1). Minimum 1.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_agent/signup/finish" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"email","code":"code"}'

`agent.signup.start`

Start here with no key: mail a sign-up or sign-in code to the person's email (the identity app's auth.email.code_request). Answers {accepted, expires_at} whether or not anyone holds the address; then agent.signup.finish with the code.

Route: POST /v1/_agent/signup/start
Auth: App key or user session; your security rules apply none
CLI: substrio op agent.signup.start

Parameters

Name	In	Type	Required	Description
`email`	body	`string`	Yes
`turnstile_token`	body	`string`	No	On the platform host's identity app: the token of the Cloudflare Turnstile check the page showed (`auth.turnstile` names its site key); refused TURNSTILE_REQUIRED without one while the platform sets turnstile_secret.

Response

Field	Type	Present	Description
`accepted`	`any`	Always
`expires_at`	`integer`	Always	Unix seconds.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_agent/signup/start" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"email"}'

`auth`

`auth.client.create`

Let one of the account's apps sign people in through the identity app, sending them back only to these redirect URIs (exact match).

Route: POST /v1/_accounts/{id}/clients
Auth: Account key account
MCP tool: substrio_auth_client_create
CLI: substrio op auth.client.create

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`slug`	body	`string`	Yes	The app, and its client_id.
`redirect_uris`	body	`array of string`	Yes	Where signed-in people may be sent back to, matched exactly: https, http to the loopback, or an app's own scheme.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_accounts/$ID/clients" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slug":"slug","redirect_uris":[]}'

`auth.client.delete`

Stop an app signing people in through the identity app.

Route: DELETE /v1/_accounts/{id}/clients/{slug}
Auth: Account key account
MCP tool: substrio_auth_client_delete
CLI: substrio op auth.client.delete

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`slug`	path	`string`	Yes

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X DELETE "$SUBSTRIO_URL/v1/_accounts/$ID/clients/$SLUG" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`auth.client.list`

List the account's apps that sign people in through the identity app, with their redirect URIs.

Route: GET /v1/_accounts/{id}/clients
Auth: Account key account
MCP tool: substrio_auth_client_list
CLI: substrio op auth.client.list

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_accounts/$ID/clients" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`auth.client.redirect_uris.set`

Replace the redirect URIs an app's sign-ins may return to.

Route: PUT /v1/_accounts/{id}/clients/{slug}
Auth: Account key account
MCP tool: substrio_auth_client_redirect_uris_set
CLI: substrio op auth.client.redirect_uris.set

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`slug`	path	`string`	Yes	The app, and its client_id.
`redirect_uris`	body	`array of string`	Yes	Where signed-in people may be sent back to, matched exactly: https, http to the loopback, or an app's own scheme.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X PUT "$SUBSTRIO_URL/v1/_accounts/$ID/clients/$SLUG" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"redirect_uris":[]}'

`billing`

`billing.cart.create`

Make a cart of plans (a featured app's a la carte, or a Substrio plan) and funds for the account's credit. The answer prices it from the plans files, offers the Substrio plan that covers its apps for less, and gives checkout_url: the page the person pays on. Nothing is charged.

Route: POST /v1/_accounts/{id}/billing/carts
Auth: Account key account
MCP tool: substrio_billing_cart_create
CLI: substrio op billing.cart.create

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`items`	body	`array of object`	No
`funds`	body	`integer`	No	Monetary overage credit, in minor units, 500 to 1000000. Minimum 0.
`space_blocks`	body	`integer`	No	Minimum 0. Maximum 100000.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_accounts/$ID/billing/carts" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`billing.cart.get`

Read one of the account's carts, priced as the plans are now, with its state (open, paying, paid) and checkout_url.

Route: GET /v1/_accounts/{id}/billing/carts/{cart}
Auth: Account key account
MCP tool: substrio_billing_cart_get
CLI: substrio op billing.cart.get

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`cart`	path	`string`	Yes	the cart's id, as `billing.cart.create` answered it.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_accounts/$ID/billing/carts/$CART" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`billing.cart.update`

Replace what an open cart buys (its items and funds), for example to take the Substrio plan it offers; a cart whose checkout started no longer changes.

Route: PUT /v1/_accounts/{id}/billing/carts/{cart}
Auth: Account key account
MCP tool: substrio_billing_cart_update
CLI: substrio op billing.cart.update

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`cart`	path	`string`	Yes
`items`	body	`array of object`	No
`funds`	body	`integer`	No	Minimum 0.
`space_blocks`	body	`integer`	No	Minimum 0. Maximum 100000.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X PUT "$SUBSTRIO_URL/v1/_accounts/$ID/billing/carts/$CART" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`billing.catalog`

What the account can buy: the Substrio plans (each with the featured apps it bundles), every featured app's own plans a la carte with prices, the plan the account is on at each, and whether checkout is ready.

Route: GET /v1/_accounts/{id}/billing/catalog
Auth: Account key account
MCP tool: substrio_billing_catalog
CLI: substrio op billing.catalog

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_accounts/$ID/billing/catalog" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`billing.checkout.confirm`

After the person paid on the page: reads the provider's word for the cart's payment and applies the cart once (its plans put on, its funds added to credit); the webhook applies it too, whichever comes first. Answers the cart, state paid.

Route: POST /v1/_accounts/{id}/billing/carts/{cart}/confirm
Auth: Account key account
MCP tool: substrio_billing_checkout_confirm
CLI: substrio op billing.checkout.confirm

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`cart`	path	`string`	Yes	the cart's id, as `billing.cart.create` answered it.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_accounts/$ID/billing/carts/$CART/confirm" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`billing.credit.get`

Read the account's credit: the funds it added, in the minor unit, and how many payments made it.

Route: GET /v1/_accounts/{id}/billing/credit
Auth: Account key account
MCP tool: substrio_billing_credit_get
CLI: substrio op billing.credit.get

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_accounts/$ID/billing/credit" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`billing.payout.get`

Read an app's connected payout account and whether transfers are active.

Route: GET /v1/_accounts/{id}/apps/{slug}/payouts
Auth: Account key account
MCP tool: substrio_billing_payout_get
CLI: substrio op billing.payout.get

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`slug`	path	`string`	Yes

Response

Field	Type	Present
`account`	`string or null`	When set
`ready`	`boolean`	When set
`url`	`string`	When set
`client_secret`	`string`	When set

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_accounts/$ID/apps/$SLUG/payouts" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`billing.person_cart.create`

Make a cart of plans that are the person's own, paid by the account: they hold them at every app wherever they sign in, apart from the account's (subscriptions.mine lists them). The plans, the offer and checkout_url as billing.cart.create gives them; the subject is the person whose own session starts the checkout. No space_blocks: the add-on is the account's.

Route: POST /v1/_accounts/{id}/billing/person-carts
Auth: Account key account
MCP tool: substrio_billing_person_cart_create
CLI: substrio op billing.person_cart.create

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	The account that pays. Minimum 1.
`items`	body	`array of object`	No
`funds`	body	`integer`	No	Minimum 0.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_accounts/$ID/billing/person-carts" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`billing.subscription.cancel`

End the account's subscription, at the end of the period paid for (the default) or now. When it ends, the Substrio plan and every featured app it paid for go back to their free plans, still enabled.

Route: POST /v1/_accounts/{id}/billing/subscription/cancel
Auth: Account key account
MCP tool: substrio_billing_subscription_cancel
CLI: substrio op billing.subscription.cancel

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`at_period_end`	body	`boolean`	No	true (the default): the subscription runs to the end of the period paid for; false: it ends now.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_accounts/$ID/billing/subscription/cancel" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`dashboard`

`dashboard.get`

Read the dashboard an app declares, the file its live version shipped (nav items and their panels, canonical), for the console to draw. The app is one of the account's own or a featured app the account has enabled; any other answers TENANT_NOT_FOUND. An app that declares none answers an empty nav. With version (a number or id), that version's dashboard instead, checked against its own routes as a push's is: what the console will draw once it goes live (an app of the account's own).

Route: GET /v1/_accounts/{id}/apps/{slug}/dashboard
Auth: Account key account
MCP tool: substrio_dashboard_get
CLI: substrio op dashboard.get

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`slug`	path	`string`	Yes
`version`	query	`string`	No	the dashboard of this version instead of the live one, by number or id (64 hex digits), checked against that version's own routes as `version.check` checks a push's; an app of the caller's own account only.

Response

Field	Type	Present	Description
`nav`	`array of object`	Always	navigation items in the console in order, each {id, title, icon, panels, role?, params?}; empty when the app declares no dashboard.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_accounts/$ID/apps/$SLUG/dashboard" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`featured`

`featured.disable`

Deprecated: every account has every jet, always on, so it is refused FEATURED_ALWAYS_ON. A key stops with account.key.revoke; an app's keys go with the app.

Route: DELETE /v1/_accounts/{id}/featured/{jet}
Auth: Account key account
MCP tool: substrio_featured_disable
CLI: substrio op featured.disable

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`jet`	path	`string`	Yes	the featured app's slug (`featured.list` names it app).

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X DELETE "$SUBSTRIO_URL/v1/_accounts/$ID/featured/$JET" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`featured.enable`

Deprecated: every account has every jet, always on. Answers the jet's entry as featured.list writes it and changes nothing.

Route: PUT /v1/_accounts/{id}/featured/{jet}
Auth: Account key account
MCP tool: substrio_featured_enable
CLI: substrio op featured.enable

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`jet`	path	`string`	Yes	the featured app's slug (`featured.list` names it app).

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X PUT "$SUBSTRIO_URL/v1/_accounts/$ID/featured/$JET" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`featured.key.create`

Deprecated: a jet key belongs to one of the account's apps, so it is refused JET_KEY_NEEDS_APP; jet.key.create makes it.

Route: POST /v1/_accounts/{id}/featured/{jet}/keys
Auth: Account key account
MCP tool: substrio_featured_key_create
CLI: substrio op featured.key.create

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`jet`	path	`string`	Yes	the featured app the key is scoped to; the account must have it enabled.
`name`	body	`string`	Yes
`mode`	body	`"live" \| "test"`	No
`requests_per_minute`	body	`integer`	No	the key's own request limit; 0 or absent: no limit of its own. Minimum 0.
`request_budget`	body	`integer`	No	the key's own lifetime request budget; 0 or absent: none. Minimum 0.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_accounts/$ID/featured/$JET/keys" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"name"}'

`featured.list`

List the featured apps (the jets: MapJet, SendJet, AuthJet and every later one) for the account: what each does, the plan it is metered against and the account's use this day and month (every app of the account summed) against that plan's limits. Every account has every jet: there is nothing to enable.

Route: GET /v1/_accounts/{id}/featured
Auth: Account key account
MCP tool: substrio_featured_list
CLI: substrio op featured.list

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_accounts/$ID/featured" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`jet`

`jet.key.create`

Make a key of one of the account's apps scoped to one jet; the secret is returned once. The jet sees each call as that app (request.auth.app) and meters it to the account's plan, the app's own use counted beside; removing the app revokes the key. With origins the key is publishable (safe in a page's source, answering only those origins). An unscoped account key may make one; a scoped key may not.

Route: POST /v1/_accounts/{id}/apps/{slug}/jets/{jet}/keys
Auth: Account key account
MCP tool: substrio_jet_key_create
CLI: substrio op jet.key.create

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`slug`	path	`string`	Yes	the account's app the key belongs to: the jet sees it as request.auth.app, and removing the app revokes the key.
`jet`	path	`string`	Yes	the featured app (jet) the key is scoped to (`jet.list` and `featured.list` name each as app).
`name`	body	`string`	Yes
`mode`	body	`"live" \| "test"`	No
`origins`	body	`array of string`	No	makes the key publishable: it answers only a request from one of these origins (https://host[:port]), so it is safe in a page's source.
`requests_per_minute`	body	`integer`	No	the key's own request limit; 0 or absent: no limit of its own. Minimum 0.
`request_budget`	body	`integer`	No	the key's own lifetime request budget; 0 or absent: none. Minimum 0.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_accounts/$ID/apps/$SLUG/jets/$JET/keys" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"name"}'

`jet.list`

List the jets of one of the account's apps: each jet's menu in the app's dashboard (app_nav: its pages, each a list, form or detail over the jet's own routes), the account's plan and use there (every app summed: the limit is the account's) and this app's own use this day and month.

Route: GET /v1/_accounts/{id}/apps/{slug}/jets
Auth: Account key account
MCP tool: substrio_jet_list
CLI: substrio op jet.list

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`slug`	path	`string`	Yes	one of the account's apps: the jets it has, each with its menu, the account's plan and use and this app's own use.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_accounts/$ID/apps/$SLUG/jets" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`jet.start`

Start using a jet in one call: the app named, a new app, or the account's one app, and a key of that app scoped to the jet. The answer holds the app, its url, the jet's endpoint, the key once, and what to do next. An account with several apps is told to name one (APP_REQUIRED, with their slugs in apps).

Route: POST /v1/_accounts/{id}/jets/{jet}/start
Auth: Account key account
MCP tool: substrio_jet_start
CLI: substrio op jet.start

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`jet`	path	`string`	Yes	the featured app (jet) to start with (`featured.list` names each as app).
`app`	body	`string`	No	the account's app that uses the jet. With no app and no new_app, the account's one app is used, and an account with none gets a new app. An account with several is told to name one.
`new_app`	body	`string`	No	the slug of a new app to make for the jet.
`name`	body	`string`	No	the key's name, the jet's by default.
`mode`	body	`"live" \| "test"`	No

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_accounts/$ID/jets/$JET/start" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`region`

`region.choices`

List the regions an app can be created in: those that are available and serving, each with its slug, public name and country. Empty until a region serves. Pass a slug as region to account.app.create to place the app there.

Route: GET /v1/_accounts/{id}/regions
Auth: Account key account
MCP tool: substrio_region_choices
CLI: substrio op region.choices

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.

Response

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

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_accounts/$ID/regions" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`subscriptions`

`subscriptions.mine`

List the signed-in person's own subscriptions at every app, active and ended: what they bought for themselves (a cart for the person), each Substrio plan's bundle children, and the plans apps granted them. A person's session only (at the console or at any app); a key is refused SUBSCRIPTION_PERSON_REQUIRED.

Route: GET /v1/_subscriptions/mine
Auth: Account key account
MCP tool: substrio_subscriptions_mine
CLI: substrio op subscriptions.mine

Parameters

No parameters.

Response

Field	Type	Present	Description
`subscriptions`	`array of object`	Always
`entitlements`	`array of object`	When set	`subscriptions.mine`: the plan in force at each app where one is active (the highest of the stack per counter and period).
`cursor`	`string or null`	When set	the next page's cursor; null at the end.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_subscriptions/mine" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"