Functions operations. Substrio docs

`branch`

`branch.create`

Make a branch in the app's history: name it and say where it starts (from, a branch name or a version id; default the main branch's head). A branch is a name that moves with each commit on it. 409 when the name is taken; the name of a deleted branch is free again and its log is kept. Answers {name, version, protected}.

Route: POST /v1/_branches
Auth: App key tenant
MCP tool: substrio_branch_create
CLI: substrio op branch.create

Parameters

Name	In	Type	Required	Description
`name`	body	`string`	Yes	The branch's name.
`from`	body	`string`	No	The branch or version the new branch starts at (default: the app's main branch head). A version id (64 hex) or a branch name.

Response

A JSON object.

Errors

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

Example

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

`branch.delete`

Free a branch's name (the route's {name}). Its versions are kept (another name or a merge may still reach them) and its log survives, so ref.restore can put the name back. The main branch is never deleted. Answers {name, version}.

Route: DELETE /v1/_branches/{name}
Auth: App key tenant
MCP tool: substrio_branch_delete
CLI: substrio op branch.delete

Parameters

Name	In	Type	Required	Description
`name`	path	`string`	Yes	The branch's name, as `branch.list` names it.

Response

A JSON object.

Errors

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

Example

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

`branch.list`

List the app's branches by name, each with the version it points at, when it last moved, whether it is protected and the checks a move onto it needs green; never refuses.

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

`branch.protect`

Protect a branch (the route's {name}), or unprotect it with protected:false. While it is protected every commit or merge onto it must say its required_checks are green. An empty required_checks protects it with no named check, which still needs a green verdict. Answers {name, protected, required_checks}.

Route: POST /v1/_branches/{name}/protect
Auth: App key tenant
MCP tool: substrio_branch_protect
CLI: substrio op branch.protect

Parameters

Name	In	Type	Required	Description
`name`	path	`string`	Yes	The branch's name, as `branch.list` names it.
`protected`	body	`boolean`	No	true protects the branch: a commit or a merge onto it needs its required checks green (default: true).
`required_checks`	body	`array of string`	No	The checks a move onto the branch needs green; an empty list protects it with none.

Response

A JSON object.

Errors

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

Example

curl -X POST "$SUBSTRIO_URL/v1/_branches/$NAME/protect" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`function`

`function.catalog`

Summarize tenant databases and deployed functions.

Route: GET /v1/_functions/_catalog
Auth: App key tenant
MCP tool: substrio_function_catalog
CLI: substrio op function.catalog

Parameters

Name	In	Type	Required	Description
`max_databases`	query	`integer (0 or more)`	No	the most databases to describe (positive, at most 256).
`max_functions`	query	`integer (0 or more)`	No	the most functions to describe (positive, at most 65536).
`max_databases`	query	`integer`	No	Minimum 1.
`max_functions`	query	`integer`	No	Minimum 1.

Response

A JSON object.

Errors

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

Example

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

`function.check`

Check a function before deploying it: the same body as function.deploy (script, name, routes, vars, bindings); parses the source as a script, CommonJS or ES module without running it and applies deploy's manifest and require() refusals; answers ok and diagnostics (severity, message, file, line, column); nothing is written or executed.

Route: POST /v1/_functions/_check
Auth: App key tenant
MCP tool: substrio_function_check
CLI: substrio op function.check

Parameters

Name	In	Type	Required	Description
`name`	body	`string`	No	The function's name: letters, digits, - _ and . (required by `function.deploy`; `function.update` takes it from the path; `function.check` names it in its diagnostics).
`script`	body	`string`	Yes	The whole source: a script, CommonJS or ES module. It must compile to a handler (module.exports = async function (event) {...} or export default { fetch }).
`main`	body	`string`	No	The entry file name (default index.js).
`routes`	body	`array of string`	No	HTTP routes the function answers: [METHOD ]/path, METHOD one of GET POST PUT PATCH DELETE ANY, :name for a parameter segment, a last * segment for any remainder.
`tools`	body	`boolean or object`	No	Which of its routes are the app's MCP tools (every one when absent): false, or an object keyed by a route as declared, each false or {name, title, description, inputSchema, outputSchema, annotations} (docs/mcp.md, Out of the box).
`vars`	body	`object`	No	Environment variables of the function (string values).
`bindings`	body	`array of object`	No	Named resources the function reaches through env.
`deploy_nodes`	body	`array of string`	No	Node ids the function runs on; * or absent means every node.

Response

Field	Type	Present	Description
`ok`	`boolean`	Always	true when there is no error diagnostic (info ones do not count).
`format`	`"script" \| "commonjs" \| "module"`	Always	how the source is run.
`diagnostics`	`array of object`	Always

Errors

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

Example

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

`function.compat`

Invoke a function through the compatibility endpoint.

Route: ANY /fn/{function}
ANY /fn/{function}/*
ANY /fn/*
Auth: App key tenant
CLI: substrio op function.compat

Parameters

Name	In	Type	Required	Description
`function`	path	`string`	Yes
`path`	path	`string`	Yes	The rest of the URL after the route prefix.

Response

A JSON object.

Errors

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

Example

curl "$SUBSTRIO_URL/fn/$FUNCTION" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`function.delete`

Delete one function by name; answers {success, deleted}, 404 when no such function.

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

Parameters

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

Response

A JSON object.

Errors

FUNCTION_NOT_FOUND: call function.list to find the right one.

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

Example

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

`function.deploy`

Deploy one function now, outside a version: body name and script (required), optional main, routes (like 'GET /orders/:id' or 'ANY /hooks/*'), vars, bindings and deploy_nodes. The source is compiled to a handler first; a source that does not compile, or that calls require(), is refused and nothing changes. On success it is live at once and the answer is the function's metadata (id, content_hash, routes, env_vars, bindings). To ship several functions together, or to try them first, use version.create, sandbox.create and version.live.set; function.check shows the problems without writing.

Route: POST /v1/deploy
POST /v1/functions
Auth: App key tenant
MCP tool: substrio_function_deploy
CLI: substrio op function.deploy

Parameters

Name	In	Type	Required	Description
`name`	body	`string`	No	The function's name: letters, digits, - _ and . (required by `function.deploy`; `function.update` takes it from the path; `function.check` names it in its diagnostics).
`script`	body	`string`	Yes	The whole source: a script, CommonJS or ES module. It must compile to a handler (module.exports = async function (event) {...} or export default { fetch }).
`main`	body	`string`	No	The entry file name (default index.js).
`routes`	body	`array of string`	No	HTTP routes the function answers: [METHOD ]/path, METHOD one of GET POST PUT PATCH DELETE ANY, :name for a parameter segment, a last * segment for any remainder.
`tools`	body	`boolean or object`	No	Which of its routes are the app's MCP tools (every one when absent): false, or an object keyed by a route as declared, each false or {name, title, description, inputSchema, outputSchema, annotations} (docs/mcp.md, Out of the box).
`vars`	body	`object`	No	Environment variables of the function (string values).
`bindings`	body	`array of object`	No	Named resources the function reaches through env.
`deploy_nodes`	body	`array of string`	No	Node ids the function runs on; * or absent means every node.

Response

A JSON object.

Errors

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

Example

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

`function.eval`

Run a Lua script against the tenant's default key-value store, Redis style: body script (or sha of a script loaded earlier with load:true, which answers {sha}), keys and args as arrays of strings. Answers {result}. This is Lua over key-value data, not JavaScript: to run JavaScript use function.invoke, route.call or function.execute_inline.

Route: POST /v1/eval
Auth: App key tenant
MCP tool: substrio_function_eval
CLI: substrio op function.eval

Parameters

Name	In	Type	Required	Description
`script`	body	`string`	No	The Lua source to run.
`sha`	body	`string`	No	The sha of a script loaded earlier with load:true; instead of script.
`load`	body	`boolean`	No	true only loads script and answers its sha, without running it.
`keys`	body	`array of string`	No	The script's KEYS.
`args`	body	`array of string`	No	The script's ARGV.

Response

A JSON object.

Errors

FUNCTION_NOT_FOUND: call function.list to find the right one.

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

Example

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

`function.execute_inline`

Run inline JavaScript in the app's runtime: body code (required, not empty). It runs with the caller's own permissions through the same data API a function uses, and nothing is deployed or stored. For a deployed function use function.invoke; to check source without running it use function.check.

Route: POST /v1/_exec
Auth: App key tenant
MCP tool: substrio_function_execute_inline
CLI: substrio op function.execute_inline

Parameters

Name	In	Type	Required	Description
`code`	body	`string`	Yes	The JavaScript to run; its result is answered.

Response

A JSON object.

Errors

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

Example

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

`function.get`

Read one deployed function: its name, its current source script and its metadata (content_hash, routes, env_vars, bindings, enabled, deploy_nodes). 404 when no such function. For a large source read line ranges with function.source.read instead.

Route: GET /v1/functions/{name}
Auth: App key tenant
MCP tool: substrio_function_get
CLI: substrio op function.get

Parameters

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

Response

A JSON object.

Errors

FUNCTION_NOT_FOUND: call function.list to find the right one.

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

Example

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

`function.index`

List deployable functions and immutable source metadata.

Route: GET /v1/_functions/_index
Auth: App key tenant
MCP tool: substrio_function_index
CLI: substrio op function.index

Parameters

No parameters.

Response

A JSON object.

Errors

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

Example

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

`function.invoke`

Invoke one deployed function with a JSON event.

Route: POST /v1/functions/{name}/_invoke
Auth: App key tenant
MCP tool: substrio_function_invoke
CLI: substrio op function.invoke

Parameters

Name	In	Type	Required	Description
`name`	path	`string`	Yes	The function to invoke.
`timeout_ms`	query	`integer (0 or more)`	No	CPU time limit for this run in milliseconds (positive).
`memory_mb`	query	`integer (0 or more)`	No	memory limit for this run in megabytes (positive).
`event`	body	`any`	No	The JSON event passed to the function, any fields (over HTTP, the request body); optional limits are their own arguments (query parameters over HTTP).

Response

A JSON object.

Errors

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

Example

curl -X POST "$SUBSTRIO_URL/v1/functions/$NAME/_invoke" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`function.list`

List the app's deployed functions with their metadata, paged: the limit and cursor options in, next_cursor out. function.catalog summarizes databases and functions together; route.list shows which routes answer.

Route: GET /v1/functions
Auth: App key tenant
MCP tool: substrio_function_list
CLI: substrio op function.list

Parameters

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

`function.patch.approval.get`

Inspect one durable function patch approval.

Route: GET /v1/functions/{name}/approvals/{token}
Auth: App key tenant
MCP tool: substrio_function_patch_approval_get
CLI: substrio op function.patch.approval.get

Parameters

Name	In	Type	Required	Description
`name`	path	`string`	Yes	The function's name, as `function.list` names it.
`token`	path	`string`	Yes	The approval token `function.source.preview` returned.

Response

A JSON object.

Errors

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

Example

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

`function.patch.approval.revoke`

Revoke one pending function patch approval.

Route: DELETE /v1/functions/{name}/approvals/{token}
Auth: App key tenant
MCP tool: substrio_function_patch_approval_revoke
CLI: substrio op function.patch.approval.revoke

Parameters

Name	In	Type	Required	Description
`name`	path	`string`	Yes	The function's name, as `function.list` names it.
`token`	path	`string`	Yes	The approval token `function.source.preview` returned.

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

`function.source.edit`

Replace one byte range or one exclusive line range of a function's source: body replacement, an approval_token from function.source.preview (required: preview the patch first), the range, and expected_hash (defaults to the current content_hash; a source that changed since is refused with 409). The edited source is compiled before it is stored.

Route: PATCH /v1/functions/{name}/source
Auth: App key tenant
MCP tool: substrio_function_source_edit
CLI: substrio op function.source.edit

Parameters

Name	In	Type	Required	Description
`name`	path	`string`	Yes	The function's name, as `function.list` names it.
`start`	body	`integer`	No	Minimum 0.
`end`	body	`integer`	No	Minimum 0.
`start_line`	body	`integer`	No	Minimum 1.
`end_line`	body	`integer`	No	Minimum 2.
`replacement`	body	`string`	Yes
`expected_hash`	body	`string`	No
`approval_token`	body	`string`	Yes
`idempotency_key`	body	`string`	No

Response

A JSON object.

Errors

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

Example

curl -X PATCH "$SUBSTRIO_URL/v1/functions/$NAME/source" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"replacement":"replacement","approval_token":"approval_token"}'

`function.source.preview`

Preview and approve one bounded function source edit.

Route: POST /v1/functions/{name}/source/preview
Auth: App key tenant
MCP tool: substrio_function_source_preview
CLI: substrio op function.source.preview

Parameters

Name	In	Type	Required	Description
`name`	path	`string`	Yes	The function's name, as `function.list` names it.
`start`	body	`integer`	No	Minimum 0.
`end`	body	`integer`	No	Minimum 0.
`start_line`	body	`integer`	No	Minimum 1.
`end_line`	body	`integer`	No	Minimum 2.
`replacement`	body	`string`	Yes
`expected_hash`	body	`string`	No
`idempotency_key`	body	`string`	No

Response

A JSON object.

Errors

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

Example

curl -X POST "$SUBSTRIO_URL/v1/functions/$NAME/source/preview" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"replacement":"replacement"}'

`function.source.read`

Read a bounded line range from the current function source.

Route: GET /v1/functions/{name}/source
Auth: App key tenant
MCP tool: substrio_function_source_read
CLI: substrio op function.source.read

Parameters

Name	In	Type	Required	Description
`name`	path	`string`	Yes	The function's name, as `function.list` names it.
`start_line`	query	`integer (0 or more)`	No	first line to read (1-based; required by `function.source.read`, default 1 for `version.unit`).
`end_line`	query	`integer (0 or more)`	No	line to stop before (exclusive; required by `function.source.read`, default the end for `version.unit`).
`max_bytes`	query	`integer (0 or more)`	No	the most response bytes of source (positive, at most 1 MiB); a cut answer says truncated.
`expected_hash`	query	`string`	No	the source hash the caller last saw; a different current source is a 409.
`start_line`	query	`integer`	Yes	Minimum 1.
`end_line`	query	`integer`	Yes	Minimum 2.
`max_bytes`	query	`integer`	No	Minimum 1.
`expected_hash`	query	`string`	No

Response

A JSON object.

Errors

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

Example

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

`function.source.replace`

Replace one function's whole source with a compare-and-swap: body script (required, compiled before it is stored), optional expected_hash (the content_hash you last read; it defaults to the current one, and a source that changed since is refused with a conflict), main, routes, vars, bindings and deploy_nodes. Fields left out keep their values; an empty array clears. The function must exist (404). Answers the function's metadata.

Route: PUT /v1/functions/{name}/source
Auth: App key tenant
MCP tool: substrio_function_source_replace
CLI: substrio op function.source.replace

Parameters

Name	In	Type	Required	Description
`name`	path	`string`	Yes	The function's name, as `function.list` names it.
`script`	body	`string`	Yes
`expected_hash`	body	`string`	No
`main`	body	`string`	No
`routes`	body	`array of string`	No
`vars`	body	`object`	No
`bindings`	body	`array of object`	No
`deploy_nodes`	body	`array of string`	No

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/source" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"script":"script"}'

`function.source.search`

Search bounded source snippets in the current function.

Route: GET /v1/functions/{name}/search
Auth: App key tenant
MCP tool: substrio_function_source_search
CLI: substrio op function.source.search

Parameters

Name	In	Type	Required	Description
`name`	path	`string`	Yes	The function's name, as `function.list` names it.
`max_bytes`	query	`integer (0 or more)`	No	the most response bytes of source (positive, at most 1 MiB); a cut answer says truncated.
`expected_hash`	query	`string`	No	the source hash the caller last saw; a different current source is a 409.
`q`	query	`string`	No	the text to find: in the function source (`function.source.search`, required), or the words every returned log line's message holds (`function.logs`).
`max_matches`	query	`integer (0 or more)`	No	the most matches to return (positive, at most 1024).
`q`	query	`string`	Yes
`max_matches`	query	`integer`	No	Minimum 1.
`max_bytes`	query	`integer`	No	Minimum 1.
`expected_hash`	query	`string`	No

Response

A JSON object.

Errors

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

Example

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

`function.source.symbols`

List bounded declaration symbols from the current function.

Route: GET /v1/functions/{name}/symbols
Auth: App key tenant
MCP tool: substrio_function_source_symbols
CLI: substrio op function.source.symbols

Parameters

Name	In	Type	Required	Description
`name`	path	`string`	Yes	The function's name, as `function.list` names it.
`max_bytes`	query	`integer (0 or more)`	No	the most response bytes of source (positive, at most 1 MiB); a cut answer says truncated.
`expected_hash`	query	`string`	No	the source hash the caller last saw; a different current source is a 409.
`max_symbols`	query	`integer (0 or more)`	No	the most symbols to return (positive, at most 1024).
`max_symbols`	query	`integer`	No	Minimum 1.
`max_bytes`	query	`integer`	No	Minimum 1.
`expected_hash`	query	`string`	No

Response

A JSON object.

Errors

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

Example

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

`function.syntax.check`

Validate JavaScript syntax without executing the source.

Route: POST /v1/_functions/_syntax
Auth: App key tenant
MCP tool: substrio_function_syntax_check
CLI: substrio op function.syntax.check

Parameters

Name	In	Type	Required	Description
`source`	body	`string`	Yes
`source_name`	body	`string`	No

Response

A JSON object.

Errors

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

Example

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

`function.toggle`

Enable or disable one function without deleting it: body enabled (required boolean). Answers {success, enabled}, 404 when no such function. A disabled function is left out of route.list.

Route: POST /v1/functions/{name}/toggle
Auth: App key tenant
MCP tool: substrio_function_toggle
CLI: substrio op function.toggle

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 -X POST "$SUBSTRIO_URL/v1/functions/$NAME/toggle" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`function.update`

Replace one function's source: PATCH with the body function.deploy takes (script is required); the name comes from the path and a name in the body is ignored. A source that does not compile to a handler is refused with 400 and nothing changes. On success it is live at once and the answer is the function's metadata. For a change to part of the source use function.source.edit.

Route: PATCH /v1/functions/{name}
Auth: App key tenant
MCP tool: substrio_function_update
CLI: substrio op function.update

Parameters

Name	In	Type	Required	Description
`name`	path	`string`	Yes	The function's name: letters, digits, - _ and . (required by `function.deploy`; `function.update` takes it from the path; `function.check` names it in its diagnostics).
`script`	body	`string`	Yes	The whole source: a script, CommonJS or ES module. It must compile to a handler (module.exports = async function (event) {...} or export default { fetch }).
`main`	body	`string`	No	The entry file name (default index.js).
`routes`	body	`array of string`	No	HTTP routes the function answers: [METHOD ]/path, METHOD one of GET POST PUT PATCH DELETE ANY, :name for a parameter segment, a last * segment for any remainder.
`tools`	body	`boolean or object`	No	Which of its routes are the app's MCP tools (every one when absent): false, or an object keyed by a route as declared, each false or {name, title, description, inputSchema, outputSchema, annotations} (docs/mcp.md, Out of the box).
`vars`	body	`object`	No	Environment variables of the function (string values).
`bindings`	body	`array of object`	No	Named resources the function reaches through env.
`deploy_nodes`	body	`array of string`	No	Node ids the function runs on; * or absent means every node.

Response

A JSON object.

Errors

FUNCTION_NOT_FOUND: call function.list to find the right one.

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

Example

curl -X PATCH "$SUBSTRIO_URL/v1/functions/$NAME" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"script":"script"}'

`merge`

`merge.abort`

Throw away a branch's merge draft (the route's {branch}). The branch itself never moved, so nothing of the app changes; the blobs the merge wrote are unreferenced and the next version.gc sweeps them. Answers {branch, deleted}.

Route: DELETE /v1/_merges/{branch}
Auth: App key tenant
MCP tool: substrio_merge_abort
CLI: substrio op merge.abort

Parameters

Name	In	Type	Required	Description
`branch`	path	`string`	Yes	The branch the merge lands on, as `merge.plan` was asked for it.

Response

A JSON object.

Errors

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

Example

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

`merge.commit`

Publish a branch's merge draft (the route's {branch}): one commit of the merged units onto the branch, with the branch merged in as its second parent, and the draft is dropped. 409 while a unit is still conflicted or when the branch moved under the draft. A fast forward moves the branch instead of committing, and a branch already holding the other side's work is answered as up to date. Answers {branch, version, root, number, generation, committed, fast_forward, up_to_date}.

Route: POST /v1/_merges/{branch}/commit
Auth: App key tenant
MCP tool: substrio_merge_commit
CLI: substrio op merge.commit

Parameters

Name	In	Type	Required	Description
`branch`	path	`string`	Yes	The branch the merge lands on.
`message`	body	`string`	No	What this merge did (default: a line naming both sides).
`checks_green`	body	`boolean`	No	true says the branch's required checks are green, which a protected branch needs a move onto it to say.

Response

A JSON object.

Errors

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

Example

curl -X POST "$SUBSTRIO_URL/v1/_merges/$BRANCH/commit" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`merge.get`

The merge draft of a branch (the route's {branch}) as merge.plan and merge.resolve left it: both sides, the version they descend from, every unit the merge touched, what it did with each one and how many are still conflicted. 404 when the branch has no draft.

Route: GET /v1/_merges/{branch}
Auth: App key tenant
MCP tool: substrio_merge_get
CLI: substrio op merge.get

Parameters

Name	In	Type	Required	Description
`branch`	path	`string`	Yes	The branch the merge lands on, as `merge.plan` was asked for it.

Response

A JSON object.

Errors

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

Example

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

`merge.plan`

Work out the merge of one branch into another: from names the branch (or version) whose work comes in, into the branch it lands on (default main). Three way against the version both descend from, so a unit only one side changed is kept without a question and a unit both changed is merged by lines. Publishes nothing: the plan is into's merge draft, which merge.resolve settles and merge.commit publishes. Answers {into, from, base, ours, theirs, up_to_date, fast_forward, conflicts, clean, units, count}.

Route: POST /v1/_merges
Auth: App key tenant
MCP tool: substrio_merge_plan
CLI: substrio op merge.plan

Parameters

Name	In	Type	Required	Description
`from`	body	`string`	Yes	The branch whose work is merged in, or a version id (64 hex).
`into`	body	`string`	No	The branch the merge lands on (default: main); it is this branch's draft.

Response

A JSON object.

Errors

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

Example

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

`merge.resolve`

Settle one conflicted unit of a branch's merge draft (the route's {branch}) with the bytes it should hold, as text or as base64. The unit becomes resolved and the draft's conflict count falls by one, durably. Answers the whole draft again, so the next conflict is in hand.

Route: POST /v1/_merges/{branch}/resolve
Auth: App key tenant
MCP tool: substrio_merge_resolve
CLI: substrio op merge.resolve

Parameters

Name	In	Type	Required	Description
`branch`	path	`string`	Yes	The branch the merge lands on.
`path`	body	`string`	Yes	The conflicted unit's path, as the draft lists it.
`text`	body	`string`	No	The bytes the unit is settled with, as text.
`base64`	body	`string`	No	The bytes the unit is settled with, as base64, for a unit that is not text.

Response

A JSON object.

Errors

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

Example

curl -X POST "$SUBSTRIO_URL/v1/_merges/$BRANCH/resolve" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"path"}'

`object`

`object.socket`

Open a WebSocket to a durable object: connect with ?class= (an exported class of the app) and ?name= (idFromName) or ?id= (32 hex digits). The object's fetch gets the upgrade request and accepts the socket (state.acceptWebSocket) or the socket is closed; each client frame is a webSocketMessage turn of the object, in order, and the client's close is a webSocketClose turn. A reader that falls behind the backlog bound is closed with 4290 after the frames queued before it.

Route: GET /v1/_objects/ws
Auth: App key tenant
CLI: substrio op object.socket

Parameters

No parameters.

Response

A JSON object.

Errors

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

Example

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

`package`

`package.add`

Add an npm package and everything it depends on to a branch in one commit, under node_modules/<name>/, fetched from the registry the platform setting package_registry_origin names: each tarball's SHA-512 checked against dist.integrity, only ES module packages taken, one version of each name (a dependency the branch already holds is reused when it meets the range, else PACKAGE_VERSION_CONFLICT). A function then imports it by name. Answers {branch, version, number, packages: [{name, version}]}.

Route: POST /v1/_packages
Auth: App key tenant
MCP tool: substrio_package_add
CLI: substrio op package.add

Parameters

Name	In	Type	Required	Description
`name`	body	`string`	Yes	The npm package, such as preact or @preact/signals.
`version`	body	`string`	No	A version, a range (^10, ~1.2, >=1 <2) or a dist-tag (next); default: dist-tags.latest.
`branch`	body	`string`	No	The branch to commit on (default: main); it must already hold a version.
`message`	body	`string`	No	What this commit did (default: `package.add` and the packages it wrote).
`expected`	body	`string`	No	The version the branch must still point at (64 hex). 409 when it moved: nothing is written.

Response

A JSON object.

Errors

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

Example

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

`package.remove`

Take one package out of a branch in one commit: node_modules/<name>/ is removed (its dependencies stay until removed by name). Answers {branch, version, number, name}.

Route: POST /v1/_packages/remove
Auth: App key tenant
MCP tool: substrio_package_remove
CLI: substrio op package.remove

Parameters

Name	In	Type	Required	Description
`name`	body	`string`	Yes	The package to take out of node_modules.
`branch`	body	`string`	No	The branch to commit on (default: main).
`message`	body	`string`	No	What this commit did (default: `package.remove` and the name).
`expected`	body	`string`	No	The version the branch must still point at (64 hex). 409 when it moved: nothing is written.

Response

A JSON object.

Errors

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

Example

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

`ref`

`ref.log`

Every move of one name, newest first (the route's {kind}, one of branch, tag or environment, and {name}): the version it moved from, the version it moved to, who moved it, when, and why (create, commit, merge, promote, rollback, restore, delete, protect, import). The log of a deleted name is kept, which is what ref.restore reads. 404 when the name has no log.

Route: GET /v1/_refs/{kind}/{name}/log
Auth: App key tenant
MCP tool: substrio_ref_log
CLI: substrio op ref.log

Parameters

Name	In	Type	Required	Description
`kind`	path	`"branch" \| "tag" \| "environment"`	Yes	Which kind of name.
`name`	path	`string`	Yes	The name, as `branch.list` or `tag.list` names it.
`limit`	query	`integer (0 or more)`	No	the most items to return.

Response

A JSON object.

Errors

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

Example

curl "$SUBSTRIO_URL/v1/_refs/$KIND/$NAME/log" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`ref.restore`

Put a name back to a version its own log holds (the route's {kind} and {name}): name the version, or the log entry by sequence. A name that was deleted is made again, and one that still lives is moved, which is itself one more log entry. A tag is never moved, only made again at the version it marked. Answers {name, version, previous}.

Route: POST /v1/_refs/{kind}/{name}/restore
Auth: App key tenant
MCP tool: substrio_ref_restore
CLI: substrio op ref.restore

Parameters

Name	In	Type	Required	Description
`kind`	path	`"branch" \| "tag" \| "environment"`	Yes	Which kind of name.
`name`	path	`string`	Yes	The name to put back, as `ref.log` shows it.
`version`	body	`string`	No	The version id (64 hex) to put the name back to; it must be one the name's own log holds.
`sequence`	body	`integer`	No	The log entry to put the name back to, as `ref.log` numbers it (instead of version). 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/_refs/$KIND/$NAME/restore" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`source`

`source.edit`

Edit one unit of a branch by exact match and commit it: each edit replaces old (which must occur exactly once, unless replace_all) with new, in order, and all of them land as one commit or none does. EDIT_NO_MATCH names the closest line, EDIT_AMBIGUOUS the count and the lines; both carry the path as field. A text unit only (a binary one is written whole with version.commit). Answers what version.commit answers, with replaced (the occurrences replaced).

Route: POST /v1/_source/edit
Auth: App key tenant
MCP tool: substrio_source_edit
CLI: substrio op source.edit

Parameters

Name	In	Type	Required	Description
`branch`	body	`string`	No	The branch to commit the edit on (default main).
`path`	body	`string`	Yes	The unit to edit, as `source.tree` lists it (functions/hello.js, site/index.html).
`edits`	body	`array of object`	Yes	Applied in order to the unit's text; all or none land, as one commit.
`expected`	body	`string`	No	The version the branch must still point at (64 hex). 409 when it moved: nothing is written.
`message`	body	`string`	No	What this commit did (default: edit <path>).

Response

A JSON object.

Errors

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

Example

curl -X POST "$SUBSTRIO_URL/v1/_source/edit" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"path","edits":[]}'

`source.move`

Move one unit of a branch to a new path as one commit: the old path removed and the same object written at the new one (no byte copied). The new path must be free. Answers what version.commit answers.

Route: POST /v1/_source/move
Auth: App key tenant
MCP tool: substrio_source_move
CLI: substrio op source.move

Parameters

Name	In	Type	Required	Description
`branch`	body	`string`	No	The branch to commit the move on (default main).
`from`	body	`string`	Yes	The unit's path now.
`to`	body	`string`	Yes	Its new path, which no unit holds.
`expected`	body	`string`	No	The version the branch must still point at (64 hex). 409 when it moved: nothing is written.
`message`	body	`string`	No	What this commit did (default: move <from> to <to>).

Response

A JSON object.

Errors

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

Example

curl -X POST "$SUBSTRIO_URL/v1/_source/move" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"from","to":"to"}'

`source.search`

Search the text units of a version (the route's {version}) for pattern: exact bytes, or a regular expression with regex:true (linear time, line by line). glob narrows the files; context adds lines before and after. Answers {version, matches: [{path, line, text, before, after}], count, truncated}, bounded by max_matches and max_bytes.

Route: GET /v1/_commits/{version}/search
Auth: App key tenant
MCP tool: substrio_source_search
CLI: substrio op source.search

Parameters

Name	In	Type	Required	Description
`version`	path	`string`	Yes	The version: its id (64 hex), its number on the branch, a branch name whose head it is, live for the version the app runs, or a sandbox name for the version that sandbox runs.
`max_bytes`	query	`integer (0 or more)`	No	the most response bytes of source (positive, at most 1 MiB); a cut answer says truncated.
`max_matches`	query	`integer (0 or more)`	No	the most matches to return (positive, at most 1024).
`branch`	query	`string`	No	the branch of the app's history to read (default: main).
`glob`	query	`string`	No	only the files whose path matches this pattern (* and ? also match /, so *.css is every CSS file).
`pattern`	query	`string`	No	the text to find (required): exact bytes, or a regular expression with regex:true.
`regex`	query	`boolean`	No	true reads pattern as a regular expression, matched line by line in linear time.
`context`	query	`integer (0 or more)`	No	lines to answer before and after each match (default 0, at most 20).

Response

A JSON object.

Errors

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

Example

curl "$SUBSTRIO_URL/v1/_commits/$VERSION/search" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`source.shell`

Run one shell command over the app, the way you work on a checkout: no process, a POSIX shell subset interpreted in the server. Mounts: /src is the branch's tree (writable, default main, the starting directory), /site the live release's site/ (read only), /files the app's stored files (writable; rm there is refused, file.delete does it). Any other path is refused. Builtins: grep (-r -n -l -L -c -i -v -w -o -q -E -F -A -B -C -m --include --exclude), sed (-n -E -i -e, addresses N $ /re/ ranges !, s///g with \1 groups, p d q a i c y { }), find (-name -iname -path -type -maxdepth -mindepth -empty -exec {} + -delete), cat, head, tail, wc, sort, uniq, cut, tr, diff (unified), ls, cd, pwd, mv, cp, rm, mkdir, touch, echo, printf, tee, test and [ ], xargs, basename, dirname, true, false, commit -m, and js (a script in the app's own runtime with fs.readFile, writeFile, readdir, stat, exists, rm, rename, mkdir on the same mounts; input is stdin). Variables: $PWD $HOME $SRC $SITE $FILES $BRANCH $?. Every /src change of one call lands as ONE commit (message: the command, or commit -m) when the command ends with status 0; any other status, or any refusal, lands nothing. No state is kept between calls. Answers {stdout, stderr, exit_code, offset, truncated, next_offset, commit: {version, number, changed}}; output past the budget is cut with truncated:true and continued with offset. Examples: grep -rn 'TODO' /src; sed -n 10,40p src/app.js; find /src/functions -name '*.js' | xargs sed -i 's/oldName/newName/g'; cat > /src/site/about.html <<'EOF' (lines) EOF; js 'fs.writeFile("notes.txt", input.toUpperCase())' < notes.txt.

Route: POST /v1/_source/shell
Auth: App key tenant
MCP tool: substrio_shell
CLI: substrio op source.shell

Parameters

Name	In	Type	Required	Description
`command`	body	`string`	Yes	One shell command line: pipes, ; && \|\|, redirections, quotes, globs and heredocs, over the builtins (grep, sed, find, cat, head, tail, wc, sort, uniq, cut, tr, diff, ls, mv, cp, rm, mkdir, touch, echo, printf, tee, test, xargs, js and more).
`branch`	body	`string`	No	The branch /src is (default main).
`cwd`	body	`string`	No	The directory the command starts in (default /src).
`offset`	body	`integer`	No	Continue a truncated output from this byte: the next_offset of the last answer. Refused for a command that writes. Minimum 0.
`message`	body	`string`	No	The commit's message (default: the command itself, or what commit -m set).

Response

A JSON object.

Errors

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

Example

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

`source.tree`

List the paths a version holds (the route's {version}: an id, a number, a branch, live or a sandbox name), ordered by path, each with its kind (file or dir). prefix walks only that directory; glob keeps the files whose path matches (* and ? also match /); sizes:true adds each file's size. Answers {version, entries, count}.

Route: GET /v1/_commits/{version}/tree
Auth: App key tenant
MCP tool: substrio_source_tree
CLI: substrio op source.tree

Parameters

Name	In	Type	Required	Description
`version`	path	`string`	Yes	The version: its id (64 hex), its number on the branch, a branch name whose head it is, live for the version the app runs, or a sandbox name for the version that sandbox runs.
`branch`	query	`string`	No	the branch of the app's history to read (default: main).
`prefix`	query	`string`	No	only the paths under this directory (only that subtree is read).
`glob`	query	`string`	No	only the files whose path matches this pattern (* and ? also match /, so *.css is every CSS file).
`sizes`	query	`boolean`	No	true answers each file's size in bytes too (one object header read a file).

Response

A JSON object.

Errors

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

Example

curl "$SUBSTRIO_URL/v1/_commits/$VERSION/tree" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`tag`

`tag.create`

Mark a version with a name that never moves again: name it and say which version (by id or number), or name a branch whose head it marks (default main). 409 when the name is taken. Answers {name, version}.

Route: POST /v1/_tags
Auth: App key tenant
MCP tool: substrio_tag_create
CLI: substrio op tag.create

Parameters

Name	In	Type	Required	Description
`name`	body	`string`	Yes	The tag's name; a tag never moves again.
`version`	body	`string`	No	The version the tag marks, by id (64 hex) or number (default: the head of branch).
`branch`	body	`string`	No	The branch whose head the tag marks when no version is named (default: main).

Response

A JSON object.

Errors

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

Example

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

`tag.list`

List the app's tags by name, each with the version it marks and when it was made; never refuses.

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

`trigger`

`trigger.create`

Create a trigger: body collection, type (insert, update or delete) and function (the function to run). Answers 201 {id, success, created}; 409 for a duplicate or an invalid trigger.

Route: POST /v1/_triggers
Auth: App key tenant
MCP tool: substrio_trigger_create
CLI: substrio op trigger.create

Parameters

Name	In	Type	Required	Description
`collection`	body	`string`	Yes	The collection to watch.
`type`	body	`"insert" \| "update" \| "delete"`	Yes	The change that fires the trigger.
`function`	body	`string`	Yes	The function to run.

Response

A JSON object.

Errors

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

Example

curl -X POST "$SUBSTRIO_URL/v1/_triggers" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"collection":"collection","type":"insert","function":"function"}'

`trigger.delete`

Delete one trigger by id; 404 when it does not exist.

Route: DELETE /v1/_triggers/{id}
Auth: App key tenant
MCP tool: substrio_trigger_delete
CLI: substrio op trigger.delete

Parameters

Name	In	Type	Required	Description
`id`	path	`string or integer`	Yes	The trigger's id, as `trigger.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/_triggers/$ID" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`trigger.list`

List the collection triggers: each runs a function after an insert, update or delete in a collection.

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

`trigger.update`

Enable or disable one trigger: body id and enabled; the route's {id}.

Route: PATCH /v1/_triggers/{id}
Auth: App key tenant
MCP tool: substrio_trigger_update
CLI: substrio op trigger.update

Parameters

Name	In	Type	Required	Description
`id`	path	`string or integer`	Yes
`enabled`	body	`boolean`	Yes

Response

A JSON object.

Errors

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

Example

curl -X PATCH "$SUBSTRIO_URL/v1/_triggers/$ID" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'

`version`

`version.changes`

What one commit changed (the route's {version}): every path that differs from the version it is compared against, added, removed or changed, with the object ids on both sides. against names another version (default: the commit's first parent, so the answer is the commit's own change).

Route: GET /v1/_commits/{version}/changes
Auth: App key tenant
MCP tool: substrio_version_changes
CLI: substrio op version.changes

Parameters

Name	In	Type	Required	Description
`version`	path	`string`	Yes	The version: its id (64 hex), its number on the branch, a branch name whose head it is, live for the version the app runs, or a sandbox name for the version that sandbox runs.
`branch`	query	`string`	No	the branch of the app's history to read (default: main).
`against`	query	`string`	No	the version to compare against, by id or number (default: the version's first parent).

Response

A JSON object.

Errors

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

Example

curl "$SUBSTRIO_URL/v1/_commits/$VERSION/changes" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`version.commit`

Write one commit on a branch of the app's history: the units it changes (bytes as text, as base64, or the id of an object the app already holds, such as the hash site.blob.upload answered), the paths it removes, and what it did. This is how a file is written or deleted: one file is {message, units: [{path: "site/index.html", text: "<h1>Hi</h1>"}]}, one removal is {message, removals: ["site/old.css"]}; no hash is computed by the caller. A function is functions/<name>.js with its routes in functions/<name>.json ({"routes": ["GET /hello"]}), a site file site/<path>. The answered number is promotable at once: version.live.set {version: number}, with sandbox to run it there first. mode changes applies them to the parent version, mode snapshot makes the units the whole content. expected is the version the branch must still point at, so a racing commit is refused rather than overwritten. Answers {version, root, number, generation, branch, blobs_written, trees_written}.

Route: POST /v1/_commits
Auth: App key tenant
MCP tool: substrio_version_commit
CLI: substrio op version.commit

Parameters

Name	In	Type	Required	Description
`message`	body	`string`	Yes	What this commit did.
`branch`	body	`string`	No	The branch to commit on (default: main, which the first commit makes; any other branch is made by `branch.create` first).
`mode`	body	`"changes" \| "snapshot"`	No	changes applies units and removals to the parent version (default); snapshot makes the units the whole content of the new version.
`expected`	body	`string`	No	The version the branch must still point at (64 hex, or an empty string for a branch with no version yet). 409 when it moved: nothing is written.
`units`	body	`array of object`	No	The units this commit writes.
`removals`	body	`array of string`	No	The paths this commit removes (changes mode only).
`checks_green`	body	`boolean`	No	true says the branch's required checks are green, which a protected branch needs to be committed on.

Response

A JSON object.

Errors

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

Example

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

`version.gc`

Collect the objects of the app's history no name reaches any more: what a branch, a tag, an environment, a ref log inside its window and a merge in hand all keep is kept, with every ancestor, tree, unit and patch predecessor under them, and the rest is erased. dry_run works it out and erases nothing. A collection bounded by --gc-sweep stops and is carried on by the next call. Answers {started_at, finished_at, roots, marked, missing, read, collected, bytes, kept_new, foreign, dry_run, complete, resume_after}.

Route: POST /v1/_gc
Auth: App key tenant
MCP tool: substrio_version_gc
CLI: substrio op version.gc

Parameters

Name	In	Type	Required	Description
`dry_run`	body	`boolean`	No	true works the collection out and erases nothing: the answer is what a collection would take.

Response

A JSON object.

Errors

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

Example

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

`version.gc.status`

Where the app's collection got to: the record of the collection in hand, or of the last one that finished, with the same counts version.gc answers. started_at is 0 when the app was never collected.

Route: GET /v1/_gc
Auth: App key tenant
MCP tool: substrio_version_gc_status
CLI: substrio op version.gc.status

Parameters

No parameters.

Response

A JSON object.

Errors

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

Example

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

`version.log`

The commits of a branch, newest first, following first parents: each one's id, number, generation, parents, author, when it was made and what it did. branch names the branch (default main) and limit the most to answer; next_cursor (null on the last page) is the cursor the next page passes. path answers only the commits that changed that one unit (the history of one function, route or file), newest first.

Route: GET /v1/_commits
Auth: App key tenant
MCP tool: substrio_version_log
CLI: substrio op version.log

Parameters

Name	In	Type	Required	Description
`limit`	query	`integer (0 or more)`	No	the most items to return.
`cursor`	query	`string`	No	resume after the previous page: its next_cursor.
`branch`	query	`string`	No	the branch of the app's history to read (default: main).
`path`	query	`string`	No	the unit's path: which unit to read out of the version, or which unit's own commits to list.

Response

A JSON object.

Errors

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

Example

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

`version.show`

One commit's own record (the route's {version}: an id, a number on branch, or a branch name whose head it is): its root tree, its parents, its number, its generation, its author and what it did. units:true answers every path it holds as well.

Route: GET /v1/_commits/{version}
Auth: App key tenant
MCP tool: substrio_version_show
CLI: substrio op version.show

Parameters

Name	In	Type	Required	Description
`version`	path	`string`	Yes	The version: its id (64 hex), its number on the branch, a branch name whose head it is, live for the version the app runs, or a sandbox name for the version that sandbox runs.
`branch`	query	`string`	No	the branch of the app's history to read (default: main).
`units`	query	`boolean`	No	true answers every path the version holds as well as its own record.

Response

A JSON object.

Errors

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

Example

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

`version.unit`

Read one unit (a file) out of a version (the route's {version}: an id, a number, a branch, live or a sandbox name; path the unit): text when the bytes are text, base64 when they are not, with the unit's size in bytes. start_line and end_line (exclusive) answer those lines only, with lines (the unit's line count); offset and length answer a byte range; max_bytes caps the text answered (truncated says it was cut).

Route: GET /v1/_commits/{version}/unit
Auth: App key tenant
MCP tool: substrio_version_unit
CLI: substrio op version.unit

Parameters

Name	In	Type	Required	Description
`version`	path	`string`	Yes	The version: its id (64 hex), its number on the branch, a branch name whose head it is, live for the version the app runs, or a sandbox name for the version that sandbox runs.
`start_line`	query	`integer (0 or more)`	No	first line to read (1-based; required by `function.source.read`, default 1 for `version.unit`).
`end_line`	query	`integer (0 or more)`	No	line to stop before (exclusive; required by `function.source.read`, default the end for `version.unit`).
`max_bytes`	query	`integer (0 or more)`	No	the most response bytes of source (positive, at most 1 MiB); a cut answer says truncated.
`branch`	query	`string`	No	the branch of the app's history to read (default: main).
`path`	query	`string`	No	the unit's path: which unit to read out of the version, or which unit's own commits to list.
`offset`	query	`integer (0 or more)`	No	the first byte to answer (instead of lines; default 0).
`length`	query	`integer (0 or more)`	No	the most bytes to answer from offset (default: the rest).

Response

A JSON object.

Errors

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

Example

curl "$SUBSTRIO_URL/v1/_commits/$VERSION/unit" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"