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 answers the 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 answers the 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 answers the 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 answers the 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 answers the 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 answers the 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 answers the error envelope with a typed code.

Example

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

`account.create`

Create an account owned by the signed-in person.

Route: POST /v1/_accounts
Auth: Account key account
MCP tool: substrio_account_create
CLI: substrio op account.create

Parameters

Name	In	Type	Required	Description
`name`	body	`string`	Yes
`owner_user_id`	body	`integer`	No	System key only: the identity app user who owns the account. Minimum 1.

Response

A JSON object.

Errors

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

Example

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

`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.

Response

A JSON object.

Errors

A failed call answers the 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 answers the 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 answers the 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 answers the 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 answers the 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 answers the 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 answers the 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 answers the 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 answers the 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 answers the 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 answers the 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 answers the 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 answers the 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 answers the 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 answers the 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 answers the 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 answers the 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 answers the 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 answers the 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 answers the 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 answers the 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.
`platform_operator`	body	`boolean`	No	System key only: its owners and admins who sign in to the identity app with 2FA operate the platform.
`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 answers the 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 answers the 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 and the plan's CPU slices, 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 ceiling.

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.

Errors

A failed call answers the 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 answers the error envelope with a typed code.

Example

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

`agent.approval.approve`

Approve one irreversible call an agent session asked for (people only, never an agent); the agent then repeats that exact call with the approval id, once.

Route: POST /v1/_accounts/{id}/agent/approvals/{approval_id}/approve
Auth: Account key account
MCP tool: substrio_agent_approval_approve
CLI: substrio op agent.approval.approve

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`approval_id`	path	`string`	Yes	The approval's id, as `agent.approval.list` or the agent's approval-required answer gave it.

Response

A JSON object.

Errors

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

Example

curl -X POST "$SUBSTRIO_URL/v1/_accounts/$ID/agent/approvals/$APPROVAL_ID/approve" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`agent.approval.deny`

Deny one irreversible call an agent session asked for (people only); the agent's repeat of it is refused.

Route: POST /v1/_accounts/{id}/agent/approvals/{approval_id}/deny
Auth: Account key account
MCP tool: substrio_agent_approval_deny
CLI: substrio op agent.approval.deny

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`approval_id`	path	`string`	Yes	The approval's id, as `agent.approval.list` or the agent's approval-required answer gave it.

Response

A JSON object.

Errors

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

Example

curl -X POST "$SUBSTRIO_URL/v1/_accounts/$ID/agent/approvals/$APPROVAL_ID/deny" \
  -H "Authorization: Bearer $SUBSTRIO_ACCOUNT_KEY"

`agent.approval.list`

List the irreversible calls of the account's agent sessions that wait for a person's approval, oldest first, a page at a time (limit, cursor; next_cursor), or only those on one app (app) (people only).

Route: GET /v1/_accounts/{id}/agent/approvals
Auth: Account key account
MCP tool: substrio_agent_approval_list
CLI: substrio op agent.approval.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 answers the error envelope with a typed code.

Example

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

`agent.enroll.create`

Make a one-time code that an AI agent exchanges for a session acting as you in the account; the code is returned once.

Route: POST /v1/_accounts/{id}/agent/enrollments
Auth: Account key account
MCP tool: substrio_agent_enroll_create
CLI: substrio op agent.enroll.create

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	The account the agent will act in. Minimum 1.
`name`	body	`string`	Yes	What you call the agent.
`apps`	body	`array of string`	No	Narrow the session to these apps of the account (slugs); absent: every app.
`capabilities`	body	`array of string`	No	Narrow the session to these capabilities (names from docs.capabilities); absent: all.
`expires_in_seconds`	body	`integer`	No	How long the code can be exchanged (default agent_enroll_ttl_seconds). Minimum 1.
`requests_per_minute`	body	`integer`	No	A rolling limit on the session's requests per minute; absent: none. Minimum 1.
`request_budget`	body	`integer`	No	The most requests the session makes in its life; absent: none. Minimum 1.

Response

A JSON object.

Errors

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

Example

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

`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 answers the 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.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 answers the 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 agent sessions, 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 answers the 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 answers the 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 answers the 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 answers the 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 answers the 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

Response

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

Errors

A failed call answers the 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 answers the 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 answers the 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 answers the 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 answers the 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	credit to add, in the minor unit (cents), 500 to 1000000. Minimum 0.
`space_blocks`	body	`integer`	No	the space add-on blocks the account holds once the cart is paid (a plan with space_addon, Scale); 0 releases them. Minimum 0. Maximum 100000.

Response

A JSON object.

Errors

A failed call answers the 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 answers the 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 answers the 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 answers the 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 answers the 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.checkout.start`

Start paying a cart (the person's own session only, never an agent's or a key): the provider's payment is made for its plans and funds and the answer gives the client_secret and publishable_key the checkout page's Payment Element pays with. A change the saved card pays at once is applied and answers paid true.

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

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 answers the error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_accounts/$ID/billing/carts/$CART/checkout" \
  -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 answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_accounts/$ID/billing/credit" \
  -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	credit to add to the account, in the minor unit (cents), 500 to 1000000. Minimum 0.

Response

A JSON object.

Errors

A failed call answers the 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 answers the 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	the console's nav items in order, each {id, title, icon, panels, role?, params?}; empty when the app declares no dashboard.

Errors

A failed call answers the 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`

Disable a featured app for the account: its plan there is removed, every account key scoped to that app alone is revoked (a key scoped to several apps loses this one), so each stops at its next request. The answer counts the keys revoked. The use already counted stays.

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 answers the 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`

Enable a featured app for the account: the account is put on the app's default plan there (an account already enabled keeps its plan) and may then make keys scoped to it (featured.key.create). Every call to the app is metered against that plan.

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 answers the 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`

Make an account key scoped to one featured app the account has enabled; the secret is returned once. An unscoped account key may make one (it is narrower than the key that makes it); a scoped key may not.

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 answers the 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) with what each does, its admin in the console, whether the account has it enabled, the plan it is metered against and its use this day and month against that plan's limits.

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 answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_accounts/$ID/featured" \
  -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 answers the error envelope with a typed code.

Example

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

`subscriptions`

`subscriptions.cancel`

End one of the signed-in person's own subscriptions now: a paid one leaves the account's provider subscription that pays it (that line, or the whole subscription when it was the last) and the person falls back to what else they hold there (a bundle's plan, else the app's default). A bundle child ends only with its Substrio plan (SUBSCRIPTION_NOT_FOUND). The person's own session only, never a key or an agent (SUBSCRIPTION_PERSON_REQUIRED). Answers the subscription, ended.

Route: POST /v1/_subscriptions/{id}/cancel
Auth: Account key account
MCP tool: substrio_subscriptions_cancel
CLI: substrio op subscriptions.cancel

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	The subscription's id, from `subscriptions.mine`.

Response

Field	Type	Present	Description
`id`	`integer`	When set	0: the plan the app granted.
`subject`	`object`	When set
`app`	`string`	When set	the seller: the app whose plans file the plan is in.
`plan`	`string`	When set
`source`	`"grant" \| "purchase" \| "bundle"`	When set
`status`	`"active" \| "canceling" \| "ended"`	When set
`parent`	`integer`	When set	a bundle: the Substrio plan's subscription it came with.
`since`	`integer`	When set
`period_end`	`integer or null`	When set
`ended_at`	`integer`	When set

Errors

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

Example

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

`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 answers the error envelope with a typed code.

Example

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