API Reference

The sharedrop REST API lets you upload, manage, and share HTML pages programmatically.

Base URL

https://sharedrop.cloud/api/v1

Authentication

All requests require a Bearer token in the Authorization header:

curl -H "Authorization: Bearer sd_your_api_key_here" \
  https://sharedrop.cloud/api/v1/pages

See Authentication for details on obtaining and managing API keys.

Rate Limits

All API requests are rate-limited per API key based on your plan tier. Rate limit information is included in response headers.

Response Headers

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

Limits by Tier

Endpoint	Free	Pro	Team
Upload	20/min	100/min	200/min
List / Read / Update	60/min	300/min	600/min
Delete / Share	30/min	150/min	300/min

Response Format

Success

{
  "data": { ... }
}

List (Paginated)

{
  "data": [ ... ],
  "pagination": {
    "next_cursor": "uuid-or-null",
    "has_more": true
  }
}

Error

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

Error Codes

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Invalid or missing API key
`RATE_LIMIT_EXCEEDED`	429	Too many requests. Check `X-RateLimit-*` headers.
`PAGE_NOT_FOUND`	404	Page does not exist or you don't have access
`VALIDATION_ERROR`	400	Invalid request body or parameters
`PAGE_LIMIT_REACHED`	403	Page count limit exceeded for your plan
`FILE_SIZE_EXCEEDED`	413	File exceeds the size limit for your plan

Endpoints

Upload Page

POST /api/v1/pages

Upload an HTML file to create a new page. Supports two content types.

Raw HTML Body

Send HTML directly as the request body with Content-Type: text/html. Pass metadata as query parameters.

Query Parameters:

Parameter	Type	Default	Description
`title`	string	Extracted from HTML `<title>`	Page title
`mode`	string	`static`	`static` or `interactive`
`visibility`	string	`public` (Free) / `private` (Pro+)	`public`, `private`, or `shared`
`workspace_id`	string	--	Upload to a specific workspace

curl -X POST \
  -H "Authorization: Bearer sd_..." \
  -H "Content-Type: text/html" \
  -d "<html><body><h1>My Report</h1></body></html>" \
  "https://sharedrop.cloud/api/v1/pages?title=My+Report&mode=static"

FormData Upload

Send an HTML file as multipart form data.

curl -X POST \
  -H "Authorization: Bearer sd_..." \
  -F "file=@report.html" \
  -F "title=My Report" \
  https://sharedrop.cloud/api/v1/pages

Response 201:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "slug": "abc123",
    "title": "My Report",
    "mode": "static",
    "file_size": 2048,
    "visibility": "private",
    "url": "/username/abc123",
    "full_url": "https://sharedrop.cloud/username/abc123",
    "created_at": "2026-04-07T00:00:00.000Z",
    "updated_at": "2026-04-07T00:00:00.000Z"
  }
}

Error Cases:

400 VALIDATION_ERROR -- Empty body, invalid form data, non-HTML file
403 PAGE_LIMIT_REACHED -- Page count limit exceeded
413 FILE_SIZE_EXCEEDED -- File exceeds size limit (5 MB Free, 10 MB Pro/Team)

List Pages

GET /api/v1/pages

List your pages with cursor-based pagination.

Query Parameters:

Parameter	Type	Default	Description
`limit`	number	50	Results per page (max 100)
`cursor`	string	--	Pagination cursor from previous response
`workspace_id`	string	--	Filter to a specific workspace

curl -H "Authorization: Bearer sd_..." \
  "https://sharedrop.cloud/api/v1/pages?limit=10"

Response 200:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "slug": "abc123",
      "title": "My Report",
      "mode": "static",
      "file_size": 2048,
      "visibility": "private",
      "url": "/username/abc123",
      "full_url": "https://sharedrop.cloud/username/abc123",
      "created_at": "2026-04-07T00:00:00.000Z",
      "updated_at": "2026-04-07T00:00:00.000Z"
    }
  ],
  "pagination": {
    "next_cursor": "660e8400-e29b-41d4-a716-446655440001",
    "has_more": true
  }
}

To fetch the next page, pass cursor from pagination.next_cursor:

curl -H "Authorization: Bearer sd_..." \
  "https://sharedrop.cloud/api/v1/pages?limit=10&cursor=660e8400-e29b-41d4-a716-446655440001"

Get Page

GET /api/v1/pages/:id

Get metadata for a specific page.

curl -H "Authorization: Bearer sd_..." \
  https://sharedrop.cloud/api/v1/pages/550e8400-e29b-41d4-a716-446655440000

Response 200:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "slug": "abc123",
    "title": "My Report",
    "mode": "static",
    "file_size": 2048,
    "visibility": "private",
    "url": "/username/abc123",
    "full_url": "https://sharedrop.cloud/username/abc123",
    "created_at": "2026-04-07T00:00:00.000Z",
    "updated_at": "2026-04-07T00:00:00.000Z"
  }
}

Error Cases:

404 PAGE_NOT_FOUND -- Page does not exist or you don't have access

Update Page

PATCH /api/v1/pages/:id

Update a page's title or visibility.

Request Body (JSON):

Field	Type	Description
`title`	string	New page title
`visibility`	string	`public`, `private`, or `shared`

Both fields are optional. Include only the fields you want to change.

curl -X PATCH \
  -H "Authorization: Bearer sd_..." \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated Title", "visibility": "public"}' \
  https://sharedrop.cloud/api/v1/pages/550e8400-e29b-41d4-a716-446655440000

Response 200:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "slug": "abc123",
    "title": "Updated Title",
    "mode": "static",
    "file_size": 2048,
    "visibility": "public",
    "url": "/username/abc123",
    "full_url": "https://sharedrop.cloud/username/abc123",
    "created_at": "2026-04-07T00:00:00.000Z",
    "updated_at": "2026-04-07T00:00:00.000Z"
  }
}

Error Cases:

400 VALIDATION_ERROR -- Invalid JSON body or field values
403 VALIDATION_ERROR -- Visibility not available on your plan (e.g., private on Free tier)
404 PAGE_NOT_FOUND -- Page does not exist or you don't have access

Delete Page

DELETE /api/v1/pages/:id

Permanently delete a page and its stored HTML. This also deletes all versions, comments, shares, and access grants.

curl -X DELETE \
  -H "Authorization: Bearer sd_..." \
  https://sharedrop.cloud/api/v1/pages/550e8400-e29b-41d4-a716-446655440000

Response 200:

{
  "data": {
    "success": true
  }
}

Error Cases:

404 PAGE_NOT_FOUND -- Page does not exist or you don't have access

POST /api/v1/pages/:id/share

Share a page with someone by email address. Creates an access grant that allows the recipient to view the page.

Request Body (JSON):

Field	Type	Required	Description
`email`	string	Yes	Email address of the person to share with

curl -X POST \
  -H "Authorization: Bearer sd_..." \
  -H "Content-Type: application/json" \
  -d '{"email": "colleague@example.com"}' \
  https://sharedrop.cloud/api/v1/pages/550e8400-e29b-41d4-a716-446655440000/share

Response 201:

{
  "data": {
    "id": "grant-uuid",
    "email": "colleague@example.com",
    "status": "pending",
    "created_at": "2026-04-07T00:00:00.000Z"
  }
}

The grant starts as pending. When the recipient signs in to sharedrop with a matching email, the grant automatically activates and they can view the page.

Error Cases:

400 VALIDATION_ERROR -- Invalid email address
404 PAGE_NOT_FOUND -- Page does not exist or you don't have access

API Reference

Base URL

Authentication

Rate Limits

Response Headers

Limits by Tier

Response Format

Success

List (Paginated)

Error

Error Codes

Endpoints

Upload Page

Raw HTML Body

FormData Upload

List Pages

Get Page

Update Page

Delete Page

Share Page

On this page