Seed Hypermedia handles document deletion and URL changes through the Ref system. Rather than actually deleting content (which would break content-addressed references), you create special refs that indicate the document's new state.
Understanding Refs
A Ref is a signed pointer that maps an account + path to a target. The target can be one of three types:
Version - points to a specific document version (the normal case)
Redirect - forwards to a different account + path
Tombstone - marks the document as deleted
Deleting a Document (Tombstone)
To delete a document, create a ref with a tombstone target. The old content still exists in the content-addressed store, but the path now resolves to 'deleted'.
grpcurl -plaintext -d '{
"account": "z6Mk...",
"path": "/old-document",
"target": {
"tombstone": {}
},
"signing_key_name": "my-key"
}' localhost:55002 com.seed.documents.v3alpha.Documents/CreateRefImportant: Tombstones are permanent declarations of intent. While the underlying content remains accessible by CID, the path will no longer resolve to it.
Redirecting a Document
To move content to a new URL or consolidate documents, use a redirect ref:
grpcurl -plaintext -d '{
"account": "z6Mk...",
"path": "/old-path",
"target": {
"redirect": {
"account": "z6Mk...",
"path": "/new-path"
}
},
"signing_key_name": "my-key"
}' localhost:55002 com.seed.documents.v3alpha.Documents/CreateRefRedirects can point to:
A different path in the same account (internal move)
A path in a different account (cross-account redirect)
Republishing Redirects
A special type of redirect is the republishing redirect. Instead of showing a 'redirected' message, it transparently displays the target content at the original URL. Set republish: true in the redirect target.
Handling Redirects as a Client
When GetDocument encounters a redirect, it returns a RedirectErrorDetails in the error response. Clients should:
Track visited paths to prevent infinite redirect loops
Limit redirect chain depth (e.g., max 10 redirects)
Follow the redirect to the new target
Best Practices
Guidelines for managing document lifecycle:
Prefer redirects over tombstones when content moves - preserves discoverability
Use tombstones only for truly deleted content
Keep redirect chains short - each hop adds latency
Consider republishing for seamless URL migrations