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

# Catalog

Merged image discovery independent of the local cache.

## List merged image catalog

> Returns the merged built-in and user catalog in canonical-reference order, independent of the local image cache. Request bodies and undocumented query fields are ignored.

```json
{"openapi":"3.1.0","info":{"title":"Firestone REST API","version":"0.1.0"},"tags":[{"name":"Catalog","description":"Merged image discovery independent of the local cache."}],"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/catalog":{"get":{"tags":["Catalog"],"operationId":"listCatalog","summary":"List merged image catalog","description":"Returns the merged built-in and user catalog in canonical-reference order, independent of the local image cache. Request bodies and undocumented query fields are ignored.","responses":{"200":{"description":"Merged catalog entries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogEntrySummaryList"}}}},"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":{"CatalogEntrySummaryList":{"type":"array","items":{"$ref":"#/components/schemas/CatalogEntrySummary"}},"CatalogEntrySummary":{"type":"object","properties":{"reference":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"architectures":{"type":"array","items":{"$ref":"#/components/schemas/CatalogArchitectureSummary"}}},"additionalProperties":false,"required":["reference","aliases","architectures"]},"CatalogArchitectureSummary":{"type":"object","properties":{"architecture":{"$ref":"#/components/schemas/Architecture"},"firmware":{"$ref":"#/components/schemas/CatalogFirmware"}},"additionalProperties":false,"required":["architecture","firmware"]},"Architecture":{"type":"string","enum":["x86_64","aarch64"],"description":"CPU architecture accepted by the shared machine model."},"CatalogFirmware":{"type":"string","enum":["rhf","edk2"]},"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"}}}}}}}
```


---

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