> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> Every route of the Mirage HTTP API, generated from openapi.yaml.

Routes are under `/v1` and take and return JSON. Send
`Authorization: Bearer <token>` when the server has a token set; see the
[overview](https://docs.mirage.strukto.ai/api/overview.md) for launching a server, auth and errors. The
[OpenAPI document](https://github.com/strukto-ai/mirage/blob/main/docs/openapi.yaml)
is the contract both servers are checked against.

Rows marked **daemon and hosted** are also served by the hosted API.
An error answers `{detail, errno?, refusal?}`; `429` adds `Retry-After`.

> [accordion] GET /v1/workspaces
>
> List workspaces · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/workspaces/list-workspaces.md)
>
> **Responses**
>
> `200` OK
>
> `application/json` `WorkspaceBrief[]`
>
> **id** `string` *required*
>
> **mode** `string` *required*
>
> **mount\_count** `integer` *required*
>
> **session\_count** `integer` *required*
>
> **created\_at** `number` *required*
>
> `401` The token is missing or wrong
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces
>
> Create a workspace · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/workspaces/create-a-workspace.md)
>
> Create a workspace, or answer the live one created from this config.
>
> Creating is idempotent for one config: an id already held by a
> workspace created from an identical config answers that workspace
> with 200, so a client that names its workspace can run again and
> reach it; an id held by anything else is refused with 409. The
> server's policies judge the config as written (`pre_workspace`)
> before any of it is built: a refusal is 403 with its reason, and
> `explain` answers what they say without creating anything.
>
> **Query**
>
> **explain** `boolean`
>
> Return what the call would do without running it.
>
> **Body** `application/json`
>
> **config** `WorkspaceConfig | null`
>
> **template** `string | null`
>
> **id** `string | null`
>
> **Responses**
>
> `200` An identical retry answers the existing workspace; with explain=true, what the server's policies say about the config
>
> `application/json` `WorkspaceDetail | object`
>
> *WorkspaceDetail*
>
> **id** `string` *required*
>
> **mode** `string` *required*
>
> **created\_at** `number` *required*
>
> **fuse\_mountpoints** `object`
>
> **system\_time** `string | null`
>
> **sessions** `SessionSummary[]`
>
> **mounts** `MountSummary[]`
>
> **internals** `WorkspaceInternals | null`
>
> `201` Created
>
> `application/json` `WorkspaceDetail`
>
> **id** `string` *required*
>
> **mode** `string` *required*
>
> **created\_at** `number` *required*
>
> **fuse\_mountpoints** `object`
>
> **system\_time** `string | null`
>
> **sessions** `SessionSummary[]`
>
> **mounts** `MountSummary[]`
>
> **internals** `WorkspaceInternals | null`
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `409` The id or name is taken, the workspace is busy, or a file changed since it was read
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions
>
> `503` The server is at max\_workspaces, or shutting down

> [accordion] GET /v1/workspaces/\{workspace\_id}
>
> Get a workspace · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/workspaces/get-a-workspace.md)
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **verbose** `boolean`
>
> **Responses**
>
> `200` OK
>
> `application/json` `WorkspaceDetail`
>
> **id** `string` *required*
>
> **mode** `string` *required*
>
> **created\_at** `number` *required*
>
> **fuse\_mountpoints** `object`
>
> **system\_time** `string | null`
>
> **sessions** `SessionSummary[]`
>
> **mounts** `MountSummary[]`
>
> **internals** `WorkspaceInternals | null`
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] DELETE /v1/workspaces/\{workspace\_id}
>
> Delete a workspace · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/workspaces/delete-a-workspace.md)
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Responses**
>
> `200` OK
>
> `application/json` `DeleteWorkspaceResponse`
>
> **id** `string` *required*
>
> **closed\_at** `number` *required*
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/cancel
>
> Cancel a workspace's lines · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/workspaces/cancel-a-workspaces-lines.md)
>
> Cancel every session's running and queued lines; all stay open.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Responses**
>
> `200` OK
>
> `application/json` `CancelLinesResponse`
>
> **canceled** `integer` *required*
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] PUT /v1/workspaces/\{workspace\_id}/clis/\{name}
>
> Install an MCP CLI
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/workspaces/install-an-mcp-cli.md)
>
> Install an MCP server as a CLI on the live workspace.
>
> The body is one `clis:` entry, `cli: mcp` with its config, as a
> config file states it. Its pointers resolve and its tools are listed
> under the workspace's network. A name already installed answers 409.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **name** `string` *required*
>
> **Body** `application/json`
>
> **cli** `string | null`
>
> **script** `string | null`
>
> **runtime** `string | null`
>
> **config** `object`
>
> **Responses**
>
> `200` OK
>
> `application/json` `object`
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] DELETE /v1/workspaces/\{workspace\_id}/clis/\{name}
>
> Remove an MCP CLI
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/workspaces/remove-an-mcp-cli.md)
>
> Remove an MCP CLI from the live workspace.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **name** `string` *required*
>
> **Responses**
>
> `200` OK
>
> `application/json` `object`
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/close
>
> Close a workspace
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/workspaces/close-a-workspace.md)
>
> Close the workspace and keep its state for the owner to reopen.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Responses**
>
> `200` OK
>
> `application/json` `DeleteWorkspaceResponse`
>
> **id** `string` *required*
>
> **closed\_at** `number` *required*
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] GET /v1/workspaces/\{workspace\_id}/history
>
> Read a workspace's history
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/workspaces/read-a-workspaces-history.md)
>
> The workspace's recorded history, oldest first: a `command`
> entry for every line its sessions ran, and with `vfs` a `vfs`
> entry for every call a line made to a mount. Read on the workspace's
> own loop.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> Only this session's records; every session's when absent.
>
> **since** `integer | null`
>
> **last** `integer | null`
>
> **vfs** `boolean`
>
> **Responses**
>
> `200` OK
>
> `application/json` `object[]`
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/kill
>
> Kill a workspace's jobs
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/workspaces/kill-a-workspaces-jobs.md)
>
> Kill every session's background jobs and runners.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Responses**
>
> `200` OK
>
> `application/json` `KillJobsResponse`
>
> **killed** `integer` *required*
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] PUT /v1/workspaces/\{workspace\_id}/profiles/\{name}
>
> Set a profile
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/workspaces/set-a-profile.md)
>
> Define a named profile on the live workspace, or replace it.
>
> Only the live table changes: a session moves when it is updated
> onto the name, and the workspace's config is never rewritten.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **name** `string` *required*
>
> **Body** `application/json`
>
> **cwd** `string | null`
>
> **env** `object | null`
>
> **mounts** `object | null`
>
> **paths** `PathsBlock | null`
>
> **vars** `VarsBlock | null`
>
> **commands** `CommandsBlock | null`
>
> **policy** `object | null`
>
> **command\_limits** `object | null`
>
> **processes** `ProcessPermissions | null`
>
> **network** `boolean | object | null`
>
> **Responses**
>
> `200` OK
>
> `application/json` `object`
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] GET /v1/workspaces/\{workspace\_id}/sessions
>
> List sessions · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/sessions/list-sessions.md)
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Responses**
>
> `200` OK
>
> `application/json` `SessionResponse[]`
>
> **session\_id** `string` *required*
>
> **cwd** `string` *required*
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/sessions
>
> Create a session · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/sessions/create-a-session.md)
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Body** `application/json`
>
> **session\_id** `string | null`
>
> **mounts** `object | null`
>
> **profile** `string | null`
>
> **Responses**
>
> `201` Created
>
> `application/json` `SessionResponse`
>
> **session\_id** `string` *required*
>
> **cwd** `string` *required*
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] PATCH /v1/workspaces/\{workspace\_id}/sessions/\{session\_id}
>
> Change a session's profile
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/sessions/change-a-sessions-profile.md)
>
> Replace the session's profile; its cwd, env and history stay.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **session\_id** `string` *required*
>
> **Body** `application/json`
>
> **profile** `string | SessionProfile | null` *required*
>
> **Responses**
>
> `200` OK
>
> `application/json` `SessionResponse`
>
> **session\_id** `string` *required*
>
> **cwd** `string` *required*
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] DELETE /v1/workspaces/\{workspace\_id}/sessions/\{session\_id}
>
> Delete a session
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/sessions/delete-a-session.md)
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **session\_id** `string` *required*
>
> **Responses**
>
> `200` OK
>
> `application/json` `DeleteSessionResponse`
>
> **session\_id** `string` *required*
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/sessions/\{session\_id}/cancel
>
> Cancel a session's lines
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/sessions/cancel-a-sessions-lines.md)
>
> Cancel the session's running and queued lines, from every entry point.
>
> The session stays open; returns once those lines have ended.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **session\_id** `string` *required*
>
> **Responses**
>
> `200` OK
>
> `application/json` `CancelLinesResponse`
>
> **canceled** `integer` *required*
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/sessions/\{session\_id}/kill
>
> Kill a session's jobs
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/sessions/kill-a-sessions-jobs.md)
>
> Kill the session's background jobs and runners; it stays open.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **session\_id** `string` *required*
>
> **Responses**
>
> `200` OK
>
> `application/json` `KillJobsResponse`
>
> **killed** `integer` *required*
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/glob
>
> Match paths · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/shell/match-paths.md)
>
> `session.glob`: every path a pattern matches, as the session
> sees them.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **Body** `application/json`
>
> **pattern** `string` *required*
>
> A pathname pattern, such as /src/\*\*/\*.py.
>
> **Responses**
>
> `200` Every matching path visible to the session
>
> `application/json` `string[]`
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/shell
>
> Run a shell line · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/shell/run-a-shell-line.md)
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **explain** `boolean`
>
> Return what the call would do without running it.
>
> **stream** `boolean`
>
> Stream stdout, stderr and the final status as NDJSON. Cannot be combined with explain.
>
> **Body** `application/json`
>
> **command** `string` *required*
>
> The line.
>
> **cwd** `string`
>
> A working directory for this line only.
>
> **runtime** `string`
>
> Run the line on this runtime, by name, instead of the one routing picks.
>
> **record** `boolean`
>
> Add the line to the session's history.
>
> **Body** `multipart/form-data`
>
> **request** `ShellRequest` *required*
>
> **stdin** `string`
>
> Up to 64 MiB, read as it arrives.
>
> **Responses**
>
> `200` The line's result; with explain=true, its explanation; with stream=true, an NDJSON stream ending in a status record
>
> `application/json` `ShellResult | ShellExplanation`
>
> *ShellResult*
>
> **kind** `string` *required*
>
> **exit\_code** `integer` *required*
>
> **stdout** `string` *required*
>
> **stderr** `string` *required*
>
> **refusal** `object | null`
>
> *ShellExplanation*
>
> **type** `string`
>
> line, command or vfs.
>
> **outcome** `string` *required*
>
> **reason** `string`
>
> Why, in the deciding policy's words.
>
> **source** `string`
>
> Where in the profile the deciding rule is written.
>
> **answers** `object[]`
>
> Every policy's answer.
>
> **refusal** `object | null`
>
> **line** `string`
>
> **exit\_code** `integer`
>
> What the line is refused with, 0 when it runs.
>
> **stderr** `string`
>
> **node** `object`
>
> The parsed line and each command's explanation.
>
> `application/x-ndjson` `string`
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/vfs/append
>
> VFS append
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/vfs/vfs-append.md)
>
> Append bytes to a file.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **explain** `boolean`
>
> Return what the call would do without running it.
>
> **Body** `application/json`
>
> **path** `string` *required*
>
> **data** `string (base64)` *required*
>
> The bytes, base64-encoded.
>
> **Responses**
>
> `200` What the call returns; with explain=true, its explanation
>
> `application/json` `null | VfsExplanation`
>
> *VfsExplanation*
>
> **type** `string`
>
> line, command or vfs.
>
> **outcome** `string` *required*
>
> **reason** `string`
>
> Why, in the deciding policy's words.
>
> **source** `string`
>
> Where in the profile the deciding rule is written.
>
> **answers** `object[]`
>
> Every policy's answer.
>
> **refusal** `object | null`
>
> **call** `string`
>
> **paths** `string[]`
>
> **error** `string`
>
> The errno name the call would raise, empty when it runs.
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/vfs/create
>
> VFS create
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/vfs/vfs-create.md)
>
> Create an empty file.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **explain** `boolean`
>
> Return what the call would do without running it.
>
> **Body** `application/json`
>
> **path** `string` *required*
>
> **Responses**
>
> `200` What the call returns; with explain=true, its explanation
>
> `application/json` `null | VfsExplanation`
>
> *VfsExplanation*
>
> **type** `string`
>
> line, command or vfs.
>
> **outcome** `string` *required*
>
> **reason** `string`
>
> Why, in the deciding policy's words.
>
> **source** `string`
>
> Where in the profile the deciding rule is written.
>
> **answers** `object[]`
>
> Every policy's answer.
>
> **refusal** `object | null`
>
> **call** `string`
>
> **paths** `string[]`
>
> **error** `string`
>
> The errno name the call would raise, empty when it runs.
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/vfs/exists
>
> VFS exists
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/vfs/vfs-exists.md)
>
> Whether a path exists.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **explain** `boolean`
>
> Return what the call would do without running it.
>
> **Body** `application/json`
>
> **path** `string` *required*
>
> **Responses**
>
> `200` What the call returns; with explain=true, its explanation
>
> `application/json` `boolean | VfsExplanation`
>
> *VfsExplanation*
>
> **type** `string`
>
> line, command or vfs.
>
> **outcome** `string` *required*
>
> **reason** `string`
>
> Why, in the deciding policy's words.
>
> **source** `string`
>
> Where in the profile the deciding rule is written.
>
> **answers** `object[]`
>
> Every policy's answer.
>
> **refusal** `object | null`
>
> **call** `string`
>
> **paths** `string[]`
>
> **error** `string`
>
> The errno name the call would raise, empty when it runs.
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/vfs/getxattr
>
> VFS getxattr
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/vfs/vfs-getxattr.md)
>
> One extended attribute's value.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **explain** `boolean`
>
> Return what the call would do without running it.
>
> **Body** `application/json`
>
> **path** `string` *required*
>
> **name** `string` *required*
>
> **nofollow** `boolean`
>
> **Responses**
>
> `200` What the call returns; with explain=true, its explanation
>
> `application/json` `string | VfsExplanation`
>
> *VfsExplanation*
>
> **type** `string`
>
> line, command or vfs.
>
> **outcome** `string` *required*
>
> **reason** `string`
>
> Why, in the deciding policy's words.
>
> **source** `string`
>
> Where in the profile the deciding rule is written.
>
> **answers** `object[]`
>
> Every policy's answer.
>
> **refusal** `object | null`
>
> **call** `string`
>
> **paths** `string[]`
>
> **error** `string`
>
> The errno name the call would raise, empty when it runs.
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/vfs/is\_dir
>
> VFS is\_dir
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/vfs/vfs-is_dir.md)
>
> Whether a path is a directory.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **explain** `boolean`
>
> Return what the call would do without running it.
>
> **Body** `application/json`
>
> **path** `string` *required*
>
> **Responses**
>
> `200` What the call returns; with explain=true, its explanation
>
> `application/json` `boolean | VfsExplanation`
>
> *VfsExplanation*
>
> **type** `string`
>
> line, command or vfs.
>
> **outcome** `string` *required*
>
> **reason** `string`
>
> Why, in the deciding policy's words.
>
> **source** `string`
>
> Where in the profile the deciding rule is written.
>
> **answers** `object[]`
>
> Every policy's answer.
>
> **refusal** `object | null`
>
> **call** `string`
>
> **paths** `string[]`
>
> **error** `string`
>
> The errno name the call would raise, empty when it runs.
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/vfs/is\_file
>
> VFS is\_file
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/vfs/vfs-is_file.md)
>
> Whether a path is a file.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **explain** `boolean`
>
> Return what the call would do without running it.
>
> **Body** `application/json`
>
> **path** `string` *required*
>
> **Responses**
>
> `200` What the call returns; with explain=true, its explanation
>
> `application/json` `boolean | VfsExplanation`
>
> *VfsExplanation*
>
> **type** `string`
>
> line, command or vfs.
>
> **outcome** `string` *required*
>
> **reason** `string`
>
> Why, in the deciding policy's words.
>
> **source** `string`
>
> Where in the profile the deciding rule is written.
>
> **answers** `object[]`
>
> Every policy's answer.
>
> **refusal** `object | null`
>
> **call** `string`
>
> **paths** `string[]`
>
> **error** `string`
>
> The errno name the call would raise, empty when it runs.
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/vfs/list\_files
>
> VFS list\_files
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/vfs/vfs-list_files.md)
>
> The names of a directory's files.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **explain** `boolean`
>
> Return what the call would do without running it.
>
> **Body** `application/json`
>
> **path** `string` *required*
>
> **Responses**
>
> `200` What the call returns; with explain=true, its explanation
>
> `application/json` `string[] | VfsExplanation`
>
> *VfsExplanation*
>
> **type** `string`
>
> line, command or vfs.
>
> **outcome** `string` *required*
>
> **reason** `string`
>
> Why, in the deciding policy's words.
>
> **source** `string`
>
> Where in the profile the deciding rule is written.
>
> **answers** `object[]`
>
> Every policy's answer.
>
> **refusal** `object | null`
>
> **call** `string`
>
> **paths** `string[]`
>
> **error** `string`
>
> The errno name the call would raise, empty when it runs.
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/vfs/listxattr
>
> VFS listxattr
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/vfs/vfs-listxattr.md)
>
> A path's extended attribute names.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **explain** `boolean`
>
> Return what the call would do without running it.
>
> **Body** `application/json`
>
> **path** `string` *required*
>
> **nofollow** `boolean`
>
> **Responses**
>
> `200` What the call returns; with explain=true, its explanation
>
> `application/json` `string[] | VfsExplanation`
>
> *VfsExplanation*
>
> **type** `string`
>
> line, command or vfs.
>
> **outcome** `string` *required*
>
> **reason** `string`
>
> Why, in the deciding policy's words.
>
> **source** `string`
>
> Where in the profile the deciding rule is written.
>
> **answers** `object[]`
>
> Every policy's answer.
>
> **refusal** `object | null`
>
> **call** `string`
>
> **paths** `string[]`
>
> **error** `string`
>
> The errno name the call would raise, empty when it runs.
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/vfs/mkdir
>
> VFS mkdir
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/vfs/vfs-mkdir.md)
>
> Make a directory.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **explain** `boolean`
>
> Return what the call would do without running it.
>
> **Body** `application/json`
>
> **path** `string` *required*
>
> **Responses**
>
> `200` What the call returns; with explain=true, its explanation
>
> `application/json` `null | VfsExplanation`
>
> *VfsExplanation*
>
> **type** `string`
>
> line, command or vfs.
>
> **outcome** `string` *required*
>
> **reason** `string`
>
> Why, in the deciding policy's words.
>
> **source** `string`
>
> Where in the profile the deciding rule is written.
>
> **answers** `object[]`
>
> Every policy's answer.
>
> **refusal** `object | null`
>
> **call** `string`
>
> **paths** `string[]`
>
> **error** `string`
>
> The errno name the call would raise, empty when it runs.
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/vfs/pwrite
>
> VFS pwrite
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/vfs/vfs-pwrite.md)
>
> Write bytes into a file at an offset.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **explain** `boolean`
>
> Return what the call would do without running it.
>
> **Body** `application/json`
>
> **path** `string` *required*
>
> **data** `string (base64)` *required*
>
> The bytes, base64-encoded.
>
> **offset** `integer` *required*
>
> **Responses**
>
> `200` What the call returns; with explain=true, its explanation
>
> `application/json` `null | VfsExplanation`
>
> *VfsExplanation*
>
> **type** `string`
>
> line, command or vfs.
>
> **outcome** `string` *required*
>
> **reason** `string`
>
> Why, in the deciding policy's words.
>
> **source** `string`
>
> Where in the profile the deciding rule is written.
>
> **answers** `object[]`
>
> Every policy's answer.
>
> **refusal** `object | null`
>
> **call** `string`
>
> **paths** `string[]`
>
> **error** `string`
>
> The errno name the call would raise, empty when it runs.
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/vfs/read
>
> VFS read
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/vfs/vfs-read.md)
>
> Read a file's bytes, from an offset.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **explain** `boolean`
>
> Return what the call would do without running it.
>
> **Body** `application/json`
>
> **path** `string` *required*
>
> **offset** `integer`
>
> **size** `integer | null`
>
> **raw** `boolean`
>
> **stream** `boolean`
>
> Answer the bytes themselves as application/octet-stream.
>
> **Responses**
>
> `200` What the call returns; with explain=true, its explanation
>
> `application/json` `string | VfsExplanation`
>
> *VfsExplanation*
>
> **type** `string`
>
> line, command or vfs.
>
> **outcome** `string` *required*
>
> **reason** `string`
>
> Why, in the deciding policy's words.
>
> **source** `string`
>
> Where in the profile the deciding rule is written.
>
> **answers** `object[]`
>
> Every policy's answer.
>
> **refusal** `object | null`
>
> **call** `string`
>
> **paths** `string[]`
>
> **error** `string`
>
> The errno name the call would raise, empty when it runs.
>
> `application/octet-stream` `string`
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/vfs/readdir
>
> VFS readdir
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/vfs/vfs-readdir.md)
>
> A directory's entries.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **explain** `boolean`
>
> Return what the call would do without running it.
>
> **Body** `application/json`
>
> **path** `string` *required*
>
> **Responses**
>
> `200` What the call returns; with explain=true, its explanation
>
> `application/json` `string[] | VfsExplanation`
>
> *VfsExplanation*
>
> **type** `string`
>
> line, command or vfs.
>
> **outcome** `string` *required*
>
> **reason** `string`
>
> Why, in the deciding policy's words.
>
> **source** `string`
>
> Where in the profile the deciding rule is written.
>
> **answers** `object[]`
>
> Every policy's answer.
>
> **refusal** `object | null`
>
> **call** `string`
>
> **paths** `string[]`
>
> **error** `string`
>
> The errno name the call would raise, empty when it runs.
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/vfs/readlink
>
> VFS readlink
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/vfs/vfs-readlink.md)
>
> Where a symbolic link points.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **explain** `boolean`
>
> Return what the call would do without running it.
>
> **Body** `application/json`
>
> **path** `string` *required*
>
> **Responses**
>
> `200` What the call returns; with explain=true, its explanation
>
> `application/json` `string | VfsExplanation`
>
> *VfsExplanation*
>
> **type** `string`
>
> line, command or vfs.
>
> **outcome** `string` *required*
>
> **reason** `string`
>
> Why, in the deciding policy's words.
>
> **source** `string`
>
> Where in the profile the deciding rule is written.
>
> **answers** `object[]`
>
> Every policy's answer.
>
> **refusal** `object | null`
>
> **call** `string`
>
> **paths** `string[]`
>
> **error** `string`
>
> The errno name the call would raise, empty when it runs.
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/vfs/removexattr
>
> VFS removexattr
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/vfs/vfs-removexattr.md)
>
> Remove an extended attribute.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **explain** `boolean`
>
> Return what the call would do without running it.
>
> **Body** `application/json`
>
> **path** `string` *required*
>
> **name** `string` *required*
>
> **nofollow** `boolean`
>
> **Responses**
>
> `200` What the call returns; with explain=true, its explanation
>
> `application/json` `null | VfsExplanation`
>
> *VfsExplanation*
>
> **type** `string`
>
> line, command or vfs.
>
> **outcome** `string` *required*
>
> **reason** `string`
>
> Why, in the deciding policy's words.
>
> **source** `string`
>
> Where in the profile the deciding rule is written.
>
> **answers** `object[]`
>
> Every policy's answer.
>
> **refusal** `object | null`
>
> **call** `string`
>
> **paths** `string[]`
>
> **error** `string`
>
> The errno name the call would raise, empty when it runs.
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/vfs/rename
>
> VFS rename
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/vfs/vfs-rename.md)
>
> Rename a path within its mount.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **explain** `boolean`
>
> Return what the call would do without running it.
>
> **Body** `application/json`
>
> **src** `string` *required*
>
> **dst** `string` *required*
>
> **Responses**
>
> `200` What the call returns; with explain=true, its explanation
>
> `application/json` `null | VfsExplanation`
>
> *VfsExplanation*
>
> **type** `string`
>
> line, command or vfs.
>
> **outcome** `string` *required*
>
> **reason** `string`
>
> Why, in the deciding policy's words.
>
> **source** `string`
>
> Where in the profile the deciding rule is written.
>
> **answers** `object[]`
>
> Every policy's answer.
>
> **refusal** `object | null`
>
> **call** `string`
>
> **paths** `string[]`
>
> **error** `string`
>
> The errno name the call would raise, empty when it runs.
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/vfs/rmdir
>
> VFS rmdir
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/vfs/vfs-rmdir.md)
>
> Remove an empty directory.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **explain** `boolean`
>
> Return what the call would do without running it.
>
> **Body** `application/json`
>
> **path** `string` *required*
>
> **Responses**
>
> `200` What the call returns; with explain=true, its explanation
>
> `application/json` `null | VfsExplanation`
>
> *VfsExplanation*
>
> **type** `string`
>
> line, command or vfs.
>
> **outcome** `string` *required*
>
> **reason** `string`
>
> Why, in the deciding policy's words.
>
> **source** `string`
>
> Where in the profile the deciding rule is written.
>
> **answers** `object[]`
>
> Every policy's answer.
>
> **refusal** `object | null`
>
> **call** `string`
>
> **paths** `string[]`
>
> **error** `string`
>
> The errno name the call would raise, empty when it runs.
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/vfs/setattr
>
> VFS setattr
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/vfs/vfs-setattr.md)
>
> Change a path's mode, owner or times.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **explain** `boolean`
>
> Return what the call would do without running it.
>
> **Body** `application/json`
>
> **path** `string` *required*
>
> **mode** `integer`
>
> **uid** `integer | string`
>
> **gid** `integer | string`
>
> **atime** `string`
>
> **mtime** `string`
>
> **nofollow** `boolean`
>
> **Responses**
>
> `200` What the call returns; with explain=true, its explanation
>
> `application/json` `object | VfsExplanation`
>
> *VfsExplanation*
>
> **type** `string`
>
> line, command or vfs.
>
> **outcome** `string` *required*
>
> **reason** `string`
>
> Why, in the deciding policy's words.
>
> **source** `string`
>
> Where in the profile the deciding rule is written.
>
> **answers** `object[]`
>
> Every policy's answer.
>
> **refusal** `object | null`
>
> **call** `string`
>
> **paths** `string[]`
>
> **error** `string`
>
> The errno name the call would raise, empty when it runs.
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/vfs/setxattr
>
> VFS setxattr
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/vfs/vfs-setxattr.md)
>
> Set an extended attribute.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **explain** `boolean`
>
> Return what the call would do without running it.
>
> **Body** `application/json`
>
> **path** `string` *required*
>
> **name** `string` *required*
>
> **value** `string (base64)` *required*
>
> The bytes, base64-encoded.
>
> **create** `boolean`
>
> **replace** `boolean`
>
> **nofollow** `boolean`
>
> **Responses**
>
> `200` What the call returns; with explain=true, its explanation
>
> `application/json` `null | VfsExplanation`
>
> *VfsExplanation*
>
> **type** `string`
>
> line, command or vfs.
>
> **outcome** `string` *required*
>
> **reason** `string`
>
> Why, in the deciding policy's words.
>
> **source** `string`
>
> Where in the profile the deciding rule is written.
>
> **answers** `object[]`
>
> Every policy's answer.
>
> **refusal** `object | null`
>
> **call** `string`
>
> **paths** `string[]`
>
> **error** `string`
>
> The errno name the call would raise, empty when it runs.
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/vfs/stat
>
> VFS stat
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/vfs/vfs-stat.md)
>
> A path's metadata.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **explain** `boolean`
>
> Return what the call would do without running it.
>
> **Body** `application/json`
>
> **path** `string` *required*
>
> **nofollow** `boolean`
>
> **Responses**
>
> `200` What the call returns; with explain=true, its explanation
>
> `application/json` `object | VfsExplanation`
>
> *VfsExplanation*
>
> **type** `string`
>
> line, command or vfs.
>
> **outcome** `string` *required*
>
> **reason** `string`
>
> Why, in the deciding policy's words.
>
> **source** `string`
>
> Where in the profile the deciding rule is written.
>
> **answers** `object[]`
>
> Every policy's answer.
>
> **refusal** `object | null`
>
> **call** `string`
>
> **paths** `string[]`
>
> **error** `string`
>
> The errno name the call would raise, empty when it runs.
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/vfs/symlink
>
> VFS symlink
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/vfs/vfs-symlink.md)
>
> Make a symbolic link at a path.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **explain** `boolean`
>
> Return what the call would do without running it.
>
> **Body** `application/json`
>
> **path** `string` *required*
>
> **target** `string` *required*
>
> **Responses**
>
> `200` What the call returns; with explain=true, its explanation
>
> `application/json` `null | VfsExplanation`
>
> *VfsExplanation*
>
> **type** `string`
>
> line, command or vfs.
>
> **outcome** `string` *required*
>
> **reason** `string`
>
> Why, in the deciding policy's words.
>
> **source** `string`
>
> Where in the profile the deciding rule is written.
>
> **answers** `object[]`
>
> Every policy's answer.
>
> **refusal** `object | null`
>
> **call** `string`
>
> **paths** `string[]`
>
> **error** `string`
>
> The errno name the call would raise, empty when it runs.
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/vfs/truncate
>
> VFS truncate
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/vfs/vfs-truncate.md)
>
> Cut or extend a file to a length.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **explain** `boolean`
>
> Return what the call would do without running it.
>
> **Body** `application/json`
>
> **path** `string` *required*
>
> **length** `integer` *required*
>
> **Responses**
>
> `200` What the call returns; with explain=true, its explanation
>
> `application/json` `null | VfsExplanation`
>
> *VfsExplanation*
>
> **type** `string`
>
> line, command or vfs.
>
> **outcome** `string` *required*
>
> **reason** `string`
>
> Why, in the deciding policy's words.
>
> **source** `string`
>
> Where in the profile the deciding rule is written.
>
> **answers** `object[]`
>
> Every policy's answer.
>
> **refusal** `object | null`
>
> **call** `string`
>
> **paths** `string[]`
>
> **error** `string`
>
> The errno name the call would raise, empty when it runs.
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/vfs/unlink
>
> VFS unlink
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/vfs/vfs-unlink.md)
>
> Remove a file.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **explain** `boolean`
>
> Return what the call would do without running it.
>
> **Body** `application/json`
>
> **path** `string` *required*
>
> **Responses**
>
> `200` What the call returns; with explain=true, its explanation
>
> `application/json` `null | VfsExplanation`
>
> *VfsExplanation*
>
> **type** `string`
>
> line, command or vfs.
>
> **outcome** `string` *required*
>
> **reason** `string`
>
> Why, in the deciding policy's words.
>
> **source** `string`
>
> Where in the profile the deciding rule is written.
>
> **answers** `object[]`
>
> Every policy's answer.
>
> **refusal** `object | null`
>
> **call** `string`
>
> **paths** `string[]`
>
> **error** `string`
>
> The errno name the call would raise, empty when it runs.
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/vfs/write
>
> VFS write
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/vfs/vfs-write.md)
>
> Write a file's bytes, replacing what it held.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **explain** `boolean`
>
> Return what the call would do without running it.
>
> **Body** `application/json`
>
> **path** `string` *required*
>
> **data** `string (base64)` *required*
>
> The bytes, base64-encoded.
>
> **Responses**
>
> `200` What the call returns; with explain=true, its explanation
>
> `application/json` `null | VfsExplanation`
>
> *VfsExplanation*
>
> **type** `string`
>
> line, command or vfs.
>
> **outcome** `string` *required*
>
> **reason** `string`
>
> Why, in the deciding policy's words.
>
> **source** `string`
>
> Where in the profile the deciding rule is written.
>
> **answers** `object[]`
>
> Every policy's answer.
>
> **refusal** `object | null`
>
> **call** `string`
>
> **paths** `string[]`
>
> **error** `string`
>
> The errno name the call would raise, empty when it runs.
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/vfs/\{name}
>
> Call any VFS function
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/vfs/call-any-vfs-function.md)
>
> Call a declared VFS function using the ordinary session and policy gate.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **name** `string` *required*
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **Body** `application/json`
>
> **path** `string` *required*
>
> The path the function acts on.
>
> **kwargs** `object`
>
> The function's keyword arguments, Python only.
>
> **Responses**
>
> `200` OK
>
> `application/json` `any`
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/tools/edit
>
> Edit tool
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/tools/edit-tool.md)
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **Body** `application/json`
>
> **path** `string` *required*
>
> Absolute path of the file to edit.
>
> **old\_string** `string` *required*
>
> The exact text to replace.
>
> **new\_string** `string` *required*
>
> The text to put in its place.
>
> **replace\_all** `boolean`
>
> Replace every occurrence instead of exactly one (default false).
>
> **Responses**
>
> `200` OK
>
> `application/json` `ToolResponse`
>
> **text** `string` *required*
>
> **is\_error** `boolean` *required*
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/tools/glob
>
> Glob tool
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/tools/glob-tool.md)
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **Body** `application/json`
>
> **pattern** `string` *required*
>
> Pathname pattern such as \*\*/*.py or src/*.ts; a relative one is matched under path.
>
> **path** `string`
>
> Absolute path of the directory a relative pattern is matched under (default /).
>
> **Responses**
>
> `200` OK
>
> `application/json` `ToolResponse`
>
> **text** `string` *required*
>
> **is\_error** `boolean` *required*
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/tools/grep
>
> Grep tool
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/tools/grep-tool.md)
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **Body** `application/json`
>
> **pattern** `string` *required*
>
> Regular expression to search for.
>
> **path** `string` *required*
>
> Absolute path of the file or directory to search under.
>
> **ignore\_case** `boolean`
>
> Match case-insensitively (-i).
>
> **fixed\_strings** `boolean`
>
> Read pattern as a literal string, not a regex (-F).
>
> **include** `string`
>
> Search only files whose name matches this glob, such as \*.py (--include).
>
> **context** `integer`
>
> Lines of context to print around each match (-C).
>
> **files\_with\_matches** `boolean`
>
> Print only the names of files that match (-l).
>
> **count** `boolean`
>
> Print only a count of matching lines per file (-c).
>
> **max\_count** `integer`
>
> Stop each file after this many matching lines (-m).
>
> **Responses**
>
> `200` OK
>
> `application/json` `ToolResponse`
>
> **text** `string` *required*
>
> **is\_error** `boolean` *required*
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/tools/ls
>
> Ls tool
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/tools/ls-tool.md)
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **Body** `application/json`
>
> **path** `string` *required*
>
> Absolute path of the directory to list.
>
> **Responses**
>
> `200` OK
>
> `application/json` `ToolResponse`
>
> **text** `string` *required*
>
> **is\_error** `boolean` *required*
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/tools/read
>
> Read tool
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/tools/read-tool.md)
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **Body** `application/json`
>
> **path** `string` *required*
>
> Absolute path of the file to read.
>
> **offset** `integer`
>
> First line to return, zero-based (default 0).
>
> **limit** `integer`
>
> Maximum number of lines to return (default 2000).
>
> **Responses**
>
> `200` OK
>
> `application/json` `ToolResponse`
>
> **text** `string` *required*
>
> **is\_error** `boolean` *required*
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/tools/shell
>
> Shell tool
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/tools/shell-tool.md)
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **Body** `application/json`
>
> **command** `string` *required*
>
> The command line to run.
>
> **Responses**
>
> `200` OK
>
> `application/json` `ToolResponse`
>
> **text** `string` *required*
>
> **is\_error** `boolean` *required*
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/tools/write
>
> Write tool
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/tools/write-tool.md)
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **Body** `application/json`
>
> **path** `string` *required*
>
> Absolute path of the file to write.
>
> **content** `string` *required*
>
> The text to write.
>
> **Responses**
>
> `200` OK
>
> `application/json` `ToolResponse`
>
> **text** `string` *required*
>
> **is\_error** `boolean` *required*
>
> `401` The token is missing or wrong
>
> `403` A policy or mount mode refused the call
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] GET /v1/workspaces/\{workspace\_id}/sessions/\{session\_id}/skill-md
>
> Read a session's SKILL.md
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/documents/read-a-sessions-skillmd.md)
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **session\_id** `string | null` *required*
>
> **Query**
>
> **profile** `string | null`
>
> **Responses**
>
> `200` The document
>
> `text/markdown` `string`
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] PUT /v1/workspaces/\{workspace\_id}/sessions/\{session\_id}/skill-md
>
> Write a session's SKILL.md
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/documents/write-a-sessions-skillmd.md)
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **session\_id** `string | null` *required*
>
> **Query**
>
> **profile** `string | null`
>
> **Body** `application/json`
>
> **path** `string` *required*
>
> **Responses**
>
> `200` OK
>
> `application/json` `any`
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] GET /v1/workspaces/\{workspace\_id}/sessions/\{session\_id}/vfs-md
>
> Read a session's VFS.md
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/documents/read-a-sessions-vfsmd.md)
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **session\_id** `string | null` *required*
>
> **Query**
>
> **profile** `string | null`
>
> **Responses**
>
> `200` The document
>
> `text/markdown` `string`
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] PUT /v1/workspaces/\{workspace\_id}/sessions/\{session\_id}/vfs-md
>
> Write a session's VFS.md
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/documents/write-a-sessions-vfsmd.md)
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **session\_id** `string | null` *required*
>
> **Query**
>
> **profile** `string | null`
>
> **Body** `application/json`
>
> **path** `string` *required*
>
> **Responses**
>
> `200` OK
>
> `application/json` `any`
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] GET /v1/workspaces/\{workspace\_id}/skill-md
>
> Read the workspace's SKILL.md
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/documents/read-the-workspaces-skillmd.md)
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **profile** `string | null`
>
> **Responses**
>
> `200` The document
>
> `text/markdown` `string`
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] PUT /v1/workspaces/\{workspace\_id}/skill-md
>
> Write the workspace's SKILL.md
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/documents/write-the-workspaces-skillmd.md)
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **profile** `string | null`
>
> **Body** `application/json`
>
> **path** `string` *required*
>
> **Responses**
>
> `200` OK
>
> `application/json` `any`
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] GET /v1/workspaces/\{workspace\_id}/vfs-md
>
> Read the workspace's VFS.md
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/documents/read-the-workspaces-vfsmd.md)
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **profile** `string | null`
>
> **Responses**
>
> `200` The document
>
> `text/markdown` `string`
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] PUT /v1/workspaces/\{workspace\_id}/vfs-md
>
> Write the workspace's VFS.md
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/documents/write-the-workspaces-vfsmd.md)
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> The session the call acts as; the default session when absent.
>
> **profile** `string | null`
>
> **Body** `application/json`
>
> **path** `string` *required*
>
> **Responses**
>
> `200` OK
>
> `application/json` `any`
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/load
>
> Load a snapshot
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/snapshots/load-a-snapshot.md)
>
> **Body** `application/json`
>
> **key** `string`
>
> The tar's key in the snapshot store; leave it out when uploading.
>
> **id** `string`
>
> The new workspace's id.
>
> **override** `object`
>
> Configuration overrides for the restored workspace, including credentials redacted from the snapshot.
>
> **Body** `multipart/form-data`
>
> **request** `LoadRequest`
>
> **snapshot** `string` *required*
>
> The tar archive, up to 1 GiB.
>
> **Responses**
>
> `201` Created
>
> `application/json` `WorkspaceDetail`
>
> **id** `string` *required*
>
> **mode** `string` *required*
>
> **created\_at** `number` *required*
>
> **fuse\_mountpoints** `object`
>
> **system\_time** `string | null`
>
> **sessions** `SessionSummary[]`
>
> **mounts** `MountSummary[]`
>
> **internals** `WorkspaceInternals | null`
>
> `401` The token is missing or wrong
>
> `409` The id or name is taken, the workspace is busy, or a file changed since it was read
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/clone
>
> Clone a workspace
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/snapshots/clone-a-workspace.md)
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Body** `application/json`
>
> **id** `string | null`
>
> **override** `object | null`
>
> **Responses**
>
> `201` Created
>
> `application/json` `WorkspaceDetail`
>
> **id** `string` *required*
>
> **mode** `string` *required*
>
> **created\_at** `number` *required*
>
> **fuse\_mountpoints** `object`
>
> **system\_time** `string | null`
>
> **sessions** `SessionSummary[]`
>
> **mounts** `MountSummary[]`
>
> **internals** `WorkspaceInternals | null`
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] GET /v1/workspaces/\{workspace\_id}/snapshot
>
> Download a snapshot
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/snapshots/download-a-snapshot.md)
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Responses**
>
> `200` The tar archive, with secrets redacted
>
> `application/x-tar` `string`
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `409` The id or name is taken, the workspace is busy, or a file changed since it was read
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/snapshot
>
> Snapshot a workspace
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/snapshots/snapshot-a-workspace.md)
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Body** `application/json`
>
> **key** `string` *required*
>
> **Responses**
>
> `200` OK
>
> `application/json` `SnapshotWorkspaceResponse`
>
> **id** `string` *required*
>
> **key** `string` *required*
>
> **size** `integer` *required*
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] GET /v1/templates
>
> List templates · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/templates/list-templates.md)
>
> The saved templates, by name.
>
> **Responses**
>
> `200` OK
>
> `application/json` `TemplateList`
>
> **items** `TemplateResponse[]` *required*
>
> `401` The token is missing or wrong
>
> `429` Past a rate limit, or a new session past max\_sessions
>
> `501` The server requires accounts; saved configs are kept only on a server of one account

> [accordion] POST /v1/templates
>
> Create a template · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/templates/create-a-template.md)
>
> Save a template: a whole workspace config, checked as a create
> checks one, and kept as written. A name already saved is a 409.
>
> **Body** `application/json`
>
> **name** `string` *required*
>
> **description** `string | null`
>
> **config** `WorkspaceConfig` *required*
>
> **Responses**
>
> `201` Created
>
> `application/json` `TemplateResponse`
>
> **name** `string` *required*
>
> **description** `string | null` *required*
>
> **config** `object` *required*
>
> `401` The token is missing or wrong
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions
>
> `501` The server requires accounts; saved configs are kept only on a server of one account

> [accordion] GET /v1/templates/\{ref}
>
> Get a template · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/templates/get-a-template.md)
>
> **Path**
>
> **ref** `string` *required*
>
> **Responses**
>
> `200` OK
>
> `application/json` `TemplateResponse`
>
> **name** `string` *required*
>
> **description** `string | null` *required*
>
> **config** `object` *required*
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions
>
> `501` The server requires accounts; saved configs are kept only on a server of one account

> [accordion] DELETE /v1/templates/\{ref}
>
> Delete a template · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/templates/delete-a-template.md)
>
> Delete a template; `restore` brings it back.
>
> **Path**
>
> **ref** `string` *required*
>
> **Responses**
>
> `204` No content
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions
>
> `501` The server requires accounts; saved configs are kept only on a server of one account

> [accordion] POST /v1/templates/\{ref}/restore
>
> Restore a template · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/templates/restore-a-template.md)
>
> **Path**
>
> **ref** `string` *required*
>
> **Responses**
>
> `200` OK
>
> `application/json` `TemplateResponse`
>
> **name** `string` *required*
>
> **description** `string | null` *required*
>
> **config** `object` *required*
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions
>
> `501` The server requires accounts; saved configs are kept only on a server of one account

> [accordion] GET /v1/vfs
>
> List VFS configs · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/saved-vfs/list-vfs-configs.md)
>
> The saved VFS configs: a mount's type and fields, kept by name for templates to use.
>
> **Query**
>
> **type** `string | null`
>
> Only entries of this type, such as s3.
>
> **q** `string | null`
>
> Only entries whose name contains this text, ignoring case.
>
> **Responses**
>
> `200` OK
>
> `application/json` `SavedEntryList`
>
> **items** `SavedEntry[]` *required*
>
> `401` The token is missing or wrong
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions
>
> `501` The server requires accounts; saved configs are kept only on a server of one account

> [accordion] POST /v1/vfs
>
> Create a VFS config · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/saved-vfs/create-a-vfs-config.md)
>
> Save a VFS config. Its fields are checked against the type's; secret fields are sealed, and a string field may point at a saved store's secret instead. A name already saved is a 409.
>
> **Body** `application/json`
>
> **name** `string` *required*
>
> 1 to 63 of a-z 0-9 . \_ -, starting with a letter or digit. Not `types`, and not shaped like an id.
>
> **type** `string` *required*
>
> One of the types its kind's `/types` route lists, such as `GET /v1/vfs/types`.
>
> **fields** `object` *required*
>
> The type's config. Secret fields are sealed; a string field may point at a saved store instead.
>
> **Responses**
>
> `201` Created
>
> `application/json` `SavedEntry`
>
> **id** `string` *required*
>
> The entry's id; the daemon uses its name.
>
> **name** `string` *required*
>
> **kind** `string` *required*
>
> **type** `string` *required*
>
> The VFS, CLI or runtime type, such as s3.
>
> **builtin** `boolean` *required*
>
> **config** `object` *required*
>
> The plain fields. Sealed fields are never answered.
>
> **captures** `any[]`
>
> A runtime's captures; runtimes only.
>
> **created\_by** `string | null`
>
> **created\_at** `string | null`
>
> **updated\_at** `string | null`
>
> **used\_by** `integer`
>
> How many templates name the entry; in a list only.
>
> `400` Bad request: malformed, a host not allowed, or a browser page from another origin
>
> `401` The token is missing or wrong
>
> `409` The id or name is taken, the workspace is busy, or a file changed since it was read
>
> `429` Past a rate limit, or a new session past max\_sessions
>
> `501` The server requires accounts; saved configs are kept only on a server of one account

> [accordion] GET /v1/vfs/types
>
> List VFS config types · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/saved-vfs/list-vfs-config-types.md)
>
> Every type a VFS config can be, with the fields its config takes.
>
> **Responses**
>
> `200` OK
>
> `application/json` `TypeTable`
>
> `401` The token is missing or wrong
>
> `429` Past a rate limit, or a new session past max\_sessions
>
> `501` The server requires accounts; saved configs are kept only on a server of one account

> [accordion] GET /v1/vfs/\{ref}
>
> Get a VFS config · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/saved-vfs/get-a-vfs-config.md)
>
> One saved VFS config, with its sealed fields named but not answered.
>
> **Path**
>
> **ref** `string` *required*
>
> The VFS config's name.
>
> **Responses**
>
> `200` OK
>
> `application/json` `SavedEntryDetail`
>
> **id** `string` *required*
>
> The entry's id; the daemon uses its name.
>
> **name** `string` *required*
>
> **kind** `string` *required*
>
> **type** `string` *required*
>
> The VFS, CLI or runtime type, such as s3.
>
> **builtin** `boolean` *required*
>
> **config** `object` *required*
>
> The plain fields. Sealed fields are never answered.
>
> **captures** `any[]`
>
> A runtime's captures; runtimes only.
>
> **created\_by** `string | null`
>
> **created\_at** `string | null`
>
> **updated\_at** `string | null`
>
> **used\_by** `integer`
>
> How many templates name the entry; in a list only.
>
> **sealed** `string[]` *required*
>
> The sealed fields, by name.
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions
>
> `501` The server requires accounts; saved configs are kept only on a server of one account

> [accordion] PUT /v1/vfs/\{ref}
>
> Update a VFS config · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/saved-vfs/update-a-vfs-config.md)
>
> Change a VFS config's fields. Its name and type stay; a sealed field left out keeps its value.
>
> **Path**
>
> **ref** `string` *required*
>
> The VFS config's name.
>
> **Body** `application/json`
>
> **fields** `object` *required*
>
> The fields to set. A sealed field left out keeps its value; null removes a field.
>
> **Responses**
>
> `200` OK
>
> `application/json` `SavedEntry`
>
> **id** `string` *required*
>
> The entry's id; the daemon uses its name.
>
> **name** `string` *required*
>
> **kind** `string` *required*
>
> **type** `string` *required*
>
> The VFS, CLI or runtime type, such as s3.
>
> **builtin** `boolean` *required*
>
> **config** `object` *required*
>
> The plain fields. Sealed fields are never answered.
>
> **captures** `any[]`
>
> A runtime's captures; runtimes only.
>
> **created\_by** `string | null`
>
> **created\_at** `string | null`
>
> **updated\_at** `string | null`
>
> **used\_by** `integer`
>
> How many templates name the entry; in a list only.
>
> `400` Bad request: malformed, a host not allowed, or a browser page from another origin
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions
>
> `501` The server requires accounts; saved configs are kept only on a server of one account

> [accordion] DELETE /v1/vfs/\{ref}
>
> Delete a VFS config · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/saved-vfs/delete-a-vfs-config.md)
>
> Delete a saved VFS config.
>
> **Path**
>
> **ref** `string` *required*
>
> The VFS config's name.
>
> **Responses**
>
> `204` No content
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions
>
> `501` The server requires accounts; saved configs are kept only on a server of one account

> [accordion] GET /v1/clis
>
> List CLI configs · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/saved-clis/list-cli-configs.md)
>
> The saved CLI configs: a CLI install's type and fields, kept by name for templates to use.
>
> **Query**
>
> **type** `string | null`
>
> Only entries of this type, such as s3.
>
> **q** `string | null`
>
> Only entries whose name contains this text, ignoring case.
>
> **Responses**
>
> `200` OK
>
> `application/json` `SavedEntryList`
>
> **items** `SavedEntry[]` *required*
>
> `401` The token is missing or wrong
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions
>
> `501` The server requires accounts; saved configs are kept only on a server of one account

> [accordion] POST /v1/clis
>
> Create a CLI config · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/saved-clis/create-a-cli-config.md)
>
> Save a CLI config. Its fields are checked against the type's; secret fields are sealed, and a string field may point at a saved store's secret instead. A name already saved is a 409.
>
> **Body** `application/json`
>
> **name** `string` *required*
>
> 1 to 63 of a-z 0-9 . \_ -, starting with a letter or digit. Not `types`, and not shaped like an id.
>
> **type** `string` *required*
>
> One of the types its kind's `/types` route lists, such as `GET /v1/vfs/types`.
>
> **fields** `object` *required*
>
> The type's config. Secret fields are sealed; a string field may point at a saved store instead.
>
> **Responses**
>
> `201` Created
>
> `application/json` `SavedEntry`
>
> **id** `string` *required*
>
> The entry's id; the daemon uses its name.
>
> **name** `string` *required*
>
> **kind** `string` *required*
>
> **type** `string` *required*
>
> The VFS, CLI or runtime type, such as s3.
>
> **builtin** `boolean` *required*
>
> **config** `object` *required*
>
> The plain fields. Sealed fields are never answered.
>
> **captures** `any[]`
>
> A runtime's captures; runtimes only.
>
> **created\_by** `string | null`
>
> **created\_at** `string | null`
>
> **updated\_at** `string | null`
>
> **used\_by** `integer`
>
> How many templates name the entry; in a list only.
>
> `400` Bad request: malformed, a host not allowed, or a browser page from another origin
>
> `401` The token is missing or wrong
>
> `409` The id or name is taken, the workspace is busy, or a file changed since it was read
>
> `429` Past a rate limit, or a new session past max\_sessions
>
> `501` The server requires accounts; saved configs are kept only on a server of one account

> [accordion] GET /v1/clis/types
>
> List CLI config types · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/saved-clis/list-cli-config-types.md)
>
> Every type a CLI config can be, with the fields its config takes.
>
> **Responses**
>
> `200` OK
>
> `application/json` `TypeTable`
>
> `401` The token is missing or wrong
>
> `429` Past a rate limit, or a new session past max\_sessions
>
> `501` The server requires accounts; saved configs are kept only on a server of one account

> [accordion] GET /v1/clis/\{ref}
>
> Get a CLI config · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/saved-clis/get-a-cli-config.md)
>
> One saved CLI config, with its sealed fields named but not answered.
>
> **Path**
>
> **ref** `string` *required*
>
> The CLI config's name.
>
> **Responses**
>
> `200` OK
>
> `application/json` `SavedEntryDetail`
>
> **id** `string` *required*
>
> The entry's id; the daemon uses its name.
>
> **name** `string` *required*
>
> **kind** `string` *required*
>
> **type** `string` *required*
>
> The VFS, CLI or runtime type, such as s3.
>
> **builtin** `boolean` *required*
>
> **config** `object` *required*
>
> The plain fields. Sealed fields are never answered.
>
> **captures** `any[]`
>
> A runtime's captures; runtimes only.
>
> **created\_by** `string | null`
>
> **created\_at** `string | null`
>
> **updated\_at** `string | null`
>
> **used\_by** `integer`
>
> How many templates name the entry; in a list only.
>
> **sealed** `string[]` *required*
>
> The sealed fields, by name.
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions
>
> `501` The server requires accounts; saved configs are kept only on a server of one account

> [accordion] PUT /v1/clis/\{ref}
>
> Update a CLI config · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/saved-clis/update-a-cli-config.md)
>
> Change a CLI config's fields. Its name and type stay; a sealed field left out keeps its value.
>
> **Path**
>
> **ref** `string` *required*
>
> The CLI config's name.
>
> **Body** `application/json`
>
> **fields** `object` *required*
>
> The fields to set. A sealed field left out keeps its value; null removes a field.
>
> **Responses**
>
> `200` OK
>
> `application/json` `SavedEntry`
>
> **id** `string` *required*
>
> The entry's id; the daemon uses its name.
>
> **name** `string` *required*
>
> **kind** `string` *required*
>
> **type** `string` *required*
>
> The VFS, CLI or runtime type, such as s3.
>
> **builtin** `boolean` *required*
>
> **config** `object` *required*
>
> The plain fields. Sealed fields are never answered.
>
> **captures** `any[]`
>
> A runtime's captures; runtimes only.
>
> **created\_by** `string | null`
>
> **created\_at** `string | null`
>
> **updated\_at** `string | null`
>
> **used\_by** `integer`
>
> How many templates name the entry; in a list only.
>
> `400` Bad request: malformed, a host not allowed, or a browser page from another origin
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions
>
> `501` The server requires accounts; saved configs are kept only on a server of one account

> [accordion] DELETE /v1/clis/\{ref}
>
> Delete a CLI config · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/saved-clis/delete-a-cli-config.md)
>
> Delete a saved CLI config.
>
> **Path**
>
> **ref** `string` *required*
>
> The CLI config's name.
>
> **Responses**
>
> `204` No content
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions
>
> `501` The server requires accounts; saved configs are kept only on a server of one account

> [accordion] GET /v1/runtimes
>
> List runtime configs · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/saved-runtimes/list-runtime-configs.md)
>
> The saved runtime configs: a runtime's type and fields, kept by name for templates to use.
>
> **Query**
>
> **type** `string | null`
>
> Only entries of this type, such as s3.
>
> **q** `string | null`
>
> Only entries whose name contains this text, ignoring case.
>
> **Responses**
>
> `200` OK
>
> `application/json` `SavedEntryList`
>
> **items** `SavedEntry[]` *required*
>
> `401` The token is missing or wrong
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions
>
> `501` The server requires accounts; saved configs are kept only on a server of one account

> [accordion] POST /v1/runtimes
>
> Create a runtime config · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/saved-runtimes/create-a-runtime-config.md)
>
> Save a runtime config. Its fields are checked against the type's; secret fields are sealed, and a string field may point at a saved store's secret instead. A name already saved is a 409.
>
> **Body** `application/json`
>
> **name** `string` *required*
>
> 1 to 63 of a-z 0-9 . \_ -, starting with a letter or digit. Not `types`, and not shaped like an id.
>
> **type** `string` *required*
>
> One of the types its kind's `/types` route lists, such as `GET /v1/vfs/types`.
>
> **fields** `object` *required*
>
> The type's config. Secret fields are sealed; a string field may point at a saved store instead.
>
> **Responses**
>
> `201` Created
>
> `application/json` `SavedEntry`
>
> **id** `string` *required*
>
> The entry's id; the daemon uses its name.
>
> **name** `string` *required*
>
> **kind** `string` *required*
>
> **type** `string` *required*
>
> The VFS, CLI or runtime type, such as s3.
>
> **builtin** `boolean` *required*
>
> **config** `object` *required*
>
> The plain fields. Sealed fields are never answered.
>
> **captures** `any[]`
>
> A runtime's captures; runtimes only.
>
> **created\_by** `string | null`
>
> **created\_at** `string | null`
>
> **updated\_at** `string | null`
>
> **used\_by** `integer`
>
> How many templates name the entry; in a list only.
>
> `400` Bad request: malformed, a host not allowed, or a browser page from another origin
>
> `401` The token is missing or wrong
>
> `409` The id or name is taken, the workspace is busy, or a file changed since it was read
>
> `429` Past a rate limit, or a new session past max\_sessions
>
> `501` The server requires accounts; saved configs are kept only on a server of one account

> [accordion] GET /v1/runtimes/types
>
> List runtime config types · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/saved-runtimes/list-runtime-config-types.md)
>
> Every type a runtime config can be, with the fields its config takes.
>
> **Responses**
>
> `200` OK
>
> `application/json` `TypeTable`
>
> `401` The token is missing or wrong
>
> `429` Past a rate limit, or a new session past max\_sessions
>
> `501` The server requires accounts; saved configs are kept only on a server of one account

> [accordion] GET /v1/runtimes/\{ref}
>
> Get a runtime config · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/saved-runtimes/get-a-runtime-config.md)
>
> One saved runtime config, with its sealed fields named but not answered.
>
> **Path**
>
> **ref** `string` *required*
>
> The runtime config's name.
>
> **Responses**
>
> `200` OK
>
> `application/json` `SavedEntryDetail`
>
> **id** `string` *required*
>
> The entry's id; the daemon uses its name.
>
> **name** `string` *required*
>
> **kind** `string` *required*
>
> **type** `string` *required*
>
> The VFS, CLI or runtime type, such as s3.
>
> **builtin** `boolean` *required*
>
> **config** `object` *required*
>
> The plain fields. Sealed fields are never answered.
>
> **captures** `any[]`
>
> A runtime's captures; runtimes only.
>
> **created\_by** `string | null`
>
> **created\_at** `string | null`
>
> **updated\_at** `string | null`
>
> **used\_by** `integer`
>
> How many templates name the entry; in a list only.
>
> **sealed** `string[]` *required*
>
> The sealed fields, by name.
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions
>
> `501` The server requires accounts; saved configs are kept only on a server of one account

> [accordion] PUT /v1/runtimes/\{ref}
>
> Update a runtime config · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/saved-runtimes/update-a-runtime-config.md)
>
> Change a runtime config's fields. Its name and type stay; a sealed field left out keeps its value.
>
> **Path**
>
> **ref** `string` *required*
>
> The runtime config's name.
>
> **Body** `application/json`
>
> **fields** `object` *required*
>
> The fields to set. A sealed field left out keeps its value; null removes a field.
>
> **Responses**
>
> `200` OK
>
> `application/json` `SavedEntry`
>
> **id** `string` *required*
>
> The entry's id; the daemon uses its name.
>
> **name** `string` *required*
>
> **kind** `string` *required*
>
> **type** `string` *required*
>
> The VFS, CLI or runtime type, such as s3.
>
> **builtin** `boolean` *required*
>
> **config** `object` *required*
>
> The plain fields. Sealed fields are never answered.
>
> **captures** `any[]`
>
> A runtime's captures; runtimes only.
>
> **created\_by** `string | null`
>
> **created\_at** `string | null`
>
> **updated\_at** `string | null`
>
> **used\_by** `integer`
>
> How many templates name the entry; in a list only.
>
> `400` Bad request: malformed, a host not allowed, or a browser page from another origin
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions
>
> `501` The server requires accounts; saved configs are kept only on a server of one account

> [accordion] DELETE /v1/runtimes/\{ref}
>
> Delete a runtime config · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/saved-runtimes/delete-a-runtime-config.md)
>
> Delete a saved runtime config.
>
> **Path**
>
> **ref** `string` *required*
>
> The runtime config's name.
>
> **Responses**
>
> `204` No content
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions
>
> `501` The server requires accounts; saved configs are kept only on a server of one account

> [accordion] GET /v1/policies
>
> List policies · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/policies/list-policies.md)
>
> The saved policies' names, sorted. Get one for its source.
>
> **Responses**
>
> `200` OK
>
> `application/json` `PolicyList`
>
> **items** `PolicyName[]` *required*
>
> `401` The token is missing or wrong
>
> `429` Past a rate limit, or a new session past max\_sessions
>
> `501` The server requires accounts; saved configs are kept only on a server of one account

> [accordion] POST /v1/policies
>
> Create a policy · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/policies/create-a-policy.md)
>
> Save a policy program, by name. A name already saved is a 409.
>
> **Body** `application/json`
>
> **name** `string` *required*
>
> Ends in .py, such as guard.py.
>
> **source** `string` *required*
>
> The policy's Python program, up to 64 KiB.
>
> **Responses**
>
> `201` Created
>
> `application/json` `PolicyResponse`
>
> **name** `string` *required*
>
> **source** `string` *required*
>
> `400` Bad request: malformed, a host not allowed, or a browser page from another origin
>
> `401` The token is missing or wrong
>
> `409` The id or name is taken, the workspace is busy, or a file changed since it was read
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions
>
> `501` The server requires accounts; saved configs are kept only on a server of one account

> [accordion] GET /v1/policies/\{ref}
>
> Get a policy · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/policies/get-a-policy.md)
>
> One saved policy, with its source.
>
> **Path**
>
> **ref** `string` *required*
>
> The policy's name, such as guard.py.
>
> **Responses**
>
> `200` OK
>
> `application/json` `PolicyResponse`
>
> **name** `string` *required*
>
> **source** `string` *required*
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions
>
> `501` The server requires accounts; saved configs are kept only on a server of one account

> [accordion] PUT /v1/policies/\{ref}
>
> Update a policy · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/policies/update-a-policy.md)
>
> Replace a saved policy's source.
>
> **Path**
>
> **ref** `string` *required*
>
> The policy's name, such as guard.py.
>
> **Body** `application/json`
>
> **source** `string` *required*
>
> The new program, up to 64 KiB.
>
> **Responses**
>
> `200` OK
>
> `application/json` `PolicyResponse`
>
> **name** `string` *required*
>
> **source** `string` *required*
>
> `400` Bad request: malformed, a host not allowed, or a browser page from another origin
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions
>
> `501` The server requires accounts; saved configs are kept only on a server of one account

> [accordion] DELETE /v1/policies/\{ref}
>
> Delete a policy · daemon and hosted
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/policies/delete-a-policy.md)
>
> Delete a saved policy.
>
> **Path**
>
> **ref** `string` *required*
>
> The policy's name, such as guard.py.
>
> **Responses**
>
> `204` No content
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions
>
> `501` The server requires accounts; saved configs are kept only on a server of one account

> [accordion] GET /v1/workspaces/\{workspace\_id}/asks
>
> List asks
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/asks/list-asks.md)
>
> The workspace's asks: pending by default, every decision under
> `all=true`. The ledger already serves both views from one store,
> so the entry point only picks which query to run.
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **Query**
>
> **session\_id** `string`
>
> Only this session's records; every session's when absent.
>
> **all** `boolean`
>
> **Responses**
>
> `200` OK
>
> `application/json` `AskResponse[]`
>
> **id** `string` *required*
>
> **session\_id** `string` *required*
>
> **command** `string` *required*
>
> **argv** `string[]` *required*
>
> **cwd** `string` *required*
>
> **paths** `string[]` *required*
>
> **reason** `string` *required*
>
> **outcome** `string | null` *required*
>
> **scope** `string` *required*
>
> **note** `string` *required*
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] POST /v1/workspaces/\{workspace\_id}/asks/\{ask\_id}
>
> Answer an ask
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/asks/answer-an-ask.md)
>
> Answer one waiting ask, allow or deny, and return the settled
> record. A known id with nothing waiting is 409 rather than 404, so
> an operator retrying a click reads "already answered", not "not
> found".
>
> **Path**
>
> **workspace\_id** `string` *required*
>
> The workspace's id.
>
> **ask\_id** `string` *required*
>
> **Body** `application/json`
>
> **answer** `string` *required*
>
> **scope** `string`
>
> **note** `string`
>
> **Responses**
>
> `200` OK
>
> `application/json` `AskResponse`
>
> **id** `string` *required*
>
> **session\_id** `string` *required*
>
> **command** `string` *required*
>
> **argv** `string[]` *required*
>
> **cwd** `string` *required*
>
> **paths** `string[]` *required*
>
> **reason** `string` *required*
>
> **outcome** `string | null` *required*
>
> **scope** `string` *required*
>
> **note** `string` *required*
>
> `401` The token is missing or wrong
>
> `404` The workspace, session, job or file does not exist
>
> `422` Validation Error
>
> `application/json` `HTTPValidationError`
>
> **detail** `ValidationError[]`
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] GET /v1/health
>
> Check health
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/server/check-health.md)
>
> **Responses**
>
> `200` OK
>
> `application/json` `HealthResponse`
>
> **status** `string`
>
> **workspaces** `integer` *required*
>
> **uptime\_s** `number` *required*

> [accordion] GET /v1/ready
>
> Check readiness
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/server/check-readiness.md)
>
> Whether the server takes new workspaces: 503 while it drains for
> shutdown or holds `max_workspaces`, so a load balancer sends new
> work elsewhere. `/v1/health` only says the process is up.
>
> **Responses**
>
> `200` OK
>
> `application/json` `any`

> [accordion] POST /v1/shutdown
>
> Shut down the server
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/server/shut-down-the-server.md)
>
> Trip the exit event, which the app's `on_idle_exit` acts on.
>
> The daemon's hook sends SIGTERM to its own process, so uvicorn runs
> its graceful shutdown (close connections, run the lifespan's finally
> block). An app run without a hook keeps serving. The server serves
> every account, so an account may not stop it.
>
> **Responses**
>
> `200` OK
>
> `application/json` `ShutdownResponse`
>
> **status** `string` *required*
>
> **pid** `integer` *required*
>
> `401` The token is missing or wrong
>
> `429` Past a rate limit, or a new session past max\_sessions

> [accordion] GET /.well-known/oauth-protected-resource
>
> Read OAuth protected-resource metadata
>
> [Open page](https://docs.mirage.strukto.ai/api/operations/auth/read-oauth-protected-resource-metadata.md)
>
> Say where to log in, for `mirage login`.
>
> RFC 9728's protected resource metadata names the issuer, and
> `client_id` the OAuth client the CLI signs in as. A server that
> publishes no login answers 404, so the CLI knows it needs none.
>
> **Responses**
>
> `200` OK
>
> `application/json` `ProtectedResource`
>
> **resource** `string` *required*
>
> **authorization\_servers** `string[]` *required*
>
> **bearer\_methods\_supported** `string[]` *required*
>
> **client\_id** `string` *required*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.