drophere.cc

Instant static hosting for AI agents and developers.

drophere.cc lets you upload static files via a 3-step flow and get a live URL back in seconds. It's designed so AI agents (Claude, Cursor, etc.) can publish HTML, images, and other static assets programmatically.

Agent/User                     API                         R2 Storage
    |                           |                              |
    |  1. POST /api/v1/artifact |  (file manifest)             |
    |  ────────────────────────>|                              |
    |  <──── slug + upload URLs |                              |
    |                           |                              |
    |  2. PUT files to upload URLs                             |
    |  ────────────────────────>|  stream to R2 ──────────────>|
    |                           |                              |
    |  3. POST /api/v1/artifact/:slug/finalize                 |
    |  ────────────────────────>|  copy unchanged files ──────>|
    |  <──── live URL           |                              |

Step 1 — Create: Send a file manifest (paths, sizes, content types). Get back a unique slug and upload URLs.

Step 2 — Upload: PUT each file to its upload URL. The API streams the body directly to R2 storage.

Step 3 — Finalize: Tell the API you're done. It activates the artifact and returns a live URL like bold-canvas-a7k2.drophere.cc.

For updates, only changed files need to be re-uploaded (hash-based incremental deploys).

Base URL

https://drophere.cc

All endpoints return JSON. Authenticated endpoints require an Authorization: Bearer <api_key> header.

Agent-readable docs

If you're an agent or script, prefer the Markdown API reference instead of this HTML page:

https://drophere.cc/skill/references/API.md

For a compact machine-readable index first, fetch https://drophere.cc/api/v1/skill/docs. It returns capability groups plus markdownDocsUrl and htmlDocsUrl.

Installation

Claude Code Skill (recommended for AI agents)

# macOS / Linux
curl -fsSL https://drophere.cc/install.sh | bash

# Windows
irm https://drophere.cc/install.ps1 | iex

Then tell your agent: "publish this to drophere.cc"

Direct API usage

No SDK required. All operations are standard HTTP requests with JSON bodies. Use curl, fetch, or any HTTP client.

Quickstart

Publish a single HTML file in three commands. No account required.

1. Create an artifact

curl -X POST https://drophere.cc/api/v1/artifact   -H "Content-Type: application/json"   -d '{
    "files": [
      { "path": "index.html", "size": 45, "contentType": "text/html" }
    ]
  }'

{
  "slug": "bold-canvas-a7k2",
  "versionId": "550e8400-e29b-41d4-a716-446655440000",
  "siteUrl": "https://bold-canvas-a7k2.drophere.cc/",
  "uploads": [
    {
      "path": "index.html",
      "method": "PUT",
      "url": "https://drophere.cc/api/v1/upload/bold-canvas-a7k2/550e84.../index.html",
      "headers": { "Content-Type": "text/html" }
    }
  ],
  "expiresAt": "2026-03-13T10:00:00Z",
  "limits": { "maxFileSize": 104857600, "maxArtifactSize": 262144000 },
  "feedback": "https://drophere.cc/api/v1/feedback",
  "claimToken": "a1b2c3d4...64chars"
}

2. Upload the file

curl -X PUT "UPLOAD_URL_FROM_STEP_1"   -H "Content-Type: text/html"   --data-binary '<h1>Hello from drophere.cc</h1>'

3. Finalize

curl -X POST https://drophere.cc/api/v1/artifact/bold-canvas-a7k2/finalize   -H "Content-Type: application/json"   -d '{
    "versionId": "550e8400-e29b-41d4-a716-446655440000",
    "claimToken": "a1b2c3d4...64chars"
  }'

{
  "slug": "bold-canvas-a7k2",
  "versionId": "550e8400-e29b-41d4-a716-446655440000",
  "siteUrl": "https://bold-canvas-a7k2.drophere.cc/",
  "expiresAt": "2026-03-13T10:00:00Z",
  "feedback": "https://drophere.cc/api/v1/feedback"
}

Your site is now live at bold-canvas-a7k2.drophere.cc. Anonymous uploads expire after 24 hours. Authenticate to make them permanent.

Authentication

drophere.cc uses magic link authentication. Request a verification code via email, exchange it for a permanent API key, then use the API key as a Bearer token for all authenticated requests.

Getting an API key

1. Request a code

curl -X POST https://drophere.cc/api/auth/agent/request-code   -H "Content-Type: application/json"   -d '{ "email": "you@example.com" }'

{
  "success": true,
  "requiresCodeEntry": true,
  "expiresAt": "2026-03-12T10:15:00Z"
}

A code in XXXX-XXXX format is sent to your email. Codes expire after 15 minutes.

Rate Limit 1 request per email per 60 seconds.

2. Verify the code

curl -X POST https://drophere.cc/api/auth/agent/verify-code   -H "Content-Type: application/json"   -d '{ "email": "you@example.com", "code": "ABCD-EFGH" }'

{
  "success": true,
  "email": "you@example.com",
  "apiKey": "a1b2c3d4e5f6...64chars",
  "isNewUser": true
}

The code is single-use and deleted on successful verification. The apiKey is permanent — store it securely.

3. Use the API key

Include the API key as a Bearer token in subsequent requests:

curl https://drophere.cc/api/v1/artifacts   -H "Authorization: Bearer a1b2c3d4e5f6...64chars"

API key storage priority

If you're using the Claude Code skill, the API key is resolved in this order:

1. --api-key flag
2. DROPHERE_API_KEY environment variable
3. Credential file at ~/.drophere/credentials

Rotating your API key

If your key leaks, you can self-serve rotate it. The fastest path is the Rotate key button on drophere.cc/account. To do it programmatically:

curl -X POST https://drophere.cc/api/v1/me/api-key/rotate   -H "Authorization: Bearer <current_key>"

{
  "apiKey": "<new 64-hex key>",
  "message": "API key rotated. All clients using the old key will start returning 401..."
}

The endpoint atomically replaces the key, fires a confirmation email to the account address (best-effort), and returns the new key in the response. The old key starts returning 401 immediately on every authenticated endpoint and on the MCP surfaces (/mcp, /mcp/<apiKey>).

Rate-limited to 5 rotations/hour/user. Not exposed via MCP — agents can't rotate their own credentials and lock you out.

Recovery if an attacker rotated first: re-run the magic-link flow (request-code → verify-code). The verify endpoint returns whatever key is currently in the database; rotate again from /account with that key. The magic-link channel is gated on email control, so the attacker can't follow.

Billing

Free Token includes API and MCP access, unlimited 24-hour artifacts, and 10 persistent artifacts. Unlimited unlocks unlimited persistent artifacts. Secure unlocks access control, password protection, collaboration, service variables, and custom domains.

Plans

No Auth

{
  "plans": [
    { "id": "unlimited", "price": "$4.99/month" },
    { "id": "secure", "price": "$9.99/month" }
  ]
}

Status

{
  "plan": "free_token",
  "usage": { "persistentArtifacts": 3, "persistentArtifactLimit": 10 },
  "features": { "apiAndMcp": true, "secureAccessControls": false },
  "upgradeOptions": [{ "plan": "unlimited", "checkoutEndpoint": "/api/v1/billing/checkout" }]
}

Checkout

curl -X POST https://drophere.cc/api/v1/billing/checkout   -H "Content-Type: application/json"   -H "Authorization: Bearer YOUR_API_KEY"   -d '{ "plan": "secure" }'

Creates a Stripe Checkout Session for unlimited or secure. Agents should call this only after explicit user confirmation.

Portal

Creates a Stripe billing portal session for the authenticated account.

Paywall errors

Paid-feature gates return HTTP 402 with a structured PAYWALL response. Agents should present agentMessage, ask the human whether to upgrade, and create checkout only if the human confirms.

{
  "error": "PAYWALL",
  "code": "PLAN_REQUIRED",
  "requiredPlan": "secure",
  "agentMessage": "The collaboration feature requires the secure plan. Upgrade to secure ($9.99/month) at https://drophere.cc/account?upgrade=secure.",
  "upgrade": { "checkoutEndpoint": "/api/v1/billing/checkout" },
  "retry": { "action": "collaboration" }
}

Create Artifact

Start a new artifact upload. Send a file manifest and receive upload URLs.

Auth Optional Anonymous uploads (no auth) get a 24-hour TTL and a claimToken.

Request body

curl -X POST https://drophere.cc/api/v1/artifact   -H "Content-Type: application/json"   -H "Authorization: Bearer YOUR_API_KEY"   -d '{
    "files": [
      { "path": "index.html", "size": 2048, "contentType": "text/html", "hash": "sha256:abc123..." },
      { "path": "style.css", "size": 512, "contentType": "text/css", "hash": "sha256:def456..." }
    ],
    "viewer": {
      "title": "My Project",
      "description": "A demo page"
    }
  }'

{
  "slug": "bold-canvas-a7k2",
  "versionId": "550e8400-e29b-41d4-a716-446655440000",
  "siteUrl": "https://bold-canvas-a7k2.drophere.cc/",
  "expiresAt": null,
  "uploads": [
    {
      "path": "index.html",
      "method": "PUT",
      "url": "https://drophere.cc/api/v1/upload/bold-canvas-a7k2/550e84.../index.html",
      "headers": { "Content-Type": "text/html" }
    },
    {
      "path": "style.css",
      "method": "PUT",
      "url": "https://drophere.cc/api/v1/upload/bold-canvas-a7k2/550e84.../style.css",
      "headers": { "Content-Type": "text/css" }
    }
  ],
  "limits": {
    "maxFileSize": 1073741824,
    "maxArtifactSize": 5368709120
  },
  "feedback": "https://drophere.cc/api/v1/feedback"
}

• uploads — upload URLs (10-minute window). Upload each file with PUT.
• claimToken — only returned for anonymous uploads. Store it to update/finalize later.
• expiresAt — null for authenticated uploads without a TTL.
• limits — current size limits so clients can pre-validate.
• feedback — URL for submitting feedback about the service.

Rate Limit Authenticated: 60 creates/hour. Anonymous: 5 creates/hour per IP.

Errors

Upload Files

Upload each file to the URL returned in the uploads array. The API streams the body to R2 storage.

curl -X PUT "UPLOAD_URL_FROM_CREATE"   -H "Content-Type: text/html"   --data-binary @index.html

{
  "ok": true,
  "path": "index.html"
}

• Set the Content-Type header as specified in the upload entry's headers
• Upload URLs expire after 10 minutes
• If Content-Length is present, it must not exceed the declared file size in the manifest
• Upload all files before calling finalize

Finalize Artifact

Mark an upload as complete. This activates the artifact and makes it accessible at its URL. For incremental deploys, unchanged files are copied server-side during finalization.

Authenticated Requires Bearer token or claimToken in body for anonymous artifacts.

Request body

curl -X POST https://drophere.cc/api/v1/artifact/bold-canvas-a7k2/finalize   -H "Content-Type: application/json"   -H "Authorization: Bearer YOUR_API_KEY"   -d '{ "versionId": "550e8400-e29b-41d4-a716-446655440000" }'

{
  "slug": "bold-canvas-a7k2",
  "versionId": "550e8400-e29b-41d4-a716-446655440000",
  "siteUrl": "https://bold-canvas-a7k2.drophere.cc/",
  "expiresAt": null,
  "feedback": "https://drophere.cc/api/v1/feedback"
}

Errors

Update Artifact (Incremental Deploy)

Update an existing artifact. Files with matching SHA-256 hashes are skipped — no re-upload needed. Only changed or new files get upload URLs.

Authenticated Requires Bearer token or claimToken in body.

Request body

curl -X PUT https://drophere.cc/api/v1/artifact/bold-canvas-a7k2   -H "Content-Type: application/json"   -H "Authorization: Bearer YOUR_API_KEY"   -d '{
    "files": [
      { "path": "index.html", "size": 3072, "contentType": "text/html", "hash": "sha256:new123..." },
      { "path": "style.css", "size": 512, "contentType": "text/css", "hash": "sha256:def456..." }
    ]
  }'

{
  "slug": "bold-canvas-a7k2",
  "versionId": "660e8400-e29b-41d4-a716-446655440001",
  "siteUrl": "https://bold-canvas-a7k2.drophere.cc/",
  "uploads": [
    {
      "path": "index.html",
      "method": "PUT",
      "url": "https://drophere.cc/api/v1/upload/bold-canvas-a7k2/660e84.../index.html",
      "headers": { "Content-Type": "text/html" }
    }
  ],
  "skipped": [
    { "path": "style.css", "hash": "sha256:def456..." }
  ],
  "limits": { "maxFileSize": 1073741824, "maxArtifactSize": 5368709120 },
  "feedback": "https://drophere.cc/api/v1/feedback"
}

• Only files in uploads need to be uploaded
• Files in skipped matched by hash and will be copied server-side during finalize
• After uploading changed files, finalize the new version

Errors

Claim Artifact

Transfer an anonymous artifact to your authenticated account. This removes the 24-hour expiry and the claim token, making the artifact permanent.

Authenticated

curl -X POST https://drophere.cc/api/v1/artifact/bold-canvas-a7k2/claim   -H "Content-Type: application/json"   -H "Authorization: Bearer YOUR_API_KEY"   -d '{ "claimToken": "a1b2c3d4...64chars" }'

{
  "slug": "bold-canvas-a7k2",
  "siteUrl": "https://bold-canvas-a7k2.drophere.cc/",
  "message": "Artifact claimed successfully"
}

Claiming is idempotent — calling it again on an already-claimed artifact is a no-op.

Get Artifact

Retrieve details for a specific artifact, including its current files.

Authenticated Must own the artifact.

curl https://drophere.cc/api/v1/artifact/bold-canvas-a7k2   -H "Authorization: Bearer YOUR_API_KEY"

{
  "slug": "bold-canvas-a7k2",
  "siteUrl": "https://bold-canvas-a7k2.drophere.cc/",
  "status": "active",
  "currentVersionId": "550e8400-e29b-41d4-a716-446655440000",
  "pendingVersionId": null,
  "collaboration": {
    "enabled": false,
    "commentPolicy": "authenticated",
    "commentDomain": null,
    "commentAllowedEmails": null
  },
  "viewerMetadata": null,
  "expiresAt": null,
  "createdAt": "2026-03-12T10:00:00Z",
  "updatedAt": "2026-03-12T10:01:00Z",
  "files": [
    {
      "path": "index.html",
      "size": 2048,
      "contentType": "text/html",
      "hash": "sha256:abc123..."
    }
  ]
}

List Artifacts

List all artifacts owned by the authenticated user.

Authenticated

curl https://drophere.cc/api/v1/artifacts   -H "Authorization: Bearer YOUR_API_KEY"

{
  "artifacts": [
    {
      "slug": "bold-canvas-a7k2",
      "siteUrl": "https://bold-canvas-a7k2.drophere.cc/",
      "status": "active",
      "currentVersionId": "550e8400-...",
      "pendingVersionId": null,
      "collaboration": {
        "enabled": false,
        "commentPolicy": "authenticated",
        "commentDomain": null,
        "commentAllowedEmails": null
      },
      "viewerMetadata": { "title": "My Project" },
      "title": "My Project",
      "expiresAt": null,
      "updatedAt": "2026-03-12T10:01:00Z"
    }
  ]
}

viewerMetadata is the full JSON blob set via the metadata endpoint (null when unset). title is a convenience extraction of viewerMetadata.title (trimmed; null when missing or empty) so list consumers don't have to dig. collaboration is included so owners and agents can discover whether the comment layer is enabled before calling the comment APIs.

Update Viewer Metadata

Update the title, description, or OG image for auto-viewer rendering. This metadata has no effect if the artifact contains an index.html or is a single HTML file — in both cases the HTML is served directly and its own <head> tags are authoritative.

Authenticated

curl -X PATCH https://drophere.cc/api/v1/artifact/bold-canvas-a7k2/metadata   -H "Content-Type: application/json"   -H "Authorization: Bearer YOUR_API_KEY"   -d '{
    "viewerMetadata": {
      "title": "Project Gallery",
      "description": "Screenshots from v2 launch",
      "ogImagePath": "hero.png"
    }
  }'

{
  "slug": "bold-canvas-a7k2",
  "viewerMetadata": {
    "title": "Project Gallery",
    "description": "Screenshots from v2 launch",
    "ogImagePath": "hero.png"
  },
  "note": "Viewer metadata updated successfully."
}

Delete Artifact

Permanently delete an artifact and all its versions. Files are removed from R2 storage in the background.

Authenticated Must own the artifact.

curl -X DELETE https://drophere.cc/api/v1/artifact/bold-canvas-a7k2   -H "Authorization: Bearer YOUR_API_KEY"

{
  "slug": "bold-canvas-a7k2",
  "message": "Artifact deleted"
}

Password Protection

Protect an artifact with a password. Simpler alternative to email-based access control. Visitors see a password form; correct entry sets a 30-day session cookie.

Set or remove password

Authenticated Must own the artifact.

Request body

# Set a password
curl -X PATCH https://drophere.cc/api/v1/artifact/bold-canvas-a7k2/password \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "password": "my-secret-123" }'

{
  "slug": "bold-canvas-a7k2",
  "passwordProtected": true
}

# Remove password
curl -X PATCH https://drophere.cc/api/v1/artifact/bold-canvas-a7k2/password \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "password": null }'

Password protection is checked before email-allowlist access control. Both can be active simultaneously.

Collaboration

Enable an isolated reader-style highlight and comment layer on HTML artifacts. Artifact visibility, passwords, and email gates still control who can view the artifact; the collaboration comment policy controls who can write comments.

Enable or disable collaboration

Authenticated Must own the artifact.

curl -X PATCH https://drophere.cc/api/v1/artifact/bold-canvas-a7k2/collaboration \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

{
  "slug": "bold-canvas-a7k2",
  "collaborationEnabled": true,
  "commentPolicy": "authenticated",
  "commentDomain": null,
  "commentAllowedEmails": null
}

Set view and comment permissions atomically

Authenticated Must own the artifact. This endpoint validates view access and comment settings before writing, updates both together, and returns the persisted readback.

curl -X PATCH https://drophere.cc/api/v1/artifact/bold-canvas-a7k2/permissions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "access": { "visibility": "public" },
    "collaboration": {
      "enabled": true,
      "commentPolicy": "specific_accounts",
      "commentAllowedEmails": ["alice@example.com"]
    }
  }'

{
  "slug": "bold-canvas-a7k2",
  "access": {
    "visibility": "public",
    "allowedEmails": null,
    "allowedDomains": null
  },
  "collaboration": {
    "enabled": true,
    "commentPolicy": "specific_accounts",
    "commentDomain": null,
    "commentAllowedEmails": ["alice@example.com"]
  }
}

Read comments

Authenticated Owner Bearer token. Viewer UI uses the isolated Drophere frame after artifact access is granted. Query parameter status may be open, resolved, or all. settings.viewer.canComment and each thread's capabilities.canReply reflect the current viewer's comment policy eligibility.

curl https://drophere.cc/api/v1/artifact/bold-canvas-a7k2/comments?status=open \
  -H "Authorization: Bearer YOUR_API_KEY"

Comment actions

curl -X PATCH https://drophere.cc/api/v1/artifact/bold-canvas-a7k2/comments/THREAD_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "resolved" }'

Viewer commenting runs through an isolated Drophere-controlled frame using a short-lived HttpOnly access cookie. The frame can create threads, reply, paste image attachments, and delete the viewer's own messages when the artifact gates and comment policy allow it. Artifact JavaScript does not receive comment bodies or private author metadata. Owner and agent APIs receive private author metadata; viewer responses redact email and user IDs. Attachments are validated and served through artifact gates rather than direct public bucket URLs.

Agents should prefer the MCP tools for parity: drophere_set_collaboration, drophere_list_comments, drophere_add_comment, drophere_update_comment, and drophere_delete_comment.

GET /api/v1/artifact/:slug/annotations and PATCH /api/v1/artifact/:slug/annotations/:id remain as temporary owner-only compatibility aliases backed by comment threads.

Duplicate Artifact

Create a server-side copy of an artifact with a new slug. Files are copied within R2 — no re-upload needed.

Authenticated Must own the source artifact.

curl -X POST https://drophere.cc/api/v1/artifact/bold-canvas-a7k2/duplicate \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "slug": "calm-reef-x9z1",
  "sourceSlug": "bold-canvas-a7k2",
  "versionId": "550e8400-e29b-41d4-a716-446655440000",
  "siteUrl": "https://calm-reef-x9z1.drophere.cc/",
  "files": 12
}

The duplicate does NOT copy: password, access control settings, TTL/expiry, domain links, or claim token. The new artifact starts as public with no expiry.

Rate Limit Same as artifact creation (60/hour authenticated).

Refresh Upload URLs

Re-issue upload URLs for a pending version when the original 10-minute window expires. Only returns URLs for files not yet uploaded.

Auth Optional Authenticated via Bearer token, or anonymous via claimToken in body.

curl -X POST https://drophere.cc/api/v1/artifact/bold-canvas-a7k2/uploads/refresh \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "slug": "bold-canvas-a7k2",
  "versionId": "550e8400-e29b-41d4-a716-446655440000",
  "uploads": [
    {
      "path": "app.js",
      "method": "PUT",
      "url": "https://drophere.cc/api/v1/upload/...",
      "headers": { "Content-Type": "application/javascript" }
    }
  ],
  "alreadyUploaded": ["index.html", "style.css"],
  "expiresIn": 600
}

• Only works when a pending (unfinalized) version exists
• Resets the 10-minute upload window
• Files already in R2 are listed in alreadyUploaded and skipped

Access Control

Restrict who can view an artifact by email address or email domain. By default, all artifacts are public.

Set Visibility

Authenticated Must own the artifact.

Request body

curl -X PATCH https://drophere.cc/api/v1/artifact/bold-canvas-a7k2/access   -H "Content-Type: application/json"   -H "Authorization: Bearer YOUR_API_KEY"   -d '{
    "visibility": "restricted",
    "allowedEmails": ["alice@acme.com", "bob@acme.com"],
    "allowedDomains": ["acme.com"]
  }'

{
  "slug": "bold-canvas-a7k2",
  "visibility": "restricted",
  "allowedEmails": ["alice@acme.com", "bob@acme.com"],
  "allowedDomains": ["acme.com"]
}

To make public again, set visibility to "public" — this clears all allowlists.

When visibility is "restricted", at least one email or domain must be provided.

Errors

Get Access Control

Authenticated Must own the artifact.

curl https://drophere.cc/api/v1/artifact/bold-canvas-a7k2/access   -H "Authorization: Bearer YOUR_API_KEY"

{
  "slug": "bold-canvas-a7k2",
  "visibility": "restricted",
  "allowedEmails": ["alice@acme.com"],
  "allowedDomains": ["acme.com"]
}

Visitor Authentication

Visitors to restricted artifacts verify their email via a one-time code. After verification, a session cookie (dh_visitor) is set on .drophere.cc for 30 days.

Request visitor code

No Auth

curl -X POST https://drophere.cc/api/v1/visitor/request-code   -H "Content-Type: application/json"   -d '{ "email": "alice@acme.com", "slug": "bold-canvas-a7k2" }'

{
  "success": true,
  "expiresIn": 900
}

Verify visitor code

curl -X POST https://drophere.cc/api/v1/visitor/verify-code   -H "Content-Type: application/json"   -d '{ "email": "alice@acme.com", "code": "ABCD-EFGH", "slug": "bold-canvas-a7k2" }'

{
  "success": true,
  "email": "alice@acme.com"
}

Sets a dh_visitor cookie (30-day TTL, HttpOnly, Secure, SameSite=None).

URL Structure

Every artifact gets a unique subdomain URL. You can also serve artifacts via handles and custom domains.

Handles

Handles give you a custom subdomain: yourname.drophere.cc. Combine with links to map paths to different artifacts.

Claim handle

Authenticated

curl -X POST https://drophere.cc/api/v1/handle   -H "Content-Type: application/json"   -H "Authorization: Bearer YOUR_API_KEY"   -d '{ "handle": "alice" }'

{
  "handle": "alice",
  "hostname": "alice.drophere.cc",
  "namespace_id": "user-uuid"
}

Validation: 2-30 chars, lowercase alphanumeric + hyphens, no leading/trailing hyphens.

Reserved handles: admin, api, www, help, blog, docs, app, dashboard, settings, account, login, signup, auth, status, support.

Errors

Get handle

Authenticated

curl https://drophere.cc/api/v1/handle   -H "Authorization: Bearer YOUR_API_KEY"

{
  "handle": "alice",
  "hostname": "alice.drophere.cc",
  "namespace_id": "user-uuid",
  "links": [
    { "location": "", "slug": "bold-canvas-a7k2" },
    { "location": "blog", "slug": "quiet-river-b3m1" }
  ]
}

Change handle

Authenticated

curl -X PATCH https://drophere.cc/api/v1/handle   -H "Content-Type: application/json"   -H "Authorization: Bearer YOUR_API_KEY"   -d '{ "handle": "new-name" }'

{
  "handle": "new-name",
  "hostname": "new-name.drophere.cc"
}

Release handle

Authenticated

Deletes the handle, its KV entry, and all associated links.

curl -X DELETE https://drophere.cc/api/v1/handle   -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true
}

Custom Domains

Serve artifacts from your own domain. Register the domain, add a DNS record, then create links to route paths to artifacts.

Add domain

Authenticated

curl -X POST https://drophere.cc/api/v1/domains   -H "Content-Type: application/json"   -H "Authorization: Bearer YOUR_API_KEY"   -d '{ "domain": "docs.example.com" }'

{
  "domain": "docs.example.com",
  "status": "pending",
  "dns_instructions": {
    "type": "CNAME",
    "name": "docs.example.com",
    "value": "fallback.drophere.cc",
    "note": "Add a CNAME record pointing docs.example.com to fallback.drophere.cc. If this is an apex domain, use an ALIAS record instead."
  }
}

List domains

Authenticated

curl https://drophere.cc/api/v1/domains   -H "Authorization: Bearer YOUR_API_KEY"

{
  "domains": [
    {
      "domain": "docs.example.com",
      "status": "active",
      "ssl_status": "active",
      "created_at": "2026-03-11T10:00:00Z",
      "links": [
        { "location": "", "slug": "bold-canvas-a7k2" }
      ]
    }
  ]
}

Get domain

Authenticated

Delete domain

Authenticated

Removes the domain and all its associated links. KV entries are cleaned up.

curl -X DELETE https://drophere.cc/api/v1/domains/docs.example.com   -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true
}

Links

Links route URL paths on your handle or custom domain to specific artifacts. For example, alice.drophere.cc/blog can point to a different artifact than alice.drophere.cc/portfolio.

Create link

Authenticated

curl -X POST https://drophere.cc/api/v1/links   -H "Content-Type: application/json"   -H "Authorization: Bearer YOUR_API_KEY"   -d '{ "location": "blog", "slug": "quiet-river-b3m1" }'

{
  "namespace": "alice",
  "location": "blog",
  "slug": "quiet-river-b3m1"
}

Creating a link with the same namespace + location upserts (updates the existing link).

List links

Authenticated

curl https://drophere.cc/api/v1/links   -H "Authorization: Bearer YOUR_API_KEY"

{
  "links": [
    {
      "location": "blog",
      "slug": "quiet-river-b3m1",
      "namespace": "alice",
      "namespaceType": "handle"
    }
  ]
}

Get link

Authenticated Use __root__ for the root location.

Update link

Authenticated

curl -X PATCH https://drophere.cc/api/v1/links/blog   -H "Content-Type: application/json"   -H "Authorization: Bearer YOUR_API_KEY"   -d '{ "slug": "new-blog-slug" }'

{
  "success": true
}

Delete link

Authenticated Optional query param ?domain=example.com for domain-scoped links.

curl -X DELETE https://drophere.cc/api/v1/links/blog   -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true
}

Key-Value Store

Per-artifact key-value storage, accessible from the artifact's own origin. No authentication required — designed for public read/write from hosted apps (e.g., game leaderboards, user preferences, shared state).

All store endpoints are served from the artifact's subdomain:

https://{slug}.drophere.cc/_api/store/

Also works via handles and custom domains.

Key validation

Keys must match: ^[a-zA-Z0-9._-:/]{1,480}$

Valid: score, game.level-1_data, leaderboard/level:1
Invalid: empty string, spaces, ../etc/passwd, unicode, keys > 480 chars

CORS

All store responses include CORS headers. OPTIONS requests return 204 with preflight support.

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, x-rate-limit-bypass

Get Value

No Auth Rate Limit 300 reads/min per IP per artifact.

curl https://bold-canvas-a7k2.drophere.cc/_api/store/leaderboard

{
  "value": [{ "name": "Alice", "score": 100 }],
  "metadata": { "updatedAt": "2026-03-13T10:00:00Z" }
}

Errors

Put Value

No Auth Rate Limit 30 writes/min per IP per artifact.

curl -X PUT https://bold-canvas-a7k2.drophere.cc/_api/store/leaderboard   -H "Content-Type: application/json"   -d '[{ "name": "Alice", "score": 100 }]'

Body must be valid JSON, max 100 KB.

{
  "ok": true,
  "key": "leaderboard"
}

Errors

Delete Value

No Auth Rate Limit 30 writes/min per IP per artifact.

curl -X DELETE https://bold-canvas-a7k2.drophere.cc/_api/store/leaderboard

{
  "ok": true
}

List Keys

No Auth Rate Limit 30 requests/min (write tier).

Optional query parameter: ?cursor=... for pagination.

curl https://bold-canvas-a7k2.drophere.cc/_api/store

{
  "keys": [
    {
      "name": "leaderboard",
      "metadata": { "updatedAt": "2026-03-13T10:00:00Z" }
    }
  ],
  "cursor": null
}

Returns up to 1000 keys per page. If cursor is not null, pass it as ?cursor=... for the next page.

Service Variables

Encrypted server-side storage for API keys and secrets. Used by proxy routes to inject auth headers into upstream API calls. Values are encrypted at rest (AES-256-GCM) and never returned via the API.

• Max 50 variables per account
• Max 4 KB per value
• Names: alphanumeric + underscores, 1-64 chars (/^[A-Za-z0-9_]{1,64}$/)
• Optional allowedUpstreams restricts which domains can receive the variable

Create or update variable

Authenticated

curl -X PUT https://drophere.cc/api/v1/me/variables/OPENAI_KEY \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "sk-abc123...",
    "allowedUpstreams": ["api.openai.com"]
  }'

{
  "name": "OPENAI_KEY",
  "allowedUpstreams": ["api.openai.com"],
  "message": "Variable created"
}

List variables

Authenticated

curl https://drophere.cc/api/v1/me/variables \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "variables": [
    {
      "name": "OPENAI_KEY",
      "allowedUpstreams": ["api.openai.com"],
      "createdAt": "2026-03-12T10:00:00Z",
      "updatedAt": "2026-03-12T10:00:00Z"
    }
  ]
}

Values are never included in the response. Only names and metadata are returned.

Delete variable

Authenticated

curl -X DELETE https://drophere.cc/api/v1/me/variables/OPENAI_KEY \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "name": "OPENAI_KEY",
  "message": "Variable deleted"
}

Proxy Routes

Let your static sites call authenticated APIs without exposing credentials in client code. Deploy a .drophere/proxy.json manifest with your artifact, and the edge worker forwards requests from /_proxy/* paths to upstream APIs with injected auth headers.

Browser JS                    Edge Worker                   Upstream API
    |                              |                              |
    |  fetch(/_proxy/api/chat)     |                              |
    |  ───────────────────────────>|                              |
    |                              |  Load .drophere/proxy.json   |
    |                              |  Decrypt ${OPENAI_KEY}       |
    |                              |                              |
    |                              |  fetch(upstream, {headers})  |
    |                              |  ───────────────────────────>|
    |                              |  <── response (streamed)     |
    |  <── proxied response        |                              |

Manifest format

Include .drophere/proxy.json in your artifact's files:

{
  "routes": {
    "/api/chat": {
      "upstream": "https://api.openai.com/v1/chat/completions",
      "headers": { "Authorization": "Bearer ${OPENAI_KEY}" }
    },
    "/api/db/*": {
      "upstream": "https://db.example.com/api",
      "headers": { "apikey": "${DB_KEY}" },
      "rateLimit": "20/hour/ip"
    }
  }
}

Route matching

• Exact match: /api/chat matches only /_proxy/api/chat
• Wildcard: /api/db/* matches /_proxy/api/db/anything — remaining path appended to upstream URL
• Max 20 routes per manifest

Variable resolution

${VAR_NAME} references in headers are resolved from your service variables at request time. Variables are decrypted server-side — client code never sees credentials.

Security

• upstream must use HTTPS — HTTP is rejected
• Set-Cookie headers from upstream are stripped
• Only Content-Type and Accept headers forwarded from client
• allowedUpstreams on variables enforced — variable rejected if upstream domain doesn't match
• Max request body: 10 MB

Rate limiting

Default: 100 requests/hour/IP per route. Override per route with "rateLimit": "20/hour/ip". Format: {count}/{second|minute|hour}/ip.

Client usage

From your deployed static site's JavaScript:

// Call an authenticated API without exposing your key
const res = await fetch('/_proxy/api/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: 'gpt-4',
    messages: [{ role: 'user', content: 'Hello' }]
  })
});
const data = await res.json();

MCP Server

drophere.cc speaks the Model Context Protocol natively. Point any MCP-capable client (Claude Desktop, Cursor, custom agents) at the server and it can publish, update, claim, password-protect, route, and delete artifacts — plus read and write the KV store and service variables — without you wiring up REST calls.

The MCP surface is a thin wrapper over the same authenticated REST API documented above. Anything an agent can do over REST it can do over MCP, with one deliberate exception: API-key rotation is not exposed, so a compromised agent can't lock you out of your own account.

Connect

Two equivalent transport forms, depending on whether your client can send custom headers:

Path-token form

API key embedded in the URL path. Useful for clients that don't expose a way to set Authorization headers (some agent UIs, simple HTTP MCP bridges). Treat the URL itself as the secret — anyone with it can act as you.

Bearer-header form

Standard MCP endpoint. Authenticate with Authorization: Bearer <apiKey>. Preferred form when your client supports it (key isn't logged in URLs / proxies / browser history).

Authenticated Same 64-hex API key you get from magic-link verification. Missing, malformed (not 64 hex chars), or revoked keys return 401.

Example: Claude Desktop config

{
  "mcpServers": {
    "drophere": {
      "url": "https://drophere.cc/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

CORS

OPTIONS preflight is open (*). Allowed methods: GET, POST, OPTIONS. Allowed headers: Authorization, Content-Type, mcp-session-id. Preflight is cached 24 hours.

Tools

The server registers the tools below. Parameter schemas mirror the corresponding REST endpoints — each tool links to the relevant section for full request/response details.

Search & fetch

• drophere_search — search your own artifacts by slug, title, or source
• drophere_fetch — fetch a hosted file's content by URL (useful for letting an agent read back what it just published)

Artifacts — read

• drophere_list_artifacts — see List Artifacts
• drophere_get_artifact — see Get Artifact
• drophere_get_artifact_access — see Get Access

Artifacts — write

• drophere_create_artifact — see Create
• drophere_update_artifact — see Update (Incremental)
• drophere_finalize_artifact — see Finalize
• drophere_claim_artifact — see Claim
• drophere_duplicate_artifact — see Duplicate
• drophere_refresh_uploads — see Refresh Upload URLs
• drophere_update_artifact_metadata — see Metadata
• drophere_set_artifact_access — see Set Visibility
• drophere_set_artifact_password / drophere_unset_artifact_password — see Password Protection

Collaboration

• drophere_set_collaboration — see Collaboration
• drophere_list_comments, drophere_add_comment, drophere_update_comment, drophere_delete_comment — see Collaboration

Upload

• drophere_upload_file — wraps the file upload proxy. The tool takes a slug + version + path + base64 content and writes to R2 in one call (no separate signed-URL step).

Handles & links

• drophere_set_handle, drophere_get_handle, drophere_delete_handle — see Handles
• drophere_set_link, drophere_get_link, drophere_list_links, drophere_delete_link — see Links

Service variables

• drophere_set_variable, drophere_list_variables, drophere_delete_variable — see Service Variables

Key-Value store

• drophere_kv_get, drophere_kv_set, drophere_kv_list, drophere_kv_delete — see Key-Value Store

Delete

• drophere_delete_artifact — see Delete Artifact

Rate Limits

MCP shares the same per-user buckets as the underlying REST endpoints — the wrapper doesn't add or subtract budget. In practice this means: 60 creates/hour, 5 key rotations/hour (REST-only), 30 writes/min and 300 reads/min on the KV store, 10 feedback submissions/hour. See Limits for the full table.

On top of those, the MCP transport itself applies a lightweight per-key throttle to absorb runaway agent loops — sustained traffic above a few requests/second will see 429. Back off and retry.

Slack

The @drophere Slack bot turns any HTML file you drop into Slack into a live URL. Mention the bot with an attachment, DM it, or use the Host on drophere message shortcut — it uploads the file, hosts it, and replies in-thread with the URL.

Slack-hosted artifacts are anonymous — they aren't linked to your drophere.cc account, even if you have one. By default they're restricted to your workspace's email domains (configured server-side); pass --public to drop the restriction.

Install

The bot is currently invite-only while we tune the workspace flow. Reach out via feedback with your Slack workspace name to request access.

Once installed, the bot exposes:

• The @drophere mention in any channel it's invited to
• Direct messages (DMs and group DMs)
• A message shortcut labelled Host on drophere

Usage

1. @-mention in a channel

Attach an HTML file and mention the bot:

@drophere here you go
[attach: report.html]

The bot replies in-thread:

Dropped! Your file is live:
https://bold-canvas-a7k2.drophere.cc/

File: report.html

To make the artifact public (no domain restriction), add --public anywhere in the message:

@drophere ship this --public
[attach: landing.html]

2. DM the bot

Send an HTML attachment directly to @drophere in a DM or group DM. Same response. The --public flag works here too.

3. Message shortcut

On any Slack message that already has an HTML attachment, open the message actions menu (…) and pick Host on drophere. Useful for re-hosting a file a teammate posted earlier without needing to mention the bot.

The shortcut always hosts with the default workspace-domain restriction — there's no --public form. If you need a public URL, re-share with an @-mention instead.

Webhook Endpoints

For completeness — these are the URLs Slack itself calls into drophere.cc. They aren't part of the public API; you don't call them directly.

Slack Events API target. Handles url_verification (during app setup), app_mention, and DM/group-DM message events. Requests are authenticated via X-Slack-Signature (HMAC-SHA256 of the timestamp + raw body, keyed by the Slack signing secret) and deduplicated on X-Slack-Retry-Num.

Slack Interactivity target. Handles the drophere_host message shortcut (callback_id). Same signature scheme as /api/slack/events.

Content Serving

Artifacts are served at https://{slug}.drophere.cc/. The edge worker handles routing, access control, and file serving from R2 storage.

File serving priority

For a given request path against an artifact:

1. Password gate — if password-protected, verify session cookie or show password form
2. Access control — if restricted, verify email/session
3. Proxy intercept — /_proxy/* requests forwarded via proxy routes
4. Root path with index.html in manifest — serve the HTML file
5. Root path with a single HTML file (not named index.html) — serve it directly as the entry point
6. Exact file match in the version manifest
7. Directory index: try {path}/index.html
8. SPA fallback — if spaMode enabled, serve index.html for unmatched paths
9. No match — 404

SPA Routing

When spaMode: true is set in viewer metadata, unmatched paths serve index.html instead of returning 404. This enables client-side routing for React, Vue, SvelteKit, and other SPA frameworks.

# Enable SPA mode
curl -X PATCH https://drophere.cc/api/v1/artifact/bold-canvas-a7k2/metadata \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "viewerMetadata": { "spaMode": true } }'

• Static assets (JS, CSS, images) are still served normally — they match before the SPA fallback
• /_api/* and /_proxy/* paths are never intercepted
• Requires an index.html in the artifact's root

Response headers

Files are served with:

• Content-Type — from R2 metadata or file extension detection
• Cache-Control: public, max-age=3600, s-maxage=86400 for public artifacts
• Cache-Control: private, no-store for restricted artifacts
• ETag — from R2 object metadata

Visit Counter

Drop-in counter for any artifact. The script reads four metrics from a same-origin endpoint and writes the raw number into every matching element. No styling, no formatting — wrap and style however you like.

Usage

<p><span data-drophere-visits="total">—</span> visits</p>
<p><span data-drophere-visits="today">—</span> today</p>
<script src="https://drophere.cc/c/visits.js" defer></script>

The data-drophere-visits attribute selects which metric to inject. Any element type works — span, div, strong, etc. Multiple elements with the same metric are all filled from a single fetch.

Endpoint

Same-origin JSON endpoint. Resolves the artifact from the Host header. Inherits the artifact's password and access-control gates — restricted artifacts return 401/403 to non-allowed visitors.

Response

{
  "total":    12483,
  "today":    142,
  "last7d":   1109,
  "unique7d": 734
}

Cached at the edge for 30–60 seconds.

Programmatic access

Owner-only equivalent of the same-origin endpoint, for fetching counts from outside the artifact (e.g. a dashboard). Returns the same JSON shape.

curl -H "Authorization: Bearer $DROPHERE_API_KEY" \
  https://drophere.cc/api/v1/artifact/bold-canvas-a7k2/visits

Auto-Viewers

When an artifact has no index.html, drophere.cc renders a viewer based on the content type. This gives rich previews for images, PDFs, videos, and more.

Auto-viewers include og:title, og:description, and og:image meta tags when viewerMetadata is set.

Download as Markdown

Off by default. Agents can enable Download-as-Markdown per artifact at creation time (or later via a metadata update). When enabled, drophere runs the artifact's HTML through a converter and returns a .md file suitable for RAG pipelines, agent ingestion, and offline reading. This is best-effort.

Scope

Works on: user-uploaded HTML artifacts (served at {slug}.drophere.cc or a custom domain) where the agent has opted in (see below), including direct file paths and auto-viewer wrappers.

Does not apply to: the drophere marketing site (drophere.cc), developer docs (docs.drophere.cc), skill/install endpoints, API responses, the password gate, or non-HTML artifacts (images, PDFs, videos, JSON). Those are either not user content or not HTML, so the button is not injected and ?format=md does not apply.

Enabling the feature

The feature is gated by the viewer.markdownDownload flag in the artifact's viewer metadata. When it is true, the ?format=md endpoint and the floating .md button both become available. When it is missing or false, ?format=md returns 404 and no button is injected.

At creation time — pass viewer.markdownDownload: true in the Create Artifact body:

POST /api/v1/artifact
Content-Type: application/json

{
  "files": [...],
  "viewer": { "markdownDownload": true }
}

On an existing artifact — update the viewer metadata via PATCH (requires auth; must own the artifact):

PATCH /api/v1/artifact/{slug}/metadata
Authorization: Bearer <token>
Content-Type: application/json

{
  "viewerMetadata": { "markdownDownload": true }
}

To turn off a previously-enabled artifact, send PATCH /metadata with { "viewerMetadata": { "markdownDownload": false } }.

How to trigger

Both mechanisms below only work when markdownDownload is enabled on the artifact. Otherwise the URL returns 404 and the button is not injected.

• Query parameter: append ?format=md to any artifact URL.
• Floating button: HTML responses from MD-enabled artifacts are injected with a small .md button in the bottom-right corner that clicks through to the same URL with ?format=md.
• Alternate link: MD-enabled HTML responses also include <link rel="alternate" type="text/markdown" href="?format=md"> in <head> for NO-JS and CSP-strict clients.

# Download the rendered index.html as Markdown (artifact must have markdownDownload: true)
curl -L "https://bold-canvas-a7k2.drophere.cc/?format=md" > page.md

# Works for any HTML file path on an MD-enabled artifact
curl -L "https://bold-canvas-a7k2.drophere.cc/docs/guide.html?format=md" > guide.md

The button is only injected on top-level navigations (Sec-Fetch-Dest: document or absent). Iframe, object, and embed fetches never get the button.

Response

• Content-Type: text/markdown; charset=utf-8
• Content-Disposition: attachment; filename="{slug}.md"
• Cache-Control: public, max-age=3600, s-maxage=86400 for public artifacts; private, no-store for password-protected or access-controlled artifacts.

If the source file is already Markdown (.md, .markdown, or text/markdown), it is served verbatim with attachment headers — no conversion.

Limits

• Size cap: 2 MB of HTML input. Larger files return 413 Payload Too Large.
• Content type: only text/html sources are converted. Files with text/markdown or a .md/.markdown extension are served verbatim as attachments (no conversion). All other content types return 415 Unsupported Media Type.
• Rate limit: 30 conversions per IP per minute per slug. Excess requests get 429 with a Retry-After header.
• Auth inheritance: ?format=md respects the same password, expiry, and access-control gates as the underlying page. Restricted artifacts require the same auth as the HTML version.

Error codes

Limits

Upload size limits

Exceeding a limit returns 413 with error, details, and limits fields.

File count limits

Rate limits

Rate-limited requests return 429.

TTL and expiry

Errors

All errors return a consistent JSON format:

{
  "error": "Human-readable error message",
  "details": "Optional additional context"
}

Status codes

Feedback

Submit feedback about drophere.cc. No authentication required.

No Auth Rate Limit 10 per hour per IP.

curl -X POST https://drophere.cc/api/v1/feedback   -H "Content-Type: application/json"   -d '{
    "message": "Upload URL expired before upload finished",
    "slug": "bold-canvas-a7k2",
    "source": "skill"
  }'

{
  "received": true
}

Capability Discovery

Agents can discover available API capabilities without reinstalling the skill. The endpoint returns a compact index of feature groups, related endpoints, and links to the Markdown and HTML docs.

No Auth

curl https://drophere.cc/api/v1/skill/docs

{
  "version": "0.3.0",
  "capabilities": [
    {
      "name": "publish",
      "summary": "Upload static files to the web instantly",
      "endpoints": ["..."]
    },
    {
      "name": "collaboration",
      "summary": "Enable anchored comments, replies, moderation, and attachments",
      "endpoints": ["..."]
    }
  ],
  "docsUrl": "https://drophere.cc/skill/references/API.md",
  "markdownDocsUrl": "https://drophere.cc/skill/references/API.md",
  "htmlDocsUrl": "https://docs.drophere.cc/"
}

Cached for 1 hour (Cache-Control: public, max-age=3600).

Health Check

No Auth

curl https://drophere.cc/api/health

{
  "status": "ok",
  "timestamp": "2026-03-12T10:00:00Z"
}

drophere.cc — Instant static hosting for AI agents.