API reference

Hugging Face's list shape, so HfApi.list_models works unchanged, plus a hologram block on every row carrying the facts Hugging Face has no field for: the index address of the model, how many files it has, how many bytes of weights, and which sources hold them. A search costs a few hundred bytes; reading the whole catalog object costs several hundred KB, so search here rather than there.

This route lists everything the hub holds, not only what is trending today. Rows for models on the current browse list carry the full facts — task, parameters, library, downloads, licence. Models the browse list has forgotten, but whose bytes this hub has published and still serves, appear as thin rows: the name, the index address, and hologram.listed: false. The facts a browse row carries were never published with the object, so a thin row says so rather than reporting zeros as if they were measurements. Filter on hologram.listed if you want one kind or the other.

Query parameters are checked rather than coerced: a limit outside 1–500 or one that is not a whole number, and a sort outside the enum, each refuse with 400 BadParameter and a sentence saying what is allowed.

Hugging Face's model-info shape. sha is the revision the hub pinned; siblings lists every file. For sizes and hashes ask for the tree instead.

The same answer as getModel, refused unless the revision you name is the one the hub indexed. Use it to fail loudly rather than silently receive a different revision.

Always exactly one branch, main, pointing at the indexed revision. Clients call this before a download to turn main into a commit.

oid is the SHA-256 of the file's bytes, which is the value you check a download against. This is the only place the expected hashes come from: never take a hash from the source that serves the bytes.

The same entries, filtered to one directory prefix.

huggingface_hub follows the hub's redirect, meets Hugging Face's Xet headers there, then asks this endpoint for a Xet read token. That token is Hugging Face's to give, so the hub sends the client there and issues nothing itself.

The route every download goes through. The hub answers 302 to the first source in its preference order that passed the last probe, and puts the expected SHA-256 in ETag and X-Linked-Etag and the serving source in X-Hub-Source. No weight byte passes through the hub.

Ask for the path SHA256SUMS and the hub synthesises the checksum file for the whole model instead, so a download can be checked with sha256sum -c and no tool of ours.

The caller states the policy and the hub executes it: /via/ipfs/... serves from IPFS even when Hugging Face is up. The prefix works in front of any Models or Files route, not only this one.

A pin is a constraint, not a hint. If the named source does not hold the file this refuses with 404 SourceHasNotGotIt, naming the sources that do; an unrecognised source name refuses with 404 UnknownSource. It does not quietly serve you something else. That matters most for the obvious use of a pin — fetching the same file through two sources and comparing them — which is worthless if one fetch can silently come from the other's host.

X-Hub-Source still names who served, and on this route it will always equal the source you asked for. Drop the prefix to let the hub choose by health and order.

The same rows as listModels. The prefix is accepted on every read route so a client can be configured once, with HF_ENDPOINT=https://gethologram.ai/via/ipfs, and never choose again.

200 {} means version 2 of the distribution API is supported and reads are anonymous. docker login is needed only to push.

The hub's registry namespace only, model-hub/index among them. Model repositories are answered from the index and do not appear here; ask for a model's tags directly.

latest always, plus one tag per single-file GGUF quantisation, which is what ollama pull …:Q4_K_M asks for. Owner and name must be lowercase: OCI references are case-sensitive and lowercase-only.

One route, two answers, chosen by Accept. Send the OCI manifest type and the hub answers a CNCF ModelPack artifact whose layers are the model's files, each layer digest being that file's SHA-256, which oras, modctl, skopeo and crane all verify for you. Send the Docker manifest type, which is what Ollama sends, and the hub answers a GGUF model manifest; models with no GGUF file refuse it.

Small layers (config, chat template, parameters) are answered directly, each checked against its digest before the hub keeps it. Weight layers are a redirect to a live source; the client verifies the digest, as every OCI client already does. HEAD answers 200 with the size directly, because newer Ollama refuses a cross-host redirect on HEAD.

Streamable HTTP, stateless, anonymous, POST only. Protocol versions 2026-07-28, 2025-11-25, 2025-06-18 and 2025-03-26 are accepted. Three tools: search_models finds one, get_model lists its files with sizes and hashes, resolve_file gives a URL, the SHA-256 it must have, and the command that hands the file to an engine.

Weight bytes never travel in a tool result: the tool returns the instruction, the agent's shell or engine does the download.

get_model returns at most 200 files. When a model has more it keeps every config, tokenizer and other small text file first, fills the remainder with the largest weights, and sets files_truncated and files_truncated_note; files_total always counts the whole model. It truncates by usefulness rather than alphabetically, because the tail of a model directory is where the tokenizer lives and a caller cannot proceed without it. For the complete list use listModelFiles.

Every operation the server exposes, which modules are loaded, and the hard limits. maximum_message_bytes is 32 MiB: anything larger is published as chunks.

One entry per module, with the operations it owns and whether it is ready.

Needs a publisher token. Reading a known address needs none. There is no anonymous listing, on purpose: the catalog is the public index and it is one object away.

The body is the bytes; the response id is their BLAKE3 address. Up to 8 MiB per request at the edge, 32 MiB at the server. Larger payloads are published as chunks and joined by a source record.

The content-addressed floor. The answer for an address never changes, so it is served immutable with a one-year lifetime and may be cached forever. The server does not verify on read: hash what arrives and keep it only if the BLAKE3 equals the address you asked for.

The one account route that needs no token. configured: false means this hub has no sign-in keys, which changes nothing for anonymous callers.

What the hub holds for this person: nothing but a saved list, the models they asked for, and a wallet address they chose to report.

The address is Privy's to mint and the page's to report. It is recorded and never trusted for anything.

A list the person keeps, nothing more. It is not a download, a pin or a claim on anything.

Removing something that is not there is not an error.

The anonymous version of this already happens: the endpoint records every model it is asked for and does not have. Signing in only adds attribution, so the operator can tell one person asking ten times from ten people asking once.

It issues nothing and grants nothing. Who may write to this registry is an operator's decision, and a decision is not something a web form gets to make.

The Hologram Server behind the object routes. status: ready means the object plane answers; it says nothing about byte sources, which have their own probe.

The result of the hub's own periodic probe of every source it can redirect to, and the order it prefers them in. A file request is sent to the first source in order that is ok.

This is measured from the hub, not from you. A source reported ok here can still be unreachable from the network you are on — ipfs.filebase.io in particular is blocked or TLS-terminated on some networks while the hub reaches it fine. Read this as the hub's routing preference, not as a promise about your own failover. If failover matters to you, test a /via/{source} fetch from where your code will actually run.

One URL, three readers, chosen by Accept.

A browser sends text/html and gets the website. A caller that asks for application/json by name gets the descriptor, which points at today's catalog address and at everything else here. Anything else — */*, which is what curl, node's fetch and python's requests all send, and therefore what an arriving agent actually asks — gets agent.md: the whole hub on one screen, in the imperative, ending in a check it can run itself.

So curl gethologram.ai is the shortest useful thing an agent can be told about this service.

The same bytes as GET / with Accept: application/json. Start here if you were given nothing but the host name.

The whole endpoint, every dialect, in one OpenAPI 3.1 document. /docs renders it. Both paths serve the same bytes; the well-known one exists because that is where an agent looks first.

The whole endpoint, every dialect, in one OpenAPI 3.1 document. /docs renders it. Both paths serve the same bytes; the well-known one exists because that is where an agent looks first.

The hub described as a set of skills, for frameworks that discover services through an agent card rather than an OpenAPI document.

One screen of plain markdown: what this is, the one line that switches an existing tool over, the three requests that use it directly, and the rule that makes the bytes safe. It is what GET / answers to anything that is not a browser, and it ends with a check the reader can run to confirm the rest. The last line is a canary: a fetcher that summarises drops it, and an agent that cannot see it knows to fetch this path again verbatim.

The site shows this address beside the models heading — the same tag on every section, so one shape covers all five. A browser gets the section's page; anything else gets a brief covering finding a model, proving it and fetching it: the few requests that do the job, in the order you would make them, with the rule that makes the bytes safe. Ask for application/json and the same address answers a section descriptor: one fixed shape, the same on all five sections, naming how to enumerate this section, how to reach one item, how to fetch its bytes and how to check them. Where the section has a snapshot, catalog.address is a content address holding the whole of it, so the entire section is one verifiable fetch. Where it has none the field is null and list carries a live route instead; no section borrows a catalogue it does not have. It adds no API — every route the descriptor names is already in this document. What was missing was an address that gathers them, which the site was already advertising. The trailing slash works either way, and a page below the section, such as a single model or one docs page, is untouched.

The site shows this address beside the registry heading — the same tag on every section, so one shape covers all five. A browser gets the section's page; anything else gets a brief covering pulling the same models as OCI artifacts: the few requests that do the job, in the order you would make them, with the rule that makes the bytes safe. Ask for application/json and the same address answers a section descriptor: one fixed shape, the same on all five sections, naming how to enumerate this section, how to reach one item, how to fetch its bytes and how to check them. Where the section has a snapshot, catalog.address is a content address holding the whole of it, so the entire section is one verifiable fetch. Where it has none the field is null and list carries a live route instead; no section borrows a catalogue it does not have. It adds no API — every route the descriptor names is already in this document. What was missing was an address that gathers them, which the site was already advertising. The trailing slash works either way, and a page below the section, such as a single model or one docs page, is untouched.

/v2/ itself is deliberately left alone: it is a protocol endpoint and OCI clients depend on exactly what it returns.

The site shows this address beside the spaces heading — the same tag on every section, so one shape covers all five. A browser gets the section's page; anything else gets a brief covering browser-only apps, each sealed under one root digest, and how to read one from the registry: the few requests that do the job, in the order you would make them, with the rule that makes the bytes safe. Ask for application/json and the same address answers a section descriptor: one fixed shape, the same on all five sections, naming how to enumerate this section, how to reach one item, how to fetch its bytes and how to check them. Where the section has a snapshot, catalog.address is a content address holding the whole of it, so the entire section is one verifiable fetch. Where it has none the field is null and list carries a live route instead; no section borrows a catalogue it does not have. It adds no API — every route the descriptor names is already in this document. What was missing was an address that gathers them, which the site was already advertising. The trailing slash works either way, and a page below the section, such as a single model or one docs page, is untouched.

The site shows this address beside the buckets heading — the same tag on every section, so one shape covers all five. A browser gets the section's page; anything else gets a brief covering walking a bucket as an OCI index tree and checking every block against its address: the few requests that do the job, in the order you would make them, with the rule that makes the bytes safe. Ask for application/json and the same address answers a section descriptor: one fixed shape, the same on all five sections, naming how to enumerate this section, how to reach one item, how to fetch its bytes and how to check them. Where the section has a snapshot, catalog.address is a content address holding the whole of it, so the entire section is one verifiable fetch. Where it has none the field is null and list carries a live route instead; no section borrows a catalogue it does not have. It adds no API — every route the descriptor names is already in this document. What was missing was an address that gathers them, which the site was already advertising. The trailing slash works either way, and a page below the section, such as a single model or one docs page, is untouched.

The browse page: every model the hub lists, with its files, sizes and addresses. For people; anything that is not a browser gets the section brief instead of 236 KB of markup. A page below this one, such as a single model, is untouched by that and always answers HTML.

A reference page for people, built from /openapi.json at load time. It is the same contract as the document; nothing is written twice.

Overview, quickstart, the concepts, one page per dialect, and a reference generated from this document. Every page has a Markdown twin at /docs/{page}.md, and /llms.txt lists them all.

This is also the address the site shows beside the Docs heading, the same tag every section carries. A browser gets this index; anything else gets the section brief, which lists every page and the address of its twin, generated from the pages themselves. The slash is load-bearing: /docs without one is the server's own API reference, on a different upstream.

The page named by its slug: quickstart, verification, addresses, sources, huggingface, ollama, oci, mcp, objects, api, errors, limits.

The same page as /docs/{page}/, from the same source, with every link resolved to an absolute Markdown twin. index.md is the overview.

A page over /v2/: every repository and tag the hub's registry holds, each layer verified in the browser against its digest. For people; a client uses /v2/ directly, and anything that is not a browser gets the section brief instead of the markup.

Five demo Apps (speech, image, chat, vision, depth). Every file of an App is sealed under one root digest, its model bytes are accepted only when they re-derive to the digest the model index names, and nothing runs on a server. An App published to the registry lives at /v2/spaces/<id> as an OCI artifact of type application/vnd.hologram.space.v1+json.

{ format: "hologram.spaces.catalog/v1", spaces: [{ id, name, task, tagline, root, bytes, files, models, modelHost, modelBytes, source, requires, entry }] }. root is SHA-256 over the App's file map; entry is the page to open.

Prose, not a schema: what to do, in order, with the tools an agent already has. Read this when you would otherwise guess.

One row per day: the index address, its IPFS CID, how many models and files it held, and the previous day. The chain lets anyone replay the hub's history and check each step.

The models whose weights the hub can still serve when Hugging Face and ModelScope are both unreachable, with the IPFS root of each and the gateway to read it through.

Allows the website, the discovery paths and this document; asks crawlers to leave redirect and blob routes alone, because they cost a byte source real traffic.