Read keys are GET /api/<Key>?…. The query string is the key's input, encoded in one of three ways. The SDK picks the right one for you. When you hand-write requests you need to know which applies.

The simplest read is a document by its hm:// id.

An account is read by its uid. The answer is the account's home document metadata.

A search takes JSON values. query is a plain string, and a number stays a number.

A key with an object input, such as ListComments, takes the object as a JSON string in one parameter. The SDK writes ?targetId=%7B%22uid%22%3A%22z6Mk…%22%2C%22path%22%3A%5B%22resources%22%5D%7D. It is easier to let the SDK or the CLI build this than to write it by hand.

Write keys are POST /api/<Key> with the input encoded as DAG-CBOR and Content-Type: application/cbor. The server does not check the content type, but the body must decode as CBOR. Two write keys matter. A handful of listing keys also use POST.

PublishBlobs is how anything gets onto the network. Its input is {blobs: [{cid?, data}]}, where data is the bytes of a signed blob and cid is that blob's content id. The server stores the blobs in the site's daemon, which verifies the signature of every structural blob it recognises and indexes it. The output is {cids: [...]}.

Give every blob its cid. When you omit it, the daemon computes the id with its own default hash, BLAKE2b, while the SDK computes SHA-256 ids. A blob that another blob points at by id must therefore carry the SHA-256 id you computed when you signed it, or the link will not resolve. Blobs explains the two hashes.

PrepareDocumentChange asks the daemon to build an unsigned Change for you from a list of edit operations, so you do not have to compute the change DAG yourself. The input is {account, path?, baseVersion?, changes: [{op: {case, value}}], capability?, visibility?}, the output {unsignedChange: bytes}. You sign the bytes and publish the result with PublishBlobs. The SDK does the whole sequence in publishDocument.

The remaining POST keys, QueryDocuments, ListDocumentAttributeNames, ListDocumentAttributeValues, ListAccounts and ListUnreferencedDocuments, are pass-throughs to the daemon's own request messages. Their body is the CBOR encoding of the protobuf JSON form of the request, with lowerCamelCase field names and enum names as strings, and they answer with plain protobuf JSON. They do not use the envelope described next. QueryDocuments is the attribute query surface. Its filter grammar is in query grammar.

Every read key and the two publishing keys answer 200 with a JSON body wrapped by superjson: {"json": <output>, "meta"?: …}. The meta member appears when the output holds a Date, a bigint or an explicit undefined, as in the Account response above. Unwrap by taking json, or let superjson restore the types for you. The pass-through keys answer with the daemon's protobuf JSON unwrapped. The SDK tells the two apart by looking for a top-level json member.

Not-found is never an HTTP status. Resource answers one of six shapes in the payload: document, comment, redirect (with redirectTarget and republish), not-found, tombstone or error. Check the shape in the payload.

Every Seed API response carries these headers.

Any web page may call the API cross-origin. The server never sends Access-Control-Allow-Credentials, so a cross-origin browser call cannot use the site's auth cookie. Send an Authorization header instead. Nothing is cached, which is right for a view that depends on who asks.

Reading public content needs nothing. Authentication matters in two cases: reading content the site holds as private, and writing on behalf of a signed-in visitor through PrepareDocumentChange. In both, the site forwards a daemon bearer token to its daemon, and the daemon decides.

A token is proof that you hold an account key. POST /hm/api/auth takes a binary protobuf AuthenticateRequest {account, timestamp, signature}, where the signature covers an ephemeral capability naming the site daemon's peer id as audience, and the timestamp must be within five minutes of the daemon's clock. The daemon mints a token that lives thirty days, and the web server sets it as an httpOnly cookie named __Host-HM-Auth-Token (HM-Auth-Token outside production). The web app does this for you after "Sign in with Seed". See sign-in.

For a script or an agent, pass the token yourself: Authorization: Bearer <token> on any /api/* request. An explicit header wins over the cookie and is forwarded verbatim to the daemon. Two limits apply. A daemon only issues tokens for principals it has already seen in a signed blob, so a brand-new key must publish something first. A token cannot be revoked on its own. Only the daemon operator can invalidate all of them at once.

Writing does not need a token. Authority to write is in the blob itself: a Ref signed by the space owner, or by a key that holds a capability from the owner, is accepted from anyone who submits it. A comment signed by any key is accepted on any public document.

GET /api/schema lists every key with its method and path. GET /api/schema?key=<Key> returns one key's input and output as JSON Schema, along with how the input is encoded.

?kind=query or ?kind=action filters the list. The list can miss the pass-through keys. The 2026.9.9 release on hyper.media lists only PublishBlobs and PrepareDocumentChange as actions. Newer builds also list QueryDocuments and the two attribute keys, but mark them outputSerialization: superjson. Those keys answer plain protobuf JSON.

The Seed CLI is a Seed API client. seed-cli --server https://example.org document get <id> sends the Resource key to that site. search, query, children, citations, activity, account and comment list map onto the read keys above, and every write command signs locally and calls PublishBlobs. Pass an https:// URL as an id and the CLI resolves it with the OPTIONS headers and talks to that URL's site.

createSeedClient(baseUrl) from @seed-hypermedia/client gives client.request(key, input) with typed inputs and outputs for every key, choosing the encoding and unwrapping the envelope. client.publish(blobs) is PublishBlobs. client.publishDocument(input, signer) runs PrepareDocumentChange, signs and publishes. Pass {headers: {Authorization: 'Bearer …'}} to authenticate. The SDK page has the builders for changes, refs, comments, capabilities and contacts.

Seed Agents read and write hypermedia through this API with delegated keys. Their search, query and attributes tools map to the Search, Query/QueryDocuments and attribute keys, and their write verb ends in PublishBlobs. An external agent, such as Claude Code with the seed-cli skill, uses the CLI or curl exactly as above. An agent with no key of its own can read everything public. To write, it needs a key and a capability from the space owner, which Using Seed from your own agent walks through.