Droplet

Deploy a new Droplet from a single HTML or Markdown file. Auto-creates the slug if not provided. Pass ?draft=true to land in your private workspace instead of publishing. Two-step: this returns a presigned S3 upload URL; PUT the file to that URL, then POST to confirm.

Non-destructively archive a Droplet — sets archivedAt, hides it from default lists, but preserves all content and audit history. Restore with the unarchive endpoint. Idempotent: a second call returns 204 with no body.

Clear archivedAt and return the Droplet to the active lane. Idempotent: a second call returns 204 with no body.

Return the latest-attempt PipelineStage row for each of the droplet's 7 background stages (upload, text-extract, summary, KB ingest, edge sync, CDN invalidation, vector indexing). Stages that have never run are absent. Caller must be able to read the droplet.

Return the full Droplet object by slug. Includes Space context (live member count when internalAccess is SPACE) and the effective audience (computed from access mode + Space policy). 404 to anyone who can't see it (privacy by indistinguishability).

Patch Droplet metadata: name, description, tags, allowEmbedding, commentsEnabled, inlineEditingEnabled, accessMode, password, publicName, spaceSlug. Use the dedicated Set access endpoint to change internalAccess (audience expansions need an explicit confirm). Tags are server-side normalized: trim → lowercase → drop empty → cap at 50 chars each → dedup → cap at 20 total. Only the owner can change accessMode, password, publicName, spaceSlug, and inlineEditingEnabled; editors can change the other metadata.

Irreversible hard-delete (029-freshness FR-028). Gated by the clean-slate rule (caller is sole owner AND zero comments AND zero view events AND no AppAccess grants). On gate failure returns 409 NOT_CLEAN_SLATE with { code, reason, message }. On success: removes the App row (Prisma cascade-deletes versions, comments, share links, access rows, stars, view events), removes the S3 prefix {slug}/, removes the DynamoDB edge record, and triggers a CloudFront invalidation for /{slug}/*. Use Archive for recoverable removal.

Change internalAccess (PRIVATE / SPACE / SPECIFIC / EVERYONE). Audience expansions return 409 CONFIRMATION_REQUIRED until { confirmed: true } is included; reductions are immediate. See POST /api/apps/{slug}/access/preview for the audience diff. The full request body supports people (email grant list) and grants (mixed audience: email + User Group grants); see the route source for the complete schema.

Move a Droplet into / between / out of a Space. Flips internalAccess to SPACE on move-in; resets to PRIVATE on move-out (FR-015). Preserves prior SPECIFIC grants as supplemental rows on move-in (FR-013) so a later move-out can recover them. Owner-only. Returns 409 CONFIRMATION_REQUIRED with the access preview for audience-expanding moves; never for reductions.

Roll back to a previous version. The target version's content is copied to the live path and the CDN cache is invalidated. The previous live version stays in history as a separate row.

Return the full version history for a Droplet — newest first. Each row includes the deployer, the file size, optional notes, the conversion status (for Markdown Droplets), and whether the version is the current published one.

Provision the next published version of a Droplet. Returns a presigned S3 upload URL — PUT the new HTML/Markdown content to that URL, and the version is live as soon as the upload completes. Owner/editor only; baseVersion provides optimistic concurrency.

Create a new Droplet seeded from this one's latest version. The new Droplet starts in PRIVATE mode under the caller's ownership; pass an optional name and newSlug. Returns the new Droplet record. Slug collisions auto-resolve by appending -2, -3, etc.

Mark a Droplet as starred for the calling user. Stars are per-user — they pin the Droplet to the top of the dashboard and surface it in drop list --starred. Idempotent: re-starring returns the original starredAt timestamp.

Remove the caller's star on a Droplet. Idempotent: returns removed: false if there was nothing to remove.

Pin a Droplet to the top of its Space. Only valid for Droplets that belong to a Space. Pinning is per-Droplet (not per-user — every Space member sees the same pinned set). Owner/editor only.

Remove a Droplet's pin within its Space. Owner/editor only. Idempotent.

Promote one of the caller's drafts to a new published version. Squashes any sibling drafts in the workspace (only the chosen draft survives, the rest are discarded). With no draftId, publishes the latest draft. If the Droplet was previously archived, publish clears archivedAt and the response includes wokeFromArchive: true (029-freshness FR-018 wake-on-publish). Owner/editor only.

Take a published Droplet offline. Sets publishedVersion = null (preserves currentVersion so republish can restore the same version). Viewers see an "unavailable" placeholder. Drafts are unaffected. Owner/editor only.

Restore a previously-unpublished Droplet by setting publishedVersion = currentVersion. Idempotent on already-published Droplets. Owner/editor only.

List the calling user's drafts on this Droplet. Drafts are private per-caller — co-editors cannot see them. Returns 404 (not 403) when the caller lacks edit rights (privacy by indistinguishability).

Get metadata for one of the caller's drafts on a Droplet. draftId may be the CUID or the workspace-local short ID (e.g. 1, 2). Returns 404 when not owned by the caller (privacy by indistinguishability).

Discard a single draft from the caller's workspace. Returns 204 on success. 404 when the draft is gone or never existed (the CLI / MCP layer treats 404 as idempotent success).

Discard every draft in the caller's workspace on this Droplet. Always returns 204 (idempotent — re-running on an empty workspace is a no-op).

Set the Droplet's Type slot (App.typeId) by resolving a Type by name. Resolution honors scope (USER | SPACE | GLOBAL) when provided, otherwise falls back to most-specific-wins from the viewer's context (user → space → global). NON-DESTRUCTIVE: existing typeFields are PRESERVED across a Type change, and any sign-off — votes and audit log — survives it. Values the new Type does not declare simply do not render, and are still there if you switch back. A topic-shaped Type seeds its draft status for keys that are absent, so a returning decision keeps the status it left with. To genuinely discard a decision, use droplet.clearType, which is the explicit act and does purge. Owner/editor only.

Clear the Droplet's Type slot — sets App.typeId = null and resets App.typeFields = {}. On a decision this is the un-decision path: the sign-offs and the recorded call go with the Type, reported as purgedSignoff. Idempotent: returns cleared: false when there was nothing to clear. Owner/editor only.

Write a single value into App.typeFields[fieldKey]. The Droplet must have a Type slot set (App.typeId != null); the server validates fieldKey against the Type's schema and coerces / rejects value per the field definition. Per-field errors return 400 TYPE_FIELD_* with { field } extras. Archived Droplets reject writes with 409 APP_ARCHIVED. Owner/editor only.

Remove a single key from App.typeFields. Idempotent: returns cleared: false when the key was already absent. Owner/editor only.

Hand a Droplet to another person. Callable by the current owner or a site admin — the admin path exists because the common case (the owner is on PTO or has left) is exactly when the owner cannot act. The prior owner keeps an EDITOR grant unless keepPriorOwnerAsEditor is false.

Ownership is not an audience change: the recipient must already be able to see the Droplet, or the call returns 409 RECIPIENT_NO_ACCESS. Grant them access first, then transfer. internalAccess, accessMode, Space membership, and every draft workspace are left alone — drafts are keyed per-user and stay with their author.

Transferring to the current owner is a no-op (204). Archived Droplets are rejected.

Move every Droplet a person owns to someone else — the offboarding path. Restricted to the @drop-owner-transfer role; being a site admin is not sufficient.

Deliberately returns a count, never a list: total plus a breakdown by access mode. That is enough to judge whether you named the right person (fourteen is plausible, four hundred is a typo) without displaying titles. Archived Droplets are excluded.

The count is recipient-aware: total is what will actually move, and blocked is what the recipient cannot read (a Space they are not in, a SPECIFIC list they are not on). Transfer never widens an audience, so those stay put.

One call moves at most 50, chosen from the movable set rather than the most recent, so batch slots are never spent on Droplets the recipient cannot read. remaining counts movable leftovers only — it reaches zero, where a raw owned-count would stall forever on blocked rows. Counting stops at 500; past that truncated is set and the numbers are a floor. Re-running is safe: a Droplet already owned by the recipient is a no-op.

Call with dryRun: true first — the UI does. Partial success is the contract: each Droplet goes through the same per-Droplet rules, and anything that could not move comes back in skipped with a code.

Bulk emits ONE notification per party rather than one per Droplet, while still writing a per-Droplet audit row.

Re-run a single pipeline stage on this droplet. Creates a new PipelineStage row at attempt = (prior + 1) and returns the terminal status. Synchronous — the caller waits for the stage to complete. Caller must be droplet owner or sys admin.