Files operations. Substrio docs

`file`

`file.delete`

Delete one stored file by its path (the route's tail, as file.list shows it).

Route: DELETE /v1/_files/*
DELETE /v1/files/*
Auth: App key tenant
MCP tool: substrio_file_delete
CLI: substrio op file.delete

Parameters

Name	In	Type	Required	Description
`path`	path	`string`	Yes	The rest of the URL after the route prefix.
`path`	query	`string`	No	the file's path, an alternative to the route's own tail capture.

Response

A JSON object.

Errors

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

Example

curl -X DELETE "$SUBSTRIO_URL/v1/_files/path/to/file" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`file.download`

Download one stored file by path (from file.list).

Route: GET /v1/_files/*
GET /v1/files/*
Auth: App key tenant
MCP tool: substrio_file_download
CLI: substrio op file.download

Parameters

Name	In	Type	Required	Description
`path`	path	`string`	Yes	The rest of the URL after the route prefix.
`path`	query	`string`	No	the file's path, an alternative to the route's own tail capture.
`path`	query	`string`	Yes

Response

A JSON object.

Errors

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

Example

curl "$SUBSTRIO_URL/v1/_files/path/to/file" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`file.list`

List the app's stored files by path (optionally under a prefix): the path is what file.download and file.delete take.

Route: GET /v1/_files
GET /v1/files
Auth: App key tenant
MCP tool: substrio_file_list
CLI: substrio op file.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.
`prefix`	query	`string`	No	only the items whose key starts with this: a file's path, a person's email (absent lists every one).

Response

A JSON object.

Errors

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

Example

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

Rename a stored file's path from one path to another, its content never copied. Refused with FILE_EXISTS when a file is at to, unless replace is true; FILE_NOT_FOUND when none is at from. Answers the file at its new path, as file.upload answers.

Route: POST /v1/_files/move
POST /v1/files/move
Auth: App key tenant
MCP tool: substrio_file_move
CLI: substrio op file.move

Parameters

Name	In	Type	Required	Description
`from`	body	`string`	Yes	The file's path now.
`to`	body	`string`	Yes	Its new path, as `file.upload` takes one.
`replace`	body	`boolean`	No	true replaces a file already at to; false refuses it with FILE_EXISTS. Default `false`.

Response

A JSON object.

Errors

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

Example

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

`file.public.get`

Read a stored file marked public, with no key, on the app's own hosts; a private or missing path is the same 404.

Route: GET /_files/*
Auth: App key or user session; your security rules apply none
CLI: substrio op file.public.get

Parameters

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

Response

A JSON object.

Errors

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

Example

curl "$SUBSTRIO_URL/_files/path/to/file" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`file.site_root.get`

Read the tenant site's index page (the app named by Host or X-Substrio-Tenant).

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

Parameters

No parameters.

Response

A JSON object.

Errors

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

Example

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

`file.static_asset.get`

Read a tenant static asset.

Route: GET /_/*
Auth: App key or user session; your security rules apply none
CLI: substrio op file.static_asset.get

Parameters

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

Response

A JSON object.

Errors

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

Example

curl "$SUBSTRIO_URL/_/path/to/file" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`file.update`

Change a stored file's settings (public, content_type, cache_control) by its path, with no byte of it sent again: its bytes and hash are untouched and an absent setting keeps its value. Answers what file.upload answers; FILE_NOT_FOUND when no file is at the path.

Route: PATCH /v1/_files/*
PATCH /v1/files/*
Auth: App key tenant
MCP tool: substrio_file_update
CLI: substrio op file.update

Parameters

Name	In	Type	Required	Description
`path`	path	`string`	Yes	The rest of the URL after the route prefix.
`path`	query	`string`	No	the file's path, an alternative to the route's own tail capture.
`path`	body	`string`	Yes	The file's path, as `file.list` or `file.upload` returned it.
`public`	body	`boolean`	No	true serves it with no key at /_files/<path> on the app's own hosts; false takes that away.
`content_type`	body	`string`	No	Its MIME type; empty or application/octet-stream is the type its path's extension gives.
`cache_control`	body	`string`	No	Its Cache-Control response header when served; empty clears it (no-cache is sent).

Response

A JSON object.

Errors

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

Example

curl -X PATCH "$SUBSTRIO_URL/v1/_files/path/to/file" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"path"}'

`file.upload`

Upload a file into the app's file storage at its path; see the schema for the body. Answers its path, which file.download and file.delete take.

Route: POST /v1/_files
POST /v1/files
Auth: App key tenant
MCP tool: substrio_file_upload
CLI: substrio op file.upload

Parameters

Name	In	Type	Required	Description
`path`	body	`string`	Yes	Where to store the file, for example docs/report.pdf; no leading or trailing /, no empty, . or .. segment.
`content_type`	body	`string`	No	Its MIME type; application/octet-stream when absent.
`cache_control`	body	`string`	No	Its Cache-Control response header when served.
`public`	body	`boolean`	No	true serves it without authentication.
`data`	body	`string`	Yes	The file's content: the text as is, or with encoding base64 its bytes in standard base64.
`encoding`	body	`"text" \| "base64"`	No	Default `"text"`.

Response

A JSON object.

Errors

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

Example

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

`site`

`site.blob.upload`

Upload one site or function file a version or release names. With no hash the server names it by the GxHash-128 it takes and answers hash and size; a given hash is checked against the bytes. A file over one MCP call goes in parts (offset, total): with no hash the first part answers an upload id that every later part carries. The answered hash is the unit's id in version.commit (units: [{path, id}]), so a large file is committed with no bytes sent twice; a small file is committed as text or base64 instead.

Route: PUT /v1/_site/blobs/{hash}
PUT /v1/_blobs/{hash}
PUT /v1/_site/blobs
Auth: App key tenant
MCP tool: substrio_site_blob_upload
CLI: substrio op site.blob.upload

Parameters

Name	In	Type	Required	Description
`hash`	path	`string`	Yes	GxHash-128 of the file's bytes, lowercase hex, checked against them. Optional: without it the server names the file by the GxHash-128 it takes and answers it as hash. Matches `^[0-9a-f]{32}$`.
`content_base64`	body	`string`	No	MCP: the file's bytes, standard base64, or one part of them. Over HTTP the PUT body is the raw bytes instead.
`offset`	body	`integer`	No	A file too large for one call goes in parts, in order: where this part starts (0, then the bytes received so far). With total. Minimum 0.
`total`	body	`integer`	No	The whole file's size in bytes, the same on every part. The last part stores the file, checks a given hash, and answers hash and size. Minimum 0.
`upload`	body	`string`	No	A file in parts sent with no hash: the id the first part answered, on every later part. Matches `^[0-9a-f]{32}$`.

Response

A JSON object.

Errors

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

Example

curl -X PUT "$SUBSTRIO_URL/v1/_site/blobs/$HASH" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`site.release.activate`

Serve a site release, or roll back to an earlier one.

Route: POST /v1/_site/releases/{id}/activate
Auth: App key tenant
MCP tool: substrio_site_release_activate
CLI: substrio op site.release.activate

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Matches `^[0-9a-f]{32}$`.

Response

A JSON object.

Errors

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

Example

curl -X POST "$SUBSTRIO_URL/v1/_site/releases/$ID/activate" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`site.release.create`

Record a site release from a manifest of file hashes and list the blobs to upload.

Route: POST /v1/_site/releases
Auth: App key tenant
MCP tool: substrio_site_release_create
CLI: substrio op site.release.create

Parameters

Name	In	Type	Required	Description
`files`	body	`array of object`	Yes

Response

A JSON object.

Errors

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

Example

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

`site.release.list`

List the static site releases and which one is active; site.release.activate serves one or rolls back to an earlier one.

Route: GET /v1/_site/releases
Auth: App key tenant
MCP tool: substrio_site_release_list
CLI: substrio op site.release.list

Parameters

No parameters.

Response

A JSON object.

Errors

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

Example

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

`tool`

`tool.install`

Install a tenant's command line tool from its image, named by the SHA-256 of its bytes.

Route: PUT /v1/tools/{name}/{sha256}
Auth: App key tenant
MCP tool: substrio_tool_install
CLI: substrio op tool.install

Parameters

Name	In	Type	Required	Description
`name`	path	`string`	Yes	The tool's name. Matches `^[a-z0-9][a-z0-9_-]*$`.
`sha256`	path	`string`	Yes	SHA-256 of the tool's image, lowercase hex. Matches `^[0-9a-f]{64}$`.
`content_base64`	body	`string`	No	MCP: the tool's image, standard base64. Over HTTP the PUT body is the raw bytes instead.

Response

A JSON object.

Errors

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

Example

curl -X PUT "$SUBSTRIO_URL/v1/tools/$NAME/$SHA256" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`tool.list`

List a tenant's installed tools and which version of each is current.

Route: GET /v1/tools
Auth: App key tenant
MCP tool: substrio_tool_list
CLI: substrio op tool.list

Parameters

No parameters.

Response

A JSON object.

Errors

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

Example

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

`tool.remove`

Remove one installed version of a tenant's tool.

Route: DELETE /v1/tools/{name}/{version}
Auth: App key tenant
MCP tool: substrio_tool_remove
CLI: substrio op tool.remove

Parameters

Name	In	Type	Required	Description
`name`	path	`string`	Yes	The tool's name, as `tool.list` shows it.
`version`	path	`string`	Yes	The 16-hex version `tool.install` or `tool.list` answered. Matches `^[0-9a-f]{16}$`.

Response

A JSON object.

Errors

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

Example

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

`tool.run`

Run an installed version of a tenant's tool inside the jail, under the tenant's limits.

Route: POST /v1/tools/{name}/run
Auth: App key tenant
MCP tool: substrio_tool_run
CLI: substrio op tool.run

Parameters

Name	In	Type	Required	Description
`name`	path	`string`	Yes	The tool's name, as `tool.list` names it.
`version`	body	`string`	No	The tool's version; absent runs the current one. Matches `^[0-9a-f]{16}$`.
`args`	body	`array of string`	No	The tool's argv[1..], exactly as given; no shell, no splitting.
`env`	body	`object`	No	The tool's environment; the server's own is never inherited.
`stdin`	body	`any`	No	A string of raw bytes, or {"base64":...} for bytes that aren't valid UTF-8.
`limits`	body	`object`	No	Per-run limits, over this tenant's effective ones; each is clamped to min(requested, effective); 0 or absent takes the effective value.

Response

A JSON object.

Errors

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

Example

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