Site services
Site services are the fixed routes every Seed site serves beside the Seed API, such as /hm/api/config, sign-in, files, exports and turning a web URL into an hm:// id.

A Seed site answers two kinds of HTTP request from programs. The first kind is the Seed API under /api/<Key>, where you ask for documents and publish. The second kind is the site services: fixed addresses that every site has. For example, https://hyper.media/hm/api/config tells you which space the site publishes.

This page lists the site services that the web server serves. They come in four groups: the /hm/api/* routes, files and raw blobs under /ipfs, document exports that you get by adding .md or .json, and the headers that turn a web URL into an hm:// id.

The /hm/api routes

A site needs these routes to work as a site. The Seed app or the site's own pages call most of them. If you build on Seed, the useful ones are /hm/api/config, /hm/api/version and /hm/api/discover. The table lists every /hm/api/* route the web server has.

Route

Method

Purpose

/hm/api/config

GET

{registeredAccountUid, peerId, protocolId, signerAccountUid, addrs, hostname, isGateway, notifyServiceUrl, notifyServiceHost, appEnvironmentUrl, agentServerUrl, requireSignIn}; CORS open, no auth. The one call to learn which space a domain publishes and how to reach its daemon. The fields are explained under the table.

/hm/api/site-url

GET

{hostname, siteUrl}: the site's hostname next to the siteUrl that the home document of its space carries (null when there is none), so an operator can see when the two differ

/hm/api/auth

POST, DELETE, OPTIONS

protobuf AuthenticateRequest in, bearer cookie out; DELETE clears it

/hm/api/session

GET

answers 204 when the request has a sign-in session or the site does not require sign-in; the reverse proxy calls it before each request on a site that requires sign-in

/hm/api/version

GET

{web: {commit, branch, date}, daemon: {commit, branch, date}}

/hm/api/file/<cid>

GET

streams /ipfs/<cid> through the web server, forwarding Range and the visitor's cookie

/hm/api/image/<cid>?size=S,M,L,XL

GET

the image resized to 120, 650, 1600 or 4000 px wide as PNG; GIFs pass through

/hm/api/content-image?space=&path=&version=

GET

the 1200 by 630 Open Graph image of a document

/hm/api/discover

POST JSON {uid, path, version?, media?}

make the site fetch a document now, blocking until done; DiscoveryStatus is the non-blocking form

/hm/api/register

POST JSON {registrationSecret, accountUid, peerId, addrs}

bind a space to this site; the Seed app calls it from the registration link

/hm/api/admin

POST JSON {adminSecret, adminAction}

the multi-tenant control plane of a hosting service; disabled unless the operator sets a secret

/hm/api/site-image

POST bytes

square-crop an icon to 512 px

/hm/api/writable-locations?account=<uid>

GET

the account's own space plus every space or path it holds a WRITER or AGENT capability for; the web app uses it to offer places to publish

/hm/api/delegate-device

POST CBOR

stores the three blobs that link a browser key to an app key; the web app calls it during device linking

/hm/api/page?id=&version=&cid=

GET

the HTML entry file of a custom page, returned as plain text, only when that document version really names that file

/hm/api/enterprise-bootstrap, /hm/api/enterprise-site-url

POST JSON

first setup of a self-hosted organization node, and republishing its siteUrl after a hostname change; both need the vault admin secret and are called by the deploy script

/hm/api/document-update

POST CBOR

stores a change, a Ref and an icon; accepted for older clients, which should use PublishBlobs

/hm/api/resource/<uid>/<path>?v=&l

GET

superjson Resource; accepted for older clients, which should use GET /api/Resource?id=

curl https://hyper.media/hm/api/config
{"registeredAccountUid":"z6MkfzKMhF9k1oPaQsShWAg8xJzbWf5kaZgn1MkeZvhcAsmB","peerId":"12D3KooWEDdEeuY3oHCSKtn1eC7tU9qNWjF9bb8sCtHzpuCjvomQ","protocolId":"/hypermedia/0.9.2","signerAccountUid":"z6MktB9d9djZFYDzrQ8jpgveVpjdBADZDtQUFaU8ygD37YYU","addrs":["/dns4/hyper.media/tcp/56001/p2p/12D3KooWEDdEe…","/dns4/hyper.media/udp/56001/quic-v1/p2p/12D3KooWEDdEe…"],"hostname":"https://hyper.media","isGateway":true,"notifyServiceUrl":"https://hyper.media/hm/api/notify","notifyServiceHost":"https://hyper.media","appEnvironmentUrl":"https://hyper.media/hm/api/apps","agentServerUrl":"https://hyper.media/hm/api/apps","requireSignIn":false}

The fields of /hm/api/config:

    registeredAccountUid is the space this site publishes, or null when no space is registered.

    peerId, protocolId and addrs say how to reach the site's daemon on the network.

    signerAccountUid is the account the web server itself signs with.

    hostname is the site's base URL, and isGateway is true when the site serves every public account under /hm/<uid>/….

    notifyServiceUrl is the base URL of the notify service, normally <origin>/hm/api/notify. notifyServiceHost is its origin only, for older clients.

    appEnvironmentUrl is the app environment the site uses, or null. agentServerUrl is the older name of the same field.

    requireSignIn is true when the site only answers signed-in visitors.

Email notification endpoints (/hm/api/notify/*, and the older /hm/api/notifications, /hm/api/notification-config, /hm/api/public-subscribe and friends) are not part of the web server. The reverse proxy routes them to the notify service, which /hm/api/config advertises as notifyServiceUrl. The web server only serves the email settings page, /hm/email-notifications. There is no sitemap, no RSS and no .well-known route. robots.txt allows everything.

A bearer token is a secret string that proves you hold an account key. Authentication explains bearer tokens, the cookie that /hm/api/auth sets, and what they let you read. Privacy explains private content. The routes of an app environment mounted on a site, /hm/api/apps/* and /hm/api/agents/*, are the signed API.

Resolving a web URL to an hm:// id

Any document URL on a site answers OPTIONS with the document's identity in headers. This is how the SDK and the CLI turn a pasted https:// link into an id without parsing HTML.

curl -X OPTIONS -I 'https://seed.hyper.media/resources/self-host-seed'
HTTP/2 200 access-control-expose-headers: X-Hypermedia-Id, X-Hypermedia-Version, X-Hypermedia-Title, X-Hypermedia-Target, X-Hypermedia-Authors, X-Hypermedia-Type x-hypermedia-id: hm%3A%2F%2Fz6Mko5npVz4Bx9Rf4vkRUf2swvb568SDbhLwStaha3HzgrLS%2Fresources%2Fself-host-seed x-hypermedia-version: bafy2bzacedia6ddwuoefhwcujtlwzwffshysz6peixz7pndfrjchtoqry7qt6 x-hypermedia-title: Self-Host%20a%20Seed%20Website x-hypermedia-type: Document x-hypermedia-authors: hm%3A%2F%2Fz6MkfnCSnmstMXTAb6MBXXCj4zdPwZedtRF6YBgYtE5Q8Sov,hm%3A%2F%2Fz6MkgisVMELvqnsCo3dYmtVpy8PiqPGMVwfAyBWFn84vebq4,…

Values are URL-encoded. X-Hypermedia-Type is Document or Comment. A comment URL adds X-Hypermedia-Target with the document it belongs to. The same headers ride on the GET of the page, and the page's HTML repeats them as <meta name="hypermedia_id"> and similar tags. When the URL cannot be resolved the response is still 200, with only the CORS headers, so check for X-Hypermedia-Id before trusting it. The URL grammar itself is in URLs.

Exports: append .md or .json

Add .md or .json to a document's URL and the site returns the document in that format. The Accept header plays no part.

URL

Returns

/<path>.md, /hm/<uid>/<path>.md

the document as markdown with frontmatter, mentions resolved and query blocks executed; text/markdown

/<path>.json

the Resource payload as plain JSON (not superjson)

/<path>.md/:comments, /<path>.md/:comments/<uid>/<tsid>

the discussion, or one comment

/<path>.md/:attributes

the document's attributes

/<path>.json/:activity, …/:activity/comments, …/:activity/versions, …/:activity/citations

activity views, paged with ?pageSize=&pageToken=

/<path>.json/:collaborators, /<path>.json/:directory, /<path>.json/:all-documents

collaborators, direct children, the whole subtree

?v=<version> pins a version and ?l forces latest, as on the page itself. Exports are cached for a minute (Cache-Control: public, max-age=60) and carry the X-Hypermedia-* headers.

curl 'https://seed.hyper.media/resources/self-host-seed.md' | head -6
--- name: Self-Host a Seed Website cover: ipfs://bafkreie6wls4wzt26vl3smvcc5smulmbostaokyftwmig2ojfpkhbmbee4 --- If you want to publish on your own domain without relying on our service, you are welcome to self-host your site. …

Files and raw blobs: /ipfs/<cid>

GET /ipfs/<cid> returns the bytes behind any content id the site's daemon holds or can fetch: an image, a PDF, or a signed blob. Files stored as UnixFS are reassembled. Range requests work, and ?filename= sets the download name. The content type is always application/octet-stream, so sniff it yourself. Append .dagjson to see a structural blob decoded. A block of a document shows up inside its Change blob, as in this example.

curl 'https://hyper.media/ipfs/bafy2bzacedia6ddwuoefhwcujtlwzwffshysz6peixz7pndfrjchtoqry7qt6.dagjson'
{ "body": {"opCount": 1, "ops": [{"block": {"id": "B_AgOiKa", "text": "curl -fsSL https://deploy.seed.hyper.media | sh", "type": "Code", "language": ""}, "type": "ReplaceBlock"}]}, "deps": [{"/": "bafy2bzaceboabcqmrardnurha7lfk3rrnochhhgokqw26eid77hcvymre2fgs"}], "depth": 3, "genesis": {"/": "bafy2bzacedvbzyb7237wk44qnl7fdu7i24aurdkjzcctleuyqlsjckcynbqru"}, "sig": {"/": {"bytes": "/UZZZ5CuMvn1efgys7OXDhpthz3UB53PeXAV008LW9i72T/9KW+gebQU6U6s1w+9uPB6f6SBZxD0QsC/rZ+YCw"}}, "signer": {"/": {"bytes": "7QG0a+na…"}}, … }

On hosted sites this path goes straight to the daemon, bypassing the web server, so a bearer cookie does not reach it. A daemon looks for an unknown id on the network for up to a minute before answering 408, and a blob that no public document, comment or profile links to is not served as public even when stored. Files covers this.

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

Unsubscribe anytime

Connections0
Linked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkSite servicesSite services
Citations 0Children & links 28

Loading child documents…

Connections show where other documents or comments link to this document.

Related documents

Loading connections…