> For the complete documentation index, see [llms.txt](https://firestonevm.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://firestonevm.gitbook.io/docs/api-reference/system.md).

# System

Build identity, inspect-only host diagnostics, and host-wide storage reclamation.

## Get version and build identity

> Returns the raw VersionResult payload. Request bodies and undocumented query fields are ignored; malformed percent encoding is rejected before routing.

```json
{"openapi":"3.1.0","info":{"title":"Firestone REST API","version":"0.1.0"},"tags":[{"name":"System","description":"Build identity, inspect-only host diagnostics, and host-wide storage reclamation."}],"servers":[{"url":"http://firestone","description":"Placeholder HTTP authority used by Unix-socket clients such as curl --unix-socket. No TCP connection is made."},{"url":"http://127.0.0.1:{port}","description":"Loopback TCP listener published by `firestone serve --listen tcp:127.0.0.1:PORT --token FILE` and by `firestone ui`. The bind address must be loopback and the listener must carry a token; both are refused before the socket is created otherwise.","variables":{"port":{"default":"8642","description":"Port passed to --listen, or the ephemeral port firestone ui binds"}}}],"paths":{"/v1/version":{"get":{"tags":["System"],"operationId":"getVersion","summary":"Get version and build identity","description":"Returns the raw VersionResult payload. Request bodies and undocumented query fields are ignored; malformed percent encoding is rejected before routing.","responses":{"200":{"description":"Version, release identity, selected dependency pins, and resolved paths.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionResult"}}}},"400":{"$ref":"#/components/responses/Error400"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"},"504":{"$ref":"#/components/responses/Error504"}}}}},"components":{"schemas":{"VersionResult":{"type":"object","properties":{"version":{"type":"string"},"identity":{"$ref":"#/components/schemas/VersionIdentity"},"architecture":{"$ref":"#/components/schemas/Architecture"},"dependencies":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/VersionDependency"}},"paths":{"$ref":"#/components/schemas/VersionPaths"}},"additionalProperties":false,"required":["version","identity","architecture","dependencies","paths"]},"VersionIdentity":{"type":"object","properties":{"release":{"type":"string","pattern":"^v.+$"},"git_commit":{"anyOf":[{"type":"string","pattern":"^[0-9a-f]{40}$"},{"type":"null"}]}},"additionalProperties":false,"required":["release","git_commit"]},"Architecture":{"type":"string","enum":["x86_64","aarch64"],"description":"CPU architecture accepted by the shared machine model."},"VersionDependency":{"type":"object","properties":{"version":{"type":"string"},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"}},"additionalProperties":false,"required":["version","sha256"]},"VersionPaths":{"type":"object","properties":{"config":{"$ref":"#/components/schemas/Path"},"data":{"$ref":"#/components/schemas/Path"},"runtime":{"$ref":"#/components/schemas/Path"}},"additionalProperties":false,"required":["config","data","runtime"]},"Path":{"type":"string","description":"UTF-8 filesystem path."},"ErrorEnvelope":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorInfo"}},"additionalProperties":false,"required":["error"]},"ErrorInfo":{"type":"object","properties":{"kind":{"$ref":"#/components/schemas/ErrorKind"},"message":{"type":"string"},"hint":{"type":"string"},"field":{"type":"string"}},"additionalProperties":false,"required":["kind","message"],"description":"hint is omitted when the error has no public remediation hint. field is omitted unless the error belongs to one machine-spec leaf; when present it is that leaf's dotted path, such as memory, network.forward, mount[0].host or cloud_init.password."},"ErrorKind":{"type":"string","enum":["generic","usage","invalid_spec","not_found","not_running","conflict","already_exists","already_running","busy","dependency","timeout","checksum","interrupted"]}},"responses":{"Error400":{"description":"Bad request: usage or invalid_spec.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Error404":{"description":"Resource or route not found: not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Error409":{"description":"Conflict: conflict, already_running, or busy.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Error500":{"description":"Internal action failure: generic, not_running, already_exists, or interrupted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Error502":{"description":"Image checksum or verification failure: checksum.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Error503":{"description":"Host dependency unavailable or broken: dependency.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Error504":{"description":"Bounded action deadline exceeded: timeout.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}
```

## Inspect host requirements

> Runs the shared doctor action with fix=false and elevation\_confirmed=false. It never performs repair. Request bodies and undocumented query fields are ignored.

```json
{"openapi":"3.1.0","info":{"title":"Firestone REST API","version":"0.1.0"},"tags":[{"name":"System","description":"Build identity, inspect-only host diagnostics, and host-wide storage reclamation."}],"servers":[{"url":"http://firestone","description":"Placeholder HTTP authority used by Unix-socket clients such as curl --unix-socket. No TCP connection is made."},{"url":"http://127.0.0.1:{port}","description":"Loopback TCP listener published by `firestone serve --listen tcp:127.0.0.1:PORT --token FILE` and by `firestone ui`. The bind address must be loopback and the listener must carry a token; both are refused before the socket is created otherwise.","variables":{"port":{"default":"8642","description":"Port passed to --listen, or the ephemeral port firestone ui binds"}}}],"paths":{"/v1/doctor":{"get":{"tags":["System"],"operationId":"getDoctorReport","summary":"Inspect host requirements","description":"Runs the shared doctor action with fix=false and elevation_confirmed=false. It never performs repair. Request bodies and undocumented query fields are ignored.","responses":{"200":{"description":"Ordered report containing all 13 host checks.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DoctorReport"}}}},"400":{"$ref":"#/components/responses/Error400"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"500":{"$ref":"#/components/responses/Error500"},"502":{"$ref":"#/components/responses/Error502"},"503":{"$ref":"#/components/responses/Error503"},"504":{"$ref":"#/components/responses/Error504"}}}}},"components":{"schemas":{"DoctorReport":{"type":"object","properties":{"checks":{"type":"array","items":{"$ref":"#/components/schemas/DoctorCheck"},"minItems":13,"maxItems":13}},"additionalProperties":false,"required":["checks"]},"DoctorCheck":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/DoctorCheckId"},"status":{"$ref":"#/components/schemas/DoctorStatus"},"reason":{"type":"string"},"fixed":{"type":"boolean","description":"True when this run repaired the check rather than finding it well. Omitted when false."},"fix":{"type":"string"},"hint":{"type":"string"}},"additionalProperties":false,"required":["id","status","reason"],"description":"fix and hint are omitted when absent; they are never emitted as null. fixed is omitted when false."},"DoctorCheckId":{"type":"string","enum":["host_arch","kvm","nested_virtualization","runtime_dir","vendored_binaries","virtiofsd","passt","qemu_img","ssh","user_namespaces","ssh_key","data_space","stale_state"]},"DoctorStatus":{"type":"string","enum":["ok","warn","fail"]},"ErrorEnvelope":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorInfo"}},"additionalProperties":false,"required":["error"]},"ErrorInfo":{"type":"object","properties":{"kind":{"$ref":"#/components/schemas/ErrorKind"},"message":{"type":"string"},"hint":{"type":"string"},"field":{"type":"string"}},"additionalProperties":false,"required":["kind","message"],"description":"hint is omitted when the error has no public remediation hint. field is omitted unless the error belongs to one machine-spec leaf; when present it is that leaf's dotted path, such as memory, network.forward, mount[0].host or cloud_init.password."},"ErrorKind":{"type":"string","enum":["generic","usage","invalid_spec","not_found","not_running","conflict","already_exists","already_running","busy","dependency","timeout","checksum","interrupted"]}},"responses":{"Error400":{"description":"Bad request: usage or invalid_spec.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Error404":{"description":"Resource or route not found: not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Error409":{"description":"Conflict: conflict, already_running, or busy.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Error500":{"description":"Internal action failure: generic, not_running, already_exists, or interrupted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Error502":{"description":"Image checksum or verification failure: checksum.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Error503":{"description":"Host dependency unavailable or broken: dependency.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Error504":{"description":"Bounded action deadline exceeded: timeout.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}
```

## Sample host metrics once

> Returns one sample of the host itself: processor count and kernel load averages from /proc/loadavg, memory levels from /proc/meminfo, and the capacity of the filesystem holding the Firestone data directory. The read takes no machine lock and needs no machine. A figure the host does not expose is null. Request bodies and undocumented query fields are ignored.

```json
{"openapi":"3.1.0","info":{"title":"Firestone REST API","version":"0.1.0"},"tags":[{"name":"System","description":"Build identity, inspect-only host diagnostics, and host-wide storage reclamation."}],"servers":[{"url":"http://firestone","description":"Placeholder HTTP authority used by Unix-socket clients such as curl --unix-socket. No TCP connection is made."},{"url":"http://127.0.0.1:{port}","description":"Loopback TCP listener published by `firestone serve --listen tcp:127.0.0.1:PORT --token FILE` and by `firestone ui`. The bind address must be loopback and the listener must carry a token; both are refused before the socket is created otherwise.","variables":{"port":{"default":"8642","description":"Port passed to --listen, or the ephemeral port firestone ui binds"}}}],"paths":{"/v1/host/metrics":{"get":{"tags":["System"],"operationId":"getHostMetrics","summary":"Sample host metrics once","description":"Returns one sample of the host itself: processor count and kernel load averages from /proc/loadavg, memory levels from /proc/meminfo, and the capacity of the filesystem holding the Firestone data directory. The read takes no machine lock and needs no machine. A figure the host does not expose is null. Request bodies and undocumented query fields are ignored.","responses":{"200":{"description":"One host sample.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HostMetricsResult"}}}},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}}}}},"components":{"schemas":{"HostMetricsResult":{"type":"object","description":"One sample of the host itself. Firestone stores no history, and an unavailable figure is null rather than zero.","properties":{"sampled_at":{"type":"string","format":"date-time","description":"RFC 3339 instant at which the host sources were read."},"cpu":{"$ref":"#/components/schemas/HostMetricsCpu"},"memory":{"$ref":"#/components/schemas/HostMetricsMemory"},"disk":{"$ref":"#/components/schemas/HostMetricsDisk"}},"additionalProperties":false,"required":["sampled_at","cpu","memory","disk"]},"HostMetricsCpu":{"type":"object","properties":{"cores":{"type":["integer","null"],"description":"Host processor count, or null when it cannot be read.","minimum":1},"load_average_1m":{"type":["number","null"],"description":"Kernel one-minute load average, or null off Linux.","minimum":0},"load_average_5m":{"type":["number","null"],"description":"Kernel five-minute load average, or null off Linux.","minimum":0},"load_average_15m":{"type":["number","null"],"description":"Kernel fifteen-minute load average, or null off Linux.","minimum":0}},"additionalProperties":false,"required":["cores","load_average_1m","load_average_5m","load_average_15m"]},"HostMetricsMemory":{"type":"object","properties":{"total_bytes":{"type":["integer","null"],"description":"MemTotal in bytes, or null when /proc/meminfo is unavailable.","minimum":0},"available_bytes":{"type":["integer","null"],"description":"MemAvailable in bytes, or null when /proc/meminfo is unavailable.","minimum":0}},"additionalProperties":false,"required":["total_bytes","available_bytes"]},"HostMetricsDisk":{"type":"object","properties":{"path":{"type":"string","description":"The measured directory: Firestone's data directory."},"total_bytes":{"type":["integer","null"],"description":"Size of the filesystem holding that directory, or null when it cannot be measured.","minimum":0},"available_bytes":{"type":["integer","null"],"description":"Bytes still available to this user there, or null when it cannot be measured.","minimum":0}},"additionalProperties":false,"required":["path","total_bytes","available_bytes"]},"ErrorEnvelope":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorInfo"}},"additionalProperties":false,"required":["error"]},"ErrorInfo":{"type":"object","properties":{"kind":{"$ref":"#/components/schemas/ErrorKind"},"message":{"type":"string"},"hint":{"type":"string"},"field":{"type":"string"}},"additionalProperties":false,"required":["kind","message"],"description":"hint is omitted when the error has no public remediation hint. field is omitted unless the error belongs to one machine-spec leaf; when present it is that leaf's dotted path, such as memory, network.forward, mount[0].host or cloud_init.password."},"ErrorKind":{"type":"string","enum":["generic","usage","invalid_spec","not_found","not_running","conflict","already_exists","already_running","busy","dependency","timeout","checksum","interrupted"]}},"responses":{"Error500":{"description":"Internal action failure: generic, not_running, already_exists, or interrupted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Error503":{"description":"Host dependency unavailable or broken: dependency.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}
```

## Reclaim Firestone storage

> Removes Firestone's own reclaimable artifacts. With no body, and with every member false, only inert artifacts are removed: stale per-machine runtime directories of machines that are not starting, running, or stopping, rotated console.log.previous files, unfinished .partial artifacts in the image store and machine directories, orphaned machine removal directories, and unfinished snapshot directories. images additionally removes stored base images that neither a machine state nor a snapshot metadata document references. machines is the only destructive tier and requires force unless dry\_run is true; without it the request is refused with a usage error naming force. The images tier is evaluated against the reference set as it stands when the prune starts, so a machine removed in the same call does not release its image until the next prune. dry\_run reports the same removed list and reclaimed\_bytes without deleting anything.

```json
{"openapi":"3.1.0","info":{"title":"Firestone REST API","version":"0.1.0"},"tags":[{"name":"System","description":"Build identity, inspect-only host diagnostics, and host-wide storage reclamation."}],"servers":[{"url":"http://firestone","description":"Placeholder HTTP authority used by Unix-socket clients such as curl --unix-socket. No TCP connection is made."},{"url":"http://127.0.0.1:{port}","description":"Loopback TCP listener published by `firestone serve --listen tcp:127.0.0.1:PORT --token FILE` and by `firestone ui`. The bind address must be loopback and the listener must carry a token; both are refused before the socket is created otherwise.","variables":{"port":{"default":"8642","description":"Port passed to --listen, or the ephemeral port firestone ui binds"}}}],"paths":{"/v1/system/prune":{"post":{"tags":["System"],"operationId":"pruneSystem","summary":"Reclaim Firestone storage","description":"Removes Firestone's own reclaimable artifacts. With no body, and with every member false, only inert artifacts are removed: stale per-machine runtime directories of machines that are not starting, running, or stopping, rotated console.log.previous files, unfinished .partial artifacts in the image store and machine directories, orphaned machine removal directories, and unfinished snapshot directories. images additionally removes stored base images that neither a machine state nor a snapshot metadata document references. machines is the only destructive tier and requires force unless dry_run is true; without it the request is refused with a usage error naming force. The images tier is evaluated against the reference set as it stands when the prune starts, so a machine removed in the same call does not release its image until the next prune. dry_run reports the same removed list and reclaimed_bytes without deleting anything.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PruneSystemRequest"}}}},"responses":{"200":{"description":"Per-artifact progress and the terminal prune result.","content":{"application/x-ndjson":{"schema":{"type":"string","description":"LF-delimited compact JSON records. Progress records arrive as produced. Success ends with exactly one typed Result record; a dispatcher failure after progress ends with one ErrorEnvelope record under HTTP 200."}},"application/json":{"schema":{"$ref":"#/components/schemas/PruneDispatchOutput"}}}},"400":{"$ref":"#/components/responses/ActionError400"},"404":{"$ref":"#/components/responses/ActionError404"},"409":{"$ref":"#/components/responses/ActionError409"},"500":{"$ref":"#/components/responses/ActionError500"},"502":{"$ref":"#/components/responses/ActionError502"},"503":{"$ref":"#/components/responses/ActionError503"},"504":{"$ref":"#/components/responses/ActionError504"}}}}},"components":{"schemas":{"PruneSystemRequest":{"type":"object","properties":{"machines":{"type":["boolean","null"],"description":"Also remove machines whose reconciled status is stopped, created, or failed. This is the only destructive tier: unless dry_run is true it requires force to be true as well, and is otherwise refused with a usage error naming force."},"images":{"type":["boolean","null"],"description":"Also remove stored base images that no machine state and no snapshot metadata references."},"force":{"type":["boolean","null"],"description":"Explicit approval for the destructive machines tier."},"dry_run":{"type":["boolean","null"],"description":"Report the same removed list without deleting anything."}},"additionalProperties":false,"description":"Optional JSON body. An absent body is the same as {}."},"PruneDispatchOutput":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/NonTerminalEvent"}},"result":{"$ref":"#/components/schemas/PruneResultEvent"}},"additionalProperties":false,"required":["events","result"]},"NonTerminalEvent":{"oneOf":[{"$ref":"#/components/schemas/StepStartEvent"},{"$ref":"#/components/schemas/StepUpdateEvent"},{"$ref":"#/components/schemas/ProgressEvent"},{"$ref":"#/components/schemas/StepDoneEvent"},{"$ref":"#/components/schemas/StepSkipEvent"},{"$ref":"#/components/schemas/StepFailEvent"},{"$ref":"#/components/schemas/LogEvent"},{"$ref":"#/components/schemas/OutputEvent"}],"discriminator":{"propertyName":"type","mapping":{"StepStart":"#/components/schemas/StepStartEvent","StepUpdate":"#/components/schemas/StepUpdateEvent","Progress":"#/components/schemas/ProgressEvent","StepDone":"#/components/schemas/StepDoneEvent","StepSkip":"#/components/schemas/StepSkipEvent","StepFail":"#/components/schemas/StepFailEvent","Log":"#/components/schemas/LogEvent","Output":"#/components/schemas/OutputEvent"}}},"StepStartEvent":{"type":"object","properties":{"type":{"type":"string","const":"StepStart"},"id":{"type":"string"},"label":{"type":"string"}},"additionalProperties":false,"required":["type","id","label"]},"StepUpdateEvent":{"type":"object","properties":{"type":{"type":"string","const":"StepUpdate"},"id":{"type":"string"},"detail":{"type":"string"}},"additionalProperties":false,"required":["type","id","detail"]},"ProgressEvent":{"type":"object","properties":{"type":{"type":"string","const":"Progress"},"id":{"type":"string"},"done":{"type":"integer","minimum":0,"maximum":18446744073709552000},"total":{"anyOf":[{"type":"integer","minimum":0,"maximum":18446744073709552000},{"type":"null"}]},"unit":{"$ref":"#/components/schemas/Unit"}},"additionalProperties":false,"required":["type","id","done","total","unit"]},"Unit":{"type":"string","enum":["bytes"]},"StepDoneEvent":{"type":"object","properties":{"type":{"type":"string","const":"StepDone"},"id":{"type":"string"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}]},"elapsed_ms":{"type":"integer","minimum":0,"maximum":18446744073709552000}},"additionalProperties":false,"required":["type","id","detail","elapsed_ms"]},"StepSkipEvent":{"type":"object","properties":{"type":{"type":"string","const":"StepSkip"},"id":{"type":"string"},"reason":{"type":"string"}},"additionalProperties":false,"required":["type","id","reason"]},"StepFailEvent":{"type":"object","properties":{"type":{"type":"string","const":"StepFail"},"id":{"type":"string"},"error":{"$ref":"#/components/schemas/ErrorInfo"}},"additionalProperties":false,"required":["type","id","error"]},"ErrorInfo":{"type":"object","properties":{"kind":{"$ref":"#/components/schemas/ErrorKind"},"message":{"type":"string"},"hint":{"type":"string"},"field":{"type":"string"}},"additionalProperties":false,"required":["kind","message"],"description":"hint is omitted when the error has no public remediation hint. field is omitted unless the error belongs to one machine-spec leaf; when present it is that leaf's dotted path, such as memory, network.forward, mount[0].host or cloud_init.password."},"ErrorKind":{"type":"string","enum":["generic","usage","invalid_spec","not_found","not_running","conflict","already_exists","already_running","busy","dependency","timeout","checksum","interrupted"]},"LogEvent":{"type":"object","properties":{"type":{"type":"string","const":"Log"},"level":{"$ref":"#/components/schemas/Level"},"message":{"type":"string"}},"additionalProperties":false,"required":["type","level","message"]},"Level":{"type":"string","enum":["trace","debug","info","warn","error"]},"OutputEvent":{"type":"object","properties":{"type":{"type":"string","const":"Output"},"data":{"type":"string"}},"additionalProperties":false,"required":["type","data"]},"PruneResultEvent":{"type":"object","properties":{"type":{"type":"string","const":"Result"},"action":{"type":"string","const":"system-prune"},"payload":{"$ref":"#/components/schemas/PruneResult"}},"additionalProperties":false,"required":["type","action","payload"]},"PruneResult":{"type":"object","properties":{"dry_run":{"type":"boolean","description":"True when nothing was deleted."},"reclaimed_bytes":{"type":"integer","minimum":0,"maximum":18446744073709552000,"description":"Sum of every row's bytes."},"removed":{"type":"array","items":{"$ref":"#/components/schemas/PruneItem"}}},"additionalProperties":false,"required":["dry_run","reclaimed_bytes","removed"]},"PruneItem":{"type":"object","properties":{"kind":{"$ref":"#/components/schemas/PruneKind"},"id":{"type":"string","description":"Machine name for runtime and machine rows, stored image id for image rows, and a data-directory relative path otherwise."},"bytes":{"type":"integer","minimum":0,"maximum":18446744073709552000,"description":"Bytes the artifact occupied, measured before deletion."}},"additionalProperties":false,"required":["kind","id","bytes"]},"PruneKind":{"type":"string","enum":["runtime","log","partial","snapshot-partial","image","machine"],"description":"Artifact class of one prune row. runtime is a stale per-machine runtime directory, log a rotated console.log.previous, partial an unfinished .partial or .removing- artifact, snapshot-partial an unfinished snapshot directory, image an unreferenced stored base image, machine a whole removed machine."},"ErrorEnvelope":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorInfo"}},"additionalProperties":false,"required":["error"]}},"responses":{"ActionError400":{"description":"Bad request: usage or invalid_spec. Before the first event, a default-stream dispatcher error is one NDJSON line; request-validation errors remain JSON. With JSON aggregation selected, dispatcher errors are JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}},"application/x-ndjson":{"schema":{"type":"string","description":"One LF-terminated ErrorEnvelope record."}}}},"ActionError404":{"description":"Resource or route not found: not_found. Before the first event, a default-stream dispatcher error is one NDJSON line; request-validation errors remain JSON. With JSON aggregation selected, dispatcher errors are JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}},"application/x-ndjson":{"schema":{"type":"string","description":"One LF-terminated ErrorEnvelope record."}}}},"ActionError409":{"description":"Conflict: conflict, already_running, or busy. Before the first event, a default-stream dispatcher error is one NDJSON line; request-validation errors remain JSON. With JSON aggregation selected, dispatcher errors are JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}},"application/x-ndjson":{"schema":{"type":"string","description":"One LF-terminated ErrorEnvelope record."}}}},"ActionError500":{"description":"Internal action failure: generic, not_running, already_exists, or interrupted. Before the first event, a default-stream dispatcher error is one NDJSON line; request-validation errors remain JSON. With JSON aggregation selected, dispatcher errors are JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}},"application/x-ndjson":{"schema":{"type":"string","description":"One LF-terminated ErrorEnvelope record."}}}},"ActionError502":{"description":"Image checksum or verification failure: checksum. Before the first event, a default-stream dispatcher error is one NDJSON line; request-validation errors remain JSON. With JSON aggregation selected, dispatcher errors are JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}},"application/x-ndjson":{"schema":{"type":"string","description":"One LF-terminated ErrorEnvelope record."}}}},"ActionError503":{"description":"Host dependency unavailable or broken: dependency. Before the first event, a default-stream dispatcher error is one NDJSON line; request-validation errors remain JSON. With JSON aggregation selected, dispatcher errors are JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}},"application/x-ndjson":{"schema":{"type":"string","description":"One LF-terminated ErrorEnvelope record."}}}},"ActionError504":{"description":"Bounded action deadline exceeded: timeout. Before the first event, a default-stream dispatcher error is one NDJSON line; request-validation errors remain JSON. With JSON aggregation selected, dispatcher errors are JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}},"application/x-ndjson":{"schema":{"type":"string","description":"One LF-terminated ErrorEnvelope record."}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://firestonevm.gitbook.io/docs/api-reference/system.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.