Seed API
The Seed API is the HTTP API that every Seed site serves under /api, and this page lists its keys, encodings, errors and sign-in rules.

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

https://hyper.media

the public gateway

serves every public account under /hm/<uid>/…; the SDK and CLI default

https://<any site>

that site's web server

same handlers; the site's daemon holds its own space plus whatever it has synced

http://localhost:56004

the Seed app

the app's local bridge, serving the same keys against your own daemon; 58004 in a dev build

http://localhost:3000

a Seed web app you run yourself

PORT in self-hosting

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

Account, Resource, ResourceMetadata, ListCitations, ListChanges, ListCapabilities, ListRefs, ListDocumentCollaborators, DiscoveryStatus

human-readable keys: ?id=hm://…, ?targetId=hm://…, ?uid=…&path=…

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

__value

keys whose input is a bare string: Comment, AccountContacts, SubjectContacts

?__value=<the 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.

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.

Errors

Status

When

400

no key in the path; a PublishBlobs or PrepareDocumentChange body that decodes but fails input validation (the message names the field); GET /api/schema with a kind that is not query or action

401

the site requires sign-in and the request has no session; the body is {"error":"Sign in required"}

404

an unknown key; the body is {"error":"Unknown query key: <Key>"} or Unknown action key. Also GET /api/schema?key= with an unknown key

500

anything the handler threw, including daemon errors, GET inputs that fail validation and POST bodies that are not valid CBOR; the body is {"error": <message>}

204

OPTIONS preflight

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, Authorization

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.

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

Resource

id=hm://… (flat)

the resource: document, comment, redirect, not-found, tombstone or error

ResourceMetadata

id=hm://… (flat)

{id, metadata, hasSite?} for a document, without its body

Account

id=<uid> (flat)

{type:'account', id, metadata, hasSite?} or {type:'account-not-found', uid}; follows aliases

Comment

__value=<author>/<tsid>

one comment

AccountContacts

__value=<uid>

the contacts an account has published

SubjectContacts

__value=<uid>

the contacts that name an account as subject

Search

query, accountUid?, searchType?, pageSize?, pageToken?, iriFilter?, contentTypeFilter?, entityKindFilter?, perspectiveAccountUid?, contextSize?, includeBody?

{entities: [{id, title, icon, parentNames, type, versionTime?, commentId?}], searchQuery, nextPageToken}

MentionCandidates

mode (account or document), query, perspectiveAccountUid?, siteUid?, documentId?, seedIds?

up to 100 candidates for an @ mention

Query

includes: [{space, path?, mode: 'Children' or 'AllDescendants'}], sort?, limit?

{in, results: DocumentInfo[], mode?} or null; the same shape a Query block embeds

QueryBlock

query, viewer? ({search?, filters?})

the query results plus interaction summaries and author metadata, as the block renders them

ListComments

targetId

{comments, authors} for one document

ListDiscussions

targetId, commentId?

comments grouped into threads

ListCommentsByReference

targetId

comments elsewhere that reference the document

ListCommentsByAuthor

authorId

{comments, authors}

ListCommentVersions

id

every version of one comment

GetCommentReplyCount

id

a number

ListCitations

targetId=hm://… (flat)

{citations: [{source, sourceType, sourceContext, sourceBlob, target, targetVersion, isExactVersion, …}]}

ListChanges

targetId=hm://… (flat)

{changes: [{id, author, deps, createTime}], latestVersion}

ListCapabilities

targetId=hm://… (flat)

{capabilities: [{id, issuer, delegate, account, path, role, label, createTime, …}]}

ListRefs

targetId=hm://… (flat)

{refs}: the Refs published at that path

ListDocumentCollaborators

targetId=hm://… (flat)

who may write: {publisherUid, parentCapabilities, grantedCapabilities, grantedMembers, members, accounts}

InteractionSummary

id

counts of citations, comments, changes and children, per document and per block

ListEvents

pageSize?, pageToken?, filterAuthors?, filterEventType?, filterResource?, targetBlockId?, currentAccount?, order? (claimed or observed), trustedOnly?

the activity feed, each event resolved to its blob

ListAccounts

none

{accounts: [{id, metadata}]}, every account the site knows

GetCID

cid

{value}: any stored blob decoded to DAG-JSON

GetDomain

domain, forceCheck?

what the site knows about another site's domain: {status, registeredAccountUid, peerId, isGateway, lastCheck, …}

ListDomains

none

{domains}

DiscoveryStatus

uid, path, v?, l? (flat)

{state: 'pending' or 'found' or 'failed', version?, error?}; each call also nudges discovery

Write and pass-through keys

Key

Body

Answer

PublishBlobs

{blobs: [{cid?, data}]}

{cids} (superjson)

PrepareDocumentChange

{account, path?, baseVersion?, changes, capability?, visibility?}

{unsignedChange} (superjson)

QueryDocuments

protobuf JSON {filter?, sort?, pageSize?, pageToken?}

{documents, nextPageToken} (protobuf JSON)

ListDocumentAttributeNames

{account?, parentPath?, prefix?, recursive?, pageSize?, pageToken?}

{names: [{name, kinds}], nextPageToken} (protobuf JSON)

ListDocumentAttributeValues

{path, kind, account?, prefix?, pageSize?, pageToken?}

{values, nextPageToken} (protobuf JSON)

ListAccounts (POST)

protobuf JSON ListAccountsRequest

protobuf JSON (a second, unwrapped route to the same list)

ListUnreferencedDocuments

{account, pageSize?, pageToken?}

documents no parent links to (protobuf JSON). The daemon has it switched off, so it answers 500 with unreferenced documents are temporarily disabled

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

Do you like what you are reading? Subscribe to receive updates.

Unsubscribe anytime