Reserved addresses

A reserved address is a /{username}/{slug} URL that exists before any content does. You reserve it now, hand out the final URL, and the first upload fills it in. Think of it as provisioning an agent with its reporting address: you can wire the URL into a dashboard, a doc, or another agent's config up front, then let the agent claim it the moment it has something to drop.

Reserving mints a one-time claim token. Whoever holds that token can claim the address with a single upload, which becomes a live page at the reserved URL, inheriting the visibility, mode, and folder you chose at reserve time.

Reserve with the CLI

The CLI is the fastest path. Reserve the address:

sharedrop reserve --title "Q3 Metrics" --agent-name "reporting-bot" --visibility public

The output prints the reserved URL, its status, and a Claim token:

Q3 Metrics
  https://sharedrop.cloud/you/abc123
  Status: reserved
  Agent:  reporting-bot

  Claim token: sdr_example_shown_once_store_now
  Store this token now. It is shown once and cannot be retrieved again.

Capture the token immediately. It is shown exactly once, never appears in sharedrop reservations list, and cannot be retrieved again. Hand it to the agent over a secure channel, the same way you would hand over any credential.

When the agent has something to publish, it claims the address with a single file:

sharedrop upload metrics.html --to abc123

--to accepts the reserved slug or the reservation id. The claim always creates a new page at the reserved URL, so it cannot be combined with --page-id, --folder (the reservation keeps the folder chosen at reserve time), or a folder bundle (single file only). After the claim lands, the agent re-uploads over the now-live page with --page-id as normal, and the URL stays stable.

Manage your reservations with:

sharedrop reservations list                 # slug, status, agent, URL, expiry
sharedrop reservations revoke <id>          # kill an unclaimed reservation

See the CLI guide for every flag.

Reserve with MCP

If your agent connects over MCP, reserve with create_reservation:

Call create_reservation (optionally passing title, intended_agent_name, visibility, mode, expires_at, folder_id). It returns the final url plus a one-time claim_token.
Claim the address by passing that reservation's id as reservation_id to create_upload (instead of page_id), then PUT the bytes and call finalize_upload. The finished upload becomes a live page at the reserved URL.
Subsequent updates use page_id as normal.

Use list_reservations and revoke_reservation to manage them. See Reserved addresses in the MCP setup.

Reserve with the REST API

Over raw REST, reserve with POST /api/v1/reservations. The 201 response includes the serialized reservation (with the final url) plus a sibling claim_token. Claim it by running the streamed upload pipeline with that reservation: pass reservation_id to the sign step, PUT the bytes, then finalize. The finished upload becomes a new page at the reserved URL.

See the Reservations reference for every endpoint, field, and status code.

While it waits

Between reservation and the first upload, the reserved URL is live but has no content yet. What a visitor sees depends on the reservation's visibility:

Public-intended reservations show a "Reserved, awaiting first drop" holding page to anyone who visits. It signals the address is claimed and content is coming.
Private or shared reservations show that holding page to the owner only. Everyone else gets a normal 404, so an unclaimed private address never reveals that it exists.

Holding pages are never indexed by search engines. The moment the address is claimed, the holding page is replaced by the real content at the same URL.

Expiry

Expiry is opt-in. Pass expires_at (CLI --expires) as an ISO 8601 timestamp when you reserve, and an unclaimed reservation lapses after that time. Omit it and the reservation is held until it is claimed or revoked.

A daily sweep expires past-due unclaimed reservations. When a reservation expires it:

frees the slug, so the address can be reserved again,
permanently invalidates the claim token, so a leaked sdr_ credential is worthless after expiry.

Revoke is the manual equivalent: sharedrop reservations revoke <id> (or POST /api/v1/reservations/:id/revoke) flips the status to revoked and kills the claim token immediately. Expired and revoked rows stay in your list for history.

Tier caps

The number of active (unclaimed) reservations you can hold at once depends on your plan:

Plan	Active reservations
Free	2
Pro	25
Team	Unlimited

Going over the cap returns a 402 billing error with an upgrade link, on every surface. Claiming or revoking a reservation frees a slot.