Relay sharing

A Relay is a temporary, revocable share: text and files, sealed at rest, reachable through a single link whose secret is shown once. The sender can revoke it at any moment, and revoking destroys the ciphertext immediately. Recipients need nothing but the link (and the PIN, if one was set); no account, no wallet.

Three properties carry the design:

Sealed at rest. The content is stored encrypted; the link secret is stored only as a hash, so Sable cannot reconstruct the link after showing it to you once.
Uniformly gone. An expired, revoked, capped-out, or nonexistent link answers the same way: "This Relay has expired or is no longer available." No detail leaks about what was there or why it ended.
View-only is a permission gate, not DRM. With downloads off, the gateway serves only inline-viewable content and refuses file downloads, but someone who can view can screenshot. Do not read view-only as a technical guarantee against copying.

Quickstart

Share a note for 24 hours, PIN-protected, at most 3 opens:

curl https://api.buildsable.com/v1/relays \
-H "Authorization: Bearer $SABLE_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "text": "The rendezvous is at 9.",
  "expires_in_secs": 86400,
  "pin": "4172",
  "max_accesses": 3
}'

{
  "id": "relay_c04b…",
  "status": "active",
  "expires_at": "2026-09-04T17:00:00Z",
  "share_url": "https://buildsable.com/relay/…",
  "allow_download": true,
  "pin_required": true,
  "note": "The link contains the one-time secret; only its hash is stored."
}

The share_url contains the one-time secret and cannot be shown again. Files travel base64-encoded in the create body:

{
  "files": [
    {
      "name": "report.pdf",
      "content_type": "application/pdf",
      "content_b64": "JVBERi0xLjc…"
    }
  ],
  "allow_download": true
}

Endpoints

Owner endpoints are session-authed (Authorization: Bearer sess_…); access endpoints are public, because the recipient holds only the link secret.

Method	Path	Auth	What it does
POST	Path`/v1/relays`	AuthSession	What it doesCreate a relay. Returns the one-time `share_url`.
GET	Path`/v1/relays`	AuthSession	What it doesList your relays: status, access counts, sizes (metadata only). The 100 most recent; there is no cursor.
POST	Path`/v1/relays/{id}/revoke`	AuthSession	What it doesRevoke: destroy the ciphertext immediately.
POST	Path`/v1/relay-access/{secret}`	AuthPublic	What it doesOpen a relay. Body `{pin?}`. Returns `{pin_required: true}` or the content listing.
POST	Path`/v1/relay-access/{secret}/objects/{id}`	AuthPublic	What it doesFetch one file's content. On view-only relays, only `image/` and `text/` are served.

A missing, expired, revoked, or capped-out secret returns 404 uniformly.

Content rules

v1 does no malware scanning. Instead the type allowlist is deliberately conservative, and files are stored sealed and never executed:

Types: text/plain, text/markdown, text/csv, application/json, application/pdf, image/png, image/jpeg, image/gif, image/webp.
Caps: 64KB of text, 5MB total, at most 10 files per relay.

Anything outside the allowlist is refused at creation.

Limits

expires_in_secs: 60 to 604800 (1 minute to 7 days); default 3600.
max_accesses: optional; once the count is reached the link answers like an expired one.
pin: optional; recipients are challenged before any content is served.
allow_download: false makes the relay view-only. Only image/* and text/* objects are served inline; other types become unreachable to the recipient.
Revocation is immediate and irreversible; create a new relay to share again.