Config operations. Substrio docs

`ai`

`ai.config.delete`

Delete the app's AI provider configuration.

Route: DELETE /v1/_ai/config
Auth: App key tenant
MCP tool: substrio_ai_config_delete
CLI: substrio op ai.config.delete

Parameters

No parameters.

Response

A JSON object.

Errors

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

Example

curl -X DELETE "$SUBSTRIO_URL/v1/_ai/config" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`ai.config.get`

Read the app's AI provider configuration.

Route: GET /v1/_ai/config
Auth: App key tenant
MCP tool: substrio_ai_config_get
CLI: substrio op ai.config.get

Parameters

No parameters.

Response

A JSON object.

Errors

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

Example

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

`ai.config.set`

Replace the app's AI provider configuration; see the schema.

Route: POST /v1/_ai/config
Auth: App key tenant
MCP tool: substrio_ai_config_set
CLI: substrio op ai.config.set

Parameters

Name	In	Type	Required
`tools`	body	`object`	No
`system_prompts`	body	`object`	No
`defaults`	body	`object`	No

Response

A JSON object.

Errors

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

Example

curl -X POST "$SUBSTRIO_URL/v1/_ai/config" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`ai.config.update`

Change part of the app's AI provider configuration; see the schema.

Route: PATCH /v1/_ai/config
Auth: App key tenant
MCP tool: substrio_ai_config_update
CLI: substrio op ai.config.update

Parameters

Name	In	Type	Required
`tools`	body	`object`	No
`system_prompts`	body	`object`	No
`defaults`	body	`object`	No

Response

A JSON object.

Errors

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

Example

curl -X PATCH "$SUBSTRIO_URL/v1/_ai/config" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`apps`

Read the app's word on calls between apps: the functions it offers other apps (each to the apps named, or @account: every app of its own account) and the functions of other apps it calls as substrio.apps.<app>.<entry>(...).

Route: GET /v1/_app_calls
Auth: App key tenant
MCP tool: substrio_apps_calls_get
CLI: substrio op apps.calls.get

Parameters

No parameters.

Response

Field	Type	Present	Description
`offer`	`object`	When set	entry -> the app slugs it is offered to, or "@account".
`use`	`object`	When set	app slug -> its entries this app calls.
`query`	`object`	When set	query name -> a read this app offers, run by the engine on this app's store with no function of it run: collection, where (fields declared indexed, each an equality bound to the call's argument of its position), select (the only fields a row answers), to (app slugs, or "@account"), limit (0 or absent: every match).
`use_query`	`object`	When set	app slug -> its queries this app reads as substrio.apps.<app>.query.<name>(...args): their names, or query name -> the fields this app reads of it ([] for every field the offer selects; a field the offer does not select is refused APP_QUERY_FIELD_NOT_EXPOSED).
`warnings`	`array of object`	When set	answer only: each app the word names that does not exist yet ({code: APP_USE_UNKNOWN_APP, app}); the word is kept and each call or read of it is refused app_call_unknown_app or app_query_unknown_app until the app exists.

Errors

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

Example

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

`apps.calls.set`

Replace the app's word on calls between apps with the body (an empty body object removes it). A call needs both sides: the callee offers the entry to the caller, the caller names it under use. A bad document is refused whole and the word in force stays; substrio deploy sends it from substrio.toml [apps.offer] and [apps.use]. A read offered under query (substrio.apps.<app>.query.<name>(...args)) is run by the engine on this app's store with no function of it run, under the same two-sided grant (the caller names it under use_query; [apps.query.<name>] and [apps.use_query]); every where field but _id must be declared indexed (index.create kind collection), else the document is refused.

Route: PUT /v1/_app_calls
Auth: App key tenant
MCP tool: substrio_apps_calls_set
CLI: substrio op apps.calls.set

Parameters

Name	In	Type	Required	Description
`offer`	body	`object`	No	entry -> the app slugs it is offered to, or "@account".
`use`	body	`object`	No	app slug -> its entries this app calls.
`query`	body	`object`	No	query name -> a read this app offers, run by the engine on this app's store with no function of it run: collection, where (fields declared indexed, each an equality bound to the call's argument of its position), select (the only fields a row answers), to (app slugs, or "@account"), limit (0 or absent: every match).
`use_query`	body	`object`	No	app slug -> its queries this app reads as substrio.apps.<app>.query.<name>(...args): their names, or query name -> the fields this app reads of it ([] for every field the offer selects; a field the offer does not select is refused APP_QUERY_FIELD_NOT_EXPOSED).
`warnings`	body	`array of object`	No	answer only: each app the word names that does not exist yet ({code: APP_USE_UNKNOWN_APP, app}); the word is kept and each call or read of it is refused app_call_unknown_app or app_query_unknown_app until the app exists.

Response

Field	Type	Present	Description
`offer`	`object`	When set	entry -> the app slugs it is offered to, or "@account".
`use`	`object`	When set	app slug -> its entries this app calls.
`query`	`object`	When set	query name -> a read this app offers, run by the engine on this app's store with no function of it run: collection, where (fields declared indexed, each an equality bound to the call's argument of its position), select (the only fields a row answers), to (app slugs, or "@account"), limit (0 or absent: every match).
`use_query`	`object`	When set	app slug -> its queries this app reads as substrio.apps.<app>.query.<name>(...args): their names, or query name -> the fields this app reads of it ([] for every field the offer selects; a field the offer does not select is refused APP_QUERY_FIELD_NOT_EXPOSED).
`warnings`	`array of object`	When set	answer only: each app the word names that does not exist yet ({code: APP_USE_UNKNOWN_APP, app}); the word is kept and each call or read of it is refused app_call_unknown_app or app_query_unknown_app until the app exists.

Errors

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

Example

curl -X PUT "$SUBSTRIO_URL/v1/_app_calls" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`function`

`function.environment.delete`

Delete one environment variable of a function: the route's {name} and {key}, optional body expected_hash (the content_hash you last read; a function that changed since is refused). Takes effect on the next call; answers the function's metadata.

Route: DELETE /v1/functions/{name}/env/{key}
Auth: App key tenant
MCP tool: substrio_function_environment_delete
CLI: substrio op function.environment.delete

Parameters

Name	In	Type	Required	Description
`name`	path	`string`	Yes	The function's name, as `function.list` names it.
`key`	path	`string`	Yes	The environment variable's name, as `function.environment.list` shows it.
`expected_hash`	query	`string`	No

Response

A JSON object.

Errors

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

Example

curl -X DELETE "$SUBSTRIO_URL/v1/functions/$NAME/env/$KEY" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`function.environment.list`

List one function's environment variables: answers {function, content_hash, environment (name to value), count}; 404 when no such function. The values are shown in full; use secret.list for secrets, which are never shown.

Route: GET /v1/functions/{name}/env
Auth: App key tenant
MCP tool: substrio_function_environment_list
CLI: substrio op function.environment.list

Parameters

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

Response

A JSON object.

Errors

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

Example

curl "$SUBSTRIO_URL/v1/functions/$NAME/env" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`function.environment.set`

Set one environment variable of a function: body key and value (strings, key not empty), optional expected_hash (the content_hash you last read; a function that changed since is refused). Takes effect on the next call; answers the function's metadata.

Route: PUT /v1/functions/{name}/env
Auth: App key tenant
MCP tool: substrio_function_environment_set
CLI: substrio op function.environment.set

Parameters

Name	In	Type	Required	Description
`name`	path	`string`	Yes	The function's name, as `function.list` names it.
`key`	body	`string`	Yes	The variable's name.
`value`	body	`string`	Yes	The variable's value.
`expected_hash`	body	`string`	No	The content_hash you last read; a function that changed since is refused.

Response

A JSON object.

Errors

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

Example

curl -X PUT "$SUBSTRIO_URL/v1/functions/$NAME/env" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key":"key","value":"value"}'

`mcp`

`mcp.tool.list`

List the app's own MCP tools (every route of its functions out of the box, mcp.json's, and those set with mcp.tool.set), each as tools/list shows it with its route, its source (route or manifest) and calls: the tools/call runs it has had.

Route: GET /v1/_mcp/tool
Auth: App key tenant
MCP tool: substrio_mcp_tool_list
CLI: substrio op mcp.tool.list

Parameters

No parameters.

Response

Field	Type	Present	Description
`tools`	`array of object`	Always
`count`	`integer`	Always	Minimum 0.

Errors

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

Example

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

`mcp.tool.remove`

Remove one tool (the route's {name}) that mcp.json or mcp.tool.set made, until a version goes live. A name the app's /mcp does not serve is MCP_TOOL_NOT_FOUND; a route's own tool is MCP_TOOL_FROM_ROUTE (its function says tools: {"<route>": false}).

Route: DELETE /v1/_mcp/tool/{name}
Auth: App key tenant
MCP tool: substrio_mcp_tool_remove
CLI: substrio op mcp.tool.remove

Parameters

Name	In	Type	Required	Description
`name`	path	`string`	Yes	The tool's name, as `mcp.tool.list` names it. Matches `^[A-Za-z0-9_-]{1,64}$`.

Response

Field	Type	Present	Description
`removed`	`any`	Always
`name`	`string`	Always

Errors

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

Example

curl -X DELETE "$SUBSTRIO_URL/v1/_mcp/tool/$NAME" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`mcp.tool.set`

Set one tool of the app's MCP manifest (the body; a tool of its name is replaced, any other added): its schema is checked first, and a refusal is MCP_TOOL_INVALID naming field. It lasts until a version goes live; declare it in functions/<name>.json or mcp.json to keep it.

Route: PUT /v1/_mcp/tool
Auth: App key tenant
MCP tool: substrio_mcp_tool_set
CLI: substrio op mcp.tool.set

Parameters

Name	In	Type	Required	Description
`name`	body	`string`	Yes	The tool's name for agents: a tool of this name is replaced, any other is added. Matches `^[A-Za-z0-9_-]{1,64}$`.
`title`	body	`string`	No
`description`	body	`string`	Yes	What the tool does, for an agent choosing one.
`route`	body	`string`	Yes	METHOD /path/:param of a route the app's functions declare: the call runs it as its HTTP request would, under the caller's identity.
`inputSchema`	body	`object`	No	A JSON Schema of the arguments (type object): each :param of the route is one; the others go to the query (GET, DELETE) or the body. Checked when set: a schema that is not well formed is MCP_TOOL_INVALID naming field.
`outputSchema`	body	`object`	No
`annotations`	body	`object`	No	MCP tool annotations (readOnlyHint, destructiveHint, ...).

Response

Field	Type	Present
`name`	`string`	Always
`title`	`string`	When set
`description`	`string`	Always
`route`	`string`	Always
`inputSchema`	`object`	Always
`outputSchema`	`object`	When set
`annotations`	`object`	When set

Errors

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

Example

curl -X PUT "$SUBSTRIO_URL/v1/_mcp/tool" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"name","description":"description","route":"route"}'

`mcp.tool.test`

Call one of the app's tools (the route's {name}) with arguments, as an end user (user) or as the caller's key, and answer exactly the tools/call result an agent would get. Counted as a call. Runs on the app's /mcp, where tools/call runs.

Route: POST /v1/_mcp/tool/{name}/test
Auth: App key tenant
MCP tool: substrio_mcp_tool_test
CLI: substrio op mcp.tool.test

Parameters

Name	In	Type	Required	Description
`name`	path	`string`	Yes	The tool's name, as `mcp.tool.list` names it. Matches `^[A-Za-z0-9_-]{1,64}$`.
`arguments`	body	`object`	No	The tool's arguments, as an agent's tools/call sends them.
`user`	body	`string or integer`	No	An end user of the app (`user.list`): the call runs as that person, under the route's gate and the app's rules, as their own OAuth token would. Absent: as the caller's key, which a gated route refuses as it refuses a key over HTTP.

Response

Field	Type	Present
`content`	`array`	Always
`structuredContent`	`any`	When set
`isError`	`boolean`	When set

Errors

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

Example

curl -X POST "$SUBSTRIO_URL/v1/_mcp/tool/$NAME/test" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`mcp.tools.delete`

Remove the app's MCP tool manifest, leaving the platform tools only.

Route: DELETE /v1/_mcp/tools
Auth: App key tenant
MCP tool: substrio_mcp_tools_delete
CLI: substrio op mcp.tools.delete

Parameters

No parameters.

Response

204 No Content: success has no body.

Errors

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

Example

curl -X DELETE "$SUBSTRIO_URL/v1/_mcp/tools" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`mcp.tools.get`

Read the app's own MCP tool manifest: the tools the app's /mcp serves besides the platform tools, and its instructions.

Route: GET /v1/_mcp/tools
Auth: App key tenant
MCP tool: substrio_mcp_tools_get
CLI: substrio op mcp.tools.get

Parameters

No parameters.

Response

Field	Type	Present
`instructions`	`string`	When set
`auth`	`"users" \| "bearer"`	Always
`consent_path`	`string`	When set
`tools`	`array of object`	Always

Errors

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

Example

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

`mcp.tools.set`

Replace the app's MCP tool manifest (its own tools and instructions) with the body; see the schema. A version can carry the manifest too (version.create).

Route: POST /v1/_mcp/tools
Auth: App key tenant
MCP tool: substrio_mcp_tools_set
CLI: substrio op mcp.tools.set

Parameters

Name	In	Type	Required	Description
`instructions`	body	`string`	No
`tools`	body	`array of object`	Yes

Response

Field	Type	Present
`instructions`	`string`	When set
`auth`	`"users" \| "bearer"`	Always
`consent_path`	`string`	When set
`tools`	`array of object`	Always

Errors

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

Example

curl -X POST "$SUBSTRIO_URL/v1/_mcp/tools" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tools":[]}'

`plans`

`plans.account.get`

Read the plan an account is on, with its limits and features; an account with no plan set is on the default plan.

Route: GET /v1/_plans/accounts/{account}
Auth: App key tenant
MCP tool: substrio_plans_account_get
CLI: substrio op plans.account.get

Parameters

Name	In	Type	Required	Description
`account`	path	`string`	Yes	The account id.

Response

A JSON object.

Errors

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

Example

curl "$SUBSTRIO_URL/v1/_plans/accounts/$ACCOUNT" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`plans.account.set`

Put an account on one of the tenant's plans.

Route: PUT /v1/_plans/accounts/{account}
Auth: App key tenant
MCP tool: substrio_plans_account_set
CLI: substrio op plans.account.set

Parameters

Name	In	Type	Required	Description
`account`	path	`string`	Yes	The account id.
`plan`	body	`string`	Yes	The id of a plan in the deployed plans file.

Response

A JSON object.

Errors

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

Example

curl -X PUT "$SUBSTRIO_URL/v1/_plans/accounts/$ACCOUNT" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan":"plan"}'

`plans.delete`

Delete the app's plans file: every plan definition is gone and cannot be restored by this call (keep the plans.get answer to put it back with plans.set). Answers 204 with no body; accounts keep no plan and fall back to the default.

Route: DELETE /v1/_plans
Auth: App key tenant
MCP tool: substrio_plans_delete
CLI: substrio op plans.delete

Parameters

No parameters.

Response

A JSON object.

Errors

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

Example

curl -X DELETE "$SUBSTRIO_URL/v1/_plans" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`plans.get`

Read the app's plans file: the plans an account can be put on, each with its limits and features. Answers 404 when no plans are set, so a first plans.set is a create, not an update.

Route: GET /v1/_plans
Auth: App key tenant
MCP tool: substrio_plans_get
CLI: substrio op plans.get

Parameters

No parameters.

Response

A JSON object.

Errors

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

Example

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

`plans.set`

Replace the tenant's plans file; a bad file is refused and the deployed plans stay in force.

Route: POST /v1/_plans
Auth: App key tenant
MCP tool: substrio_plans_set
CLI: substrio op plans.set

Parameters

Name	In	Type	Required	Description
`counters`	body	`array of string`	Yes	The usage counters the plans cap.
`default_plan`	body	`string`	Yes	The plan a new account starts on.
`plans`	body	`array of object`	Yes

Response

A JSON object.

Errors

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

Example

curl -X POST "$SUBSTRIO_URL/v1/_plans" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"counters":[],"default_plan":"default_plan","plans":[]}'

`rag`

`rag.collection.delete`

Delete a collection's retrieval (RAG) configuration.

Route: DELETE /v1/{collection}/_rag
Auth: App key tenant
MCP tool: substrio_rag_collection_delete
CLI: substrio op rag.collection.delete

Parameters

Name	In	Type	Required	Description
`collection`	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/$COLLECTION/_rag" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`rag.collection.get`

Read a collection's retrieval (RAG) configuration.

Route: GET /v1/{collection}/_rag
Auth: App key tenant
MCP tool: substrio_rag_collection_get
CLI: substrio op rag.collection.get

Parameters

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

Response

A JSON object.

Errors

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

Example

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

`rag.collection.set`

Write a collection's retrieval (RAG) configuration; see the schema.

Route: PUT /v1/{collection}/_rag
POST /v1/{collection}/_rag
Auth: App key tenant
MCP tool: substrio_rag_collection_set
CLI: substrio op rag.collection.set

Parameters

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

Response

A JSON object.

Errors

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

Example

curl -X PUT "$SUBSTRIO_URL/v1/$COLLECTION/_rag" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`rag.drift`

Inspect embedding drift for a collection.

Route: GET /v1/{collection}/_rag/drift
Auth: App key tenant
MCP tool: substrio_rag_drift
CLI: substrio op rag.drift

Parameters

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

Response

A JSON object.

Errors

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

Example

curl "$SUBSTRIO_URL/v1/$COLLECTION/_rag/drift" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`rag.embed`

Embed the records of a collection, using the collection's RAG configuration.

Route: POST /v1/{collection}/_rag/embed
Auth: App key tenant
MCP tool: substrio_rag_embed
CLI: substrio op rag.embed

Parameters

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

Response

A JSON object.

Errors

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

Example

curl -X POST "$SUBSTRIO_URL/v1/$COLLECTION/_rag/embed" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`rag.get`

Read tenant RAG configuration.

Route: GET /v1/_rag
Auth: App key or user session; your security rules apply none
CLI: substrio op rag.get

Parameters

No parameters.

Response

A JSON object.

Errors

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

Example

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

`rag.reembed`

Embed every record of a collection again, using the collection's RAG configuration.

Route: POST /v1/{collection}/_rag/re-embed
Auth: App key tenant
MCP tool: substrio_rag_reembed
CLI: substrio op rag.reembed

Parameters

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

Response

A JSON object.

Errors

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

Example

curl -X POST "$SUBSTRIO_URL/v1/$COLLECTION/_rag/re-embed" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`secret`

`secret.delete`

Delete one app secret by its key (the route's {key}): answers deleted and the key. The value is gone and cannot be restored; secret.write sets a new one. A key the app does not hold is SECRET_NOT_FOUND naming key.

Route: DELETE /v1/_secrets/{key}
Auth: App key tenant
MCP tool: substrio_secret_delete
CLI: substrio op secret.delete

Parameters

Name	In	Type	Required	Description
`key`	path	`string`	Yes	The secret's name, as `secret.list` shows it.

Response

Field	Type	Present
`success`	`boolean`	Always
`deleted`	`boolean`	Always
`key`	`string`	Always

Errors

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

Example

curl -X DELETE "$SUBSTRIO_URL/v1/_secrets/$KEY" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`secret.list`

List the names of the app's secrets: answers secrets (each {key, value:'***'}) and count. Values are never returned; set or delete one with secret.write.

Route: GET /v1/_secrets
Auth: App key tenant
MCP tool: substrio_secret_list
CLI: substrio op secret.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/_secrets" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`secret.write`

Set an app secret: key and value (both required, not empty). The value cannot be read back, only overwritten; secret.list shows names and secret.delete removes one.

Route: PUT /v1/_secrets
POST /v1/_secrets
Auth: App key tenant
MCP tool: substrio_secret_write
CLI: substrio op secret.write

Parameters

Name	In	Type	Required	Description
`key`	body	`string`	Yes	The secret's name.
`value`	body	`string`	Yes	The secret's value; it can be overwritten but never read back.

Response

A JSON object.

Errors

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

Example

curl -X PUT "$SUBSTRIO_URL/v1/_secrets" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key":"key","value":"value"}'

`settings`

`settings.delete`

Delete one app setting by key; a setting substrio reads goes back to its default.

Route: DELETE /v1/_settings/{key}
Auth: App key tenant
MCP tool: substrio_settings_delete
CLI: substrio op settings.delete

Parameters

Name	In	Type	Required	Description
`key`	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/_settings/$KEY" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`settings.get`

List the app's settings: answers settings (each {key, value}) and count.

Route: GET /v1/_settings
Auth: App key tenant
MCP tool: substrio_settings_get
CLI: substrio op settings.get

Parameters

No parameters.

Response

A JSON object.

Errors

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

Example

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

`settings.set`

Set one app setting: body key and value (a string, or true or false). Any key is stored; substrio reads changes.history (keep change history so change streams can resume) and webhooks.brand (the webhook signature and delivery id header names, <brand>-Signature and <brand>-Delivery-Id) and the delivery settings webhooks.max_attempts, webhooks.backoff_ms, triggers.max_attempts, triggers.backoff_ms, cron.max_attempts, cron.backoff_ms, delivery.backoff_cap_ms (milliseconds) and delivery.retain_days (days a delivered record stays replayable, 0 keeps none), each a whole number (the attempt counts at least 1), and refuses a value that does not suit them. A server-wide runtime limit (jsc.*, queue.*, objects.*) is a platform setting and is refused here with SETTING_IS_PLATFORM.

Route: PUT /v1/_settings
POST /v1/_settings
Auth: App key tenant
MCP tool: substrio_settings_set
CLI: substrio op settings.set

Parameters

Name	In	Type	Required	Description
`key`	body	`string`	Yes	The setting's name; substrio reads changes.history and webhooks.brand, any other key is only stored.
`value`	body	`string or boolean`	Yes	A string, or true or false for a switch such as changes.history (keep change history so change streams can resume); webhooks.brand names the webhook signature header, <brand>-Signature (default Substrio): 1 to 40 letters, digits and -.

Response

A JSON object.

Errors

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

Example

curl -X PUT "$SUBSTRIO_URL/v1/_settings" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key":"key","value":"value"}'

`subscriptions`

`subscriptions.list`

List an app's subscribers a page at a time: every subscription to its plans (a purchase, a bundle child of a Substrio plan, or a grant), by subject (an account, a person, or an app's own user) and id. The caller's own app, or (app) another app of the same owning account; any other app's is refused SUBSCRIBERS_NOT_VISIBLE.

Route: GET /v1/_subscriptions
Auth: App key tenant
MCP tool: substrio_subscriptions_list
CLI: substrio op subscriptions.list

Parameters

Name	In	Type	Required	Description
`app`	query	`string`	No	The seller app's slug: the caller's own app (the default) or another app of the same owning account.
`cursor`	query	`string`	No	The cursor a page answered.
`limit`	query	`integer`	No	Subscriptions a page (default 100). Minimum 1. Maximum 1000.

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" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`undo`

Undo a change by the undo token it returned; returns a token that redoes it.

Route: POST /v1/_undo
Auth: App key or user session; your security rules apply none
MCP tool: substrio_undo
CLI: substrio op undo

Parameters

Name	In	Type	Required	Description
`token`	body	`string`	Yes	The undo_token a change returned; a change that answered undo_token null (unchanged true, or pending true for a 202) left nothing to `undo`.

Response

A JSON object.

Errors

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

Example

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