Every Seed site is also an API server. You can ask it for documents, comments, search results and accounts with plain HTTP requests. You can also send it signed blobs to publish. You do not need to run anything to read from the network. A curl against any site is enough. The web server that shows https://hyper.media in a browser is the same program that answers these requests.
A site answers two kinds of request. The first is the Seed API: every address under /api/ is one question you can ask. /api/Resource returns a document, and /api/Search searches. The name after /api/ is called a key. Each key has a fixed input and a fixed output. This page covers the Seed API. The second kind is the site services: fixed addresses for configuration, sign-in, files, images and exports. The SDK, the CLI and Seed Agents all use the Seed API.
Base URLs
The base URL is the site's address, such as https://hyper.media. The key comes after /api/. For a read, you put the input in the query string. For a write, you put it in the body.
Base URL | What answers | Notes |
|---|---|---|
| the public gateway | serves every public account under |
| that site's web server | same handlers; the site's daemon holds its own space plus whatever it has synced |
| the Seed app | the app's local bridge, serving the same keys against your own daemon; |
| a Seed web app you run yourself |
|
The gateway answers for accounts it knows about. A site's own space is always there. Other accounts are there when the site has synced them. If a resource is unknown, the Resource key answers not-found in the payload and the site starts discovering it in the background. See DiscoveryStatus below.
Calling the Seed API
Reads are GET requests
A read is GET /api/<Key>?…. The query string holds the key's input. There are three ways to encode it, and each key uses one of them. The SDK picks the right one for you. When you write requests by hand, check this table.
Encoding | Which keys | How the input travels |
|---|---|---|
flat params |
| human-readable keys: |
JSON values | every other key whose input is an object | each top-level field is one query parameter; primitives as-is, nested objects and arrays as JSON strings (URL-encoded); the server parses each value as JSON and keeps the raw string if that fails |
| keys whose input is a bare string: |
|
The simplest read is a document by its hm:// id.
curl 'https://hyper.media/api/Resource?id=hm://z6Mko5npVz4Bx9Rf4vkRUf2swvb568SDbhLwStaha3HzgrLS/resources/self-host-seed'{"json":{"type":"document","id":{"id":"hm://z6Mko5npVz4Bx9Rf4vkRUf2swvb568SDbhLwStaha3HzgrLS/resources/self-host-seed","uid":"z6Mko5npVz4Bx9Rf4vkRUf2swvb568SDbhLwStaha3HzgrLS","path":["resources","self-host-seed"],"version":null,"latest":true,…},"document":{"content":[{"children":[],"block":{"type":"Paragraph","id":"OtLkse-T","text":"If you want to publish on your own domain…","annotations":[],"attributes":{},"link":""}},…],"metadata":{"name":"Self-Host a Seed Website","cover":"ipfs://bafkreie6…"},"version":"bafy2bzacedia6…","genesis":"bafy2bzacedvbz…","authors":["z6MkfnCSnmst…"],…}}}An account is read by its uid. The answer is the account's home document metadata.
curl 'https://hyper.media/api/Account?id=z6Mko5npVz4Bx9Rf4vkRUf2swvb568SDbhLwStaha3HzgrLS'{"json":{"type":"account","id":{"id":"hm://z6Mko5npVz4Bx9Rf4vkRUf2swvb568SDbhLwStaha3HzgrLS","uid":"z6Mko5np…","path":[],"version":"bafyreigjdxq…"},"metadata":{"name":"Seed Hypermedia","icon":"ipfs://bafkreihpk5…","siteUrl":"https://seed.hyper.media","contentWidth":"L",…}},"meta":{"values":{"metadata.summary":["undefined"]}}}A search takes JSON values. query is a plain string, and a number stays a number.
curl 'https://hyper.media/api/Search?query=hypermedia&pageSize=2'{"json":{"entities":[{"id":{"id":"hm://z6MkfzKMhF9k1oPaQsShWAg8xJzbWf5kaZgn1MkeZvhcAsmB","uid":"z6MkfzKM…","path":[],"version":"bafyreienub…","latest":true},"title":"Hypermedia","icon":"ipfs://bafkreifcj…","parentNames":[],"versionTime":"6/8/2026, 11:57:06 PM","searchQuery":"hypermedia","type":"document"},…],"searchQuery":"hypermedia","nextPageToken":"…"}}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.
Writes are POST requests with a CBOR body
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 keys write: PublishBlobs and PrepareDocumentChange. Five 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. A blob sent without one gets an id from the daemon's own hash, which is not the id the blob was signed and linked under, and links to it do not resolve. Blobs has the rule and 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.
Two response envelopes
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.
Errors
Status | When |
|---|---|
| no key in the path; a |
| the site requires sign-in and the request has no session; the body is |
| an unknown key; the body is |
| anything the handler threw, including daemon errors, GET inputs that fail validation and POST bodies that are not valid CBOR; the body is |
|
|
curl -w ' [%{http_code}]' 'https://hyper.media/api/Nope'{"error":"Unknown query key: Nope"} [404]Headers, CORS and caching
Every Seed API response carries these headers.
content-type: application/json; charset=utf-8
cache-control: private, no-store
access-control-allow-origin: *
access-control-allow-methods: GET, POST, OPTIONS
access-control-allow-headers: Content-Type, AuthorizationAny 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.
Authentication
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 bearer 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.
Discovering the API
The API describes itself. GET /api/schema lists every read key and the five action keys (PublishBlobs, PrepareDocumentChange, QueryDocuments, ListDocumentAttributeNames, ListDocumentAttributeValues), each with its method and path. It leaves out the POST forms of ListAccounts and ListUnreferencedDocuments. GET /api/schema?key=<Key> returns one key's input and output as JSON Schema, along with how the input is encoded.
curl 'https://hyper.media/api/schema?key=Resource'{"key":"Resource","kind":"query","method":"GET","path":"/api/Resource","inputEncoding":"query-string","outputEncoding":"application/json","outputSerialization":"superjson","usesParamMapping":true,"inputSchema":{"$ref":"#/definitions/ResourceInput","definitions":{"ResourceInput":{"type":"object","properties":{"id":{"type":"string"},"uid":{"type":"string"},"path":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"version":{"type":["string","null"]},…}}}},"outputSchema":{…}}?kind=query or ?kind=action filters the list. The schema marks every key outputSerialization: superjson. The pass-through keys answer plain protobuf JSON all the same.
The keys
The two tables list every key the web server answers under /api/. Inputs are given as the fields you send. Read the exact shapes from GET /api/schema?key=. id-like inputs are an unpacked hm id {uid, path, version?, latest?, blockRef?}. In flat encoding you send the packed hm:// string.
Read keys
Key | Input | Output |
|---|---|---|
|
| the resource: |
|
|
|
|
|
|
|
| one comment |
|
| the contacts an account has published |
|
| the contacts that name an account as subject |
|
|
|
|
| up to 100 candidates for an |
|
|
|
|
| the query results plus interaction summaries and author metadata, as the block renders them |
|
|
|
|
| comments grouped into threads |
|
| comments elsewhere that reference the document |
|
|
|
|
| every version of one comment |
|
| a number |
|
|
|
|
|
|
|
|
|
|
|
|
|
| who may write: |
|
| counts of citations, comments, changes and children, per document and per block |
|
| the activity feed, each event resolved to its blob |
| none |
|
|
|
|
|
| what the site knows about another site's domain: |
| none |
|
|
|
|
Write and pass-through keys
Key | Body | Answer |
|---|---|---|
|
|
|
|
|
|
| protobuf JSON |
|
|
|
|
|
|
|
| protobuf JSON | protobuf JSON (a second, unwrapped route to the same list) |
|
| documents no parent links to (protobuf JSON). The daemon has it switched off, so it answers |
The desktop bridge differs in two ways
The Seed desktop app serves the same keys on http://localhost:56004/api/* for local tools such as the CLI's space dev and the bundled app environment. It refuses requests whose Sec-Fetch-Site header marks them cross-site, so a web page cannot call it. It also lacks the pass-through special case. POST /api/QueryDocuments answers superjson there, and POST ListAccounts and ListUnreferencedDocuments answer 404.
Working with it
CLI
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.
SDK
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.
Agents
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.
See also
Site services, the routes a site serves beside /api: /hm/api/*, /ipfs/<cid>, exports and URL resolution
Getting started, the first requests in fifteen minutes
Daemon gRPC, the lower layer every site server calls
Self-hosting, for the server that answers these requests
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime