> 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/images.md).

# Images

Immutable image-cache lifecycle.

## List stored images

> Returns every valid stored image pair. Request bodies and undocumented query fields are ignored.

```json
{"openapi":"3.1.0","info":{"title":"Firestone REST API","version":"0.1.0"},"tags":[{"name":"Images","description":"Immutable image-cache lifecycle."}],"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/images":{"get":{"tags":["Images"],"operationId":"listImages","summary":"List stored images","description":"Returns every valid stored image pair. Request bodies and undocumented query fields are ignored.","responses":{"200":{"description":"Stored image records.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoredImageList"}}}},"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":{"StoredImageList":{"type":"array","items":{"$ref":"#/components/schemas/StoredImage"}},"StoredImage":{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/ImageMetadata"},"path":{"$ref":"#/components/schemas/Path"}},"additionalProperties":false,"required":["metadata","path"]},"ImageMetadata":{"type":"object","properties":{"version":{"type":"integer","const":1},"id":{"type":"string","pattern":"^image-[0-9a-f]{64}$"},"generation":{"type":"integer","minimum":1,"maximum":18446744073709552000},"source_ref":{"type":"string","minLength":1},"source_url":{"anyOf":[{"type":"string","format":"uri","pattern":"^https://"},{"type":"null"}]},"source_sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"stored_sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"architecture":{"$ref":"#/components/schemas/Architecture"},"firmware":{"anyOf":[{"$ref":"#/components/schemas/CatalogFirmware"},{"type":"null"}]},"sshd_path":{"type":"string","pattern":"^/(?!\\.\\.?(?:/|$))(?!.*?/\\.\\.?(?:/|$))(?:[A-Za-z0-9._+-]+/)*[A-Za-z0-9._+-]+$","maxLength":4096,"description":"Omitted when the default /usr/sbin/sshd applies; dot and dot-dot components are forbidden."},"source_format":{"$ref":"#/components/schemas/ImageFormat"},"stored_format":{"type":"string","const":"qcow2"},"verification_algorithm":{"anyOf":[{"$ref":"#/components/schemas/ChecksumAlgorithm"},{"type":"null"}]},"verification_digest":{"anyOf":[{"type":"string","pattern":"^(?:[0-9a-f]{64}|[0-9a-f]{128})$"},{"type":"null"}]},"size":{"type":"integer","minimum":1,"maximum":18446744073709552000},"pulled_at":{"type":"string","format":"date-time"}},"additionalProperties":false,"required":["version","id","generation","source_ref","source_url","source_sha256","stored_sha256","architecture","firmware","source_format","stored_format","verification_algorithm","verification_digest","size","pulled_at"],"description":"Strict image sidecar metadata. sshd_path is omitted when it has the default value.","allOf":[{"oneOf":[{"properties":{"verification_algorithm":{"type":"null"},"verification_digest":{"type":"null"}}},{"properties":{"verification_algorithm":{"const":"sha256"},"verification_digest":{"type":"string","pattern":"^[0-9a-f]{64}$"}}},{"properties":{"verification_algorithm":{"const":"sha512"},"verification_digest":{"type":"string","pattern":"^[0-9a-f]{128}$"}}}]}]},"Architecture":{"type":"string","enum":["x86_64","aarch64"],"description":"CPU architecture accepted by the shared machine model."},"CatalogFirmware":{"type":"string","enum":["rhf","edk2"]},"ImageFormat":{"type":"string","enum":["qcow2","raw"]},"ChecksumAlgorithm":{"type":"string","enum":["sha256","sha512"]},"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"}}}}}}}
```

## Pull or import an image

> Streams image resolution, download, verification, and conversion Events by default. Accept: application/json aggregates them. sha256 may be supplied only for a direct HTTPS reference.

```json
{"openapi":"3.1.0","info":{"title":"Firestone REST API","version":"0.1.0"},"tags":[{"name":"Images","description":"Immutable image-cache lifecycle."}],"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/images/pull":{"post":{"tags":["Images"],"operationId":"pullImage","summary":"Pull or import an image","description":"Streams image resolution, download, verification, and conversion Events by default. Accept: application/json aggregates them. sha256 may be supplied only for a direct HTTPS reference.","responses":{"200":{"description":"Image pull progress and terminal stored-image 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/PullImageDispatchOutput"}}}},"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"}},"requestBody":{"required":true,"description":"Exactly one JSON object. ref is required; sha256 may be omitted or null. Unknown fields are rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PullImageRequest"}}}}}}},"components":{"schemas":{"PullImageDispatchOutput":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/NonTerminalEvent"}},"result":{"$ref":"#/components/schemas/PullImageResultEvent"}},"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"]},"PullImageResultEvent":{"type":"object","properties":{"type":{"type":"string","const":"Result"},"action":{"type":"string","const":"images-pull"},"payload":{"$ref":"#/components/schemas/PulledImage"}},"additionalProperties":false,"required":["type","action","payload"]},"PulledImage":{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/ImageMetadata"},"path":{"$ref":"#/components/schemas/Path"},"firmware":{"anyOf":[{"$ref":"#/components/schemas/CatalogFirmware"},{"type":"null"}]},"cached":{"type":"boolean"}},"additionalProperties":false,"required":["metadata","path","firmware","cached"]},"ImageMetadata":{"type":"object","properties":{"version":{"type":"integer","const":1},"id":{"type":"string","pattern":"^image-[0-9a-f]{64}$"},"generation":{"type":"integer","minimum":1,"maximum":18446744073709552000},"source_ref":{"type":"string","minLength":1},"source_url":{"anyOf":[{"type":"string","format":"uri","pattern":"^https://"},{"type":"null"}]},"source_sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"stored_sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"architecture":{"$ref":"#/components/schemas/Architecture"},"firmware":{"anyOf":[{"$ref":"#/components/schemas/CatalogFirmware"},{"type":"null"}]},"sshd_path":{"type":"string","pattern":"^/(?!\\.\\.?(?:/|$))(?!.*?/\\.\\.?(?:/|$))(?:[A-Za-z0-9._+-]+/)*[A-Za-z0-9._+-]+$","maxLength":4096,"description":"Omitted when the default /usr/sbin/sshd applies; dot and dot-dot components are forbidden."},"source_format":{"$ref":"#/components/schemas/ImageFormat"},"stored_format":{"type":"string","const":"qcow2"},"verification_algorithm":{"anyOf":[{"$ref":"#/components/schemas/ChecksumAlgorithm"},{"type":"null"}]},"verification_digest":{"anyOf":[{"type":"string","pattern":"^(?:[0-9a-f]{64}|[0-9a-f]{128})$"},{"type":"null"}]},"size":{"type":"integer","minimum":1,"maximum":18446744073709552000},"pulled_at":{"type":"string","format":"date-time"}},"additionalProperties":false,"required":["version","id","generation","source_ref","source_url","source_sha256","stored_sha256","architecture","firmware","source_format","stored_format","verification_algorithm","verification_digest","size","pulled_at"],"description":"Strict image sidecar metadata. sshd_path is omitted when it has the default value.","allOf":[{"oneOf":[{"properties":{"verification_algorithm":{"type":"null"},"verification_digest":{"type":"null"}}},{"properties":{"verification_algorithm":{"const":"sha256"},"verification_digest":{"type":"string","pattern":"^[0-9a-f]{64}$"}}},{"properties":{"verification_algorithm":{"const":"sha512"},"verification_digest":{"type":"string","pattern":"^[0-9a-f]{128}$"}}}]}]},"Architecture":{"type":"string","enum":["x86_64","aarch64"],"description":"CPU architecture accepted by the shared machine model."},"CatalogFirmware":{"type":"string","enum":["rhf","edk2"]},"ImageFormat":{"type":"string","enum":["qcow2","raw"]},"ChecksumAlgorithm":{"type":"string","enum":["sha256","sha512"]},"Path":{"type":"string","description":"UTF-8 filesystem path."},"ErrorEnvelope":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorInfo"}},"additionalProperties":false,"required":["error"]},"PullImageRequest":{"type":"object","properties":{"ref":{"$ref":"#/components/schemas/ImageRef"},"sha256":{"type":["string","null"],"pattern":"^[0-9A-Fa-f]{64}$","description":"Optional complete source SHA-256. The dispatcher normalizes accepted hexadecimal to lowercase."}},"additionalProperties":false,"required":["ref"]},"ImageRef":{"type":"string","minLength":1,"description":"Catalog reference, strict HTTPS URL, or local image path. Pull resolution performs source-specific validation."}},"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."}}}}}}}
```

## Prune unreferenced images

> The HTTP request body must contain zero bytes; even {} is rejected. Progress Events are collected internally and discarded; success returns only the typed prune payload.

```json
{"openapi":"3.1.0","info":{"title":"Firestone REST API","version":"0.1.0"},"tags":[{"name":"Images","description":"Immutable image-cache lifecycle."}],"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/images/prune":{"post":{"tags":["Images"],"operationId":"pruneImages","summary":"Prune unreferenced images","description":"The HTTP request body must contain zero bytes; even {} is rejected. Progress Events are collected internally and discarded; success returns only the typed prune payload.","responses":{"200":{"description":"Removed image IDs and total bytes freed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImagePruneResult"}}}},"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":{"ImagePruneResult":{"type":"object","properties":{"removed":{"type":"array","items":{"type":"string","pattern":"^image-[0-9a-f]{64}$"}},"bytes_freed":{"type":"integer","minimum":0,"maximum":18446744073709552000}},"additionalProperties":false,"required":["removed","bytes_freed"]},"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"}}}}}}}
```

## Delete one image

> The request body and Accept header are ignored. Progress and the internal ImageRemoveResult are discarded; success is always empty 204.

```json
{"openapi":"3.1.0","info":{"title":"Firestone REST API","version":"0.1.0"},"tags":[{"name":"Images","description":"Immutable image-cache lifecycle."}],"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/images/{id}":{"delete":{"tags":["Images"],"operationId":"deleteImage","summary":"Delete one image","description":"The request body and Accept header are ignored. Progress and the internal ImageRemoveResult are discarded; success is always empty 204.","responses":{"204":{"description":"Image removed. Empty body and no Content-Type header."},"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"}},"parameters":[{"$ref":"#/components/parameters/ImageId"},{"$ref":"#/components/parameters/Force"}]}}},"components":{"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"}}}}},"schemas":{"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"]}},"parameters":{"ImageId":{"name":"id","in":"path","required":true,"description":"Complete lowercase stable image ID shown by GET /v1/images.","schema":{"type":"string","pattern":"^image-[0-9a-f]{64}$"}},"Force":{"name":"force","in":"query","required":false,"description":"Defaults to false. Unknown, duplicate, or non-boolean query fields are rejected on force-query routes.","schema":{"type":"boolean","default":false}}}}}
```


---

# 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/images.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.