Public API

Call Dropl from your own scripts and servers. Base URL, authentication, scopes, errors, idempotency, rate limits, and upload limits.

The Public API lets your scripts and servers do what the Dropl MCP server does: work with client sites and showcases, upload photos and videos, and get embed codes.

It's for server-to-server use: it doesn't support calls from web pages in a browser (no CORS), and a key in front-end code would be visible to anyone. Keep keys on your server.

Base URL

https://www.dropl.io/api/v1

Every path below is relative to it.

Authentication

Send an API key as a Bearer token:

curl https://www.dropl.io/api/v1/me \
  -H "Authorization: Bearer $DROPL_API_KEY"

/me works with any scope and returns the account, the person the key acts as, their role, and the key's scopes and client sites. It's a good first call to check a key.

Scopes

Each endpoint needs one scope. A key without it gets INSUFFICIENT_SCOPE, and the message names the missing scope. See the list of scopes.

Keys limited to some client sites only see those sites.

Endpoints

A few common ones:

Method and path	Scope	What it does
`GET /me`	Any	The account, user, role, and key
`GET /sites`	`sites:read`	Client sites the key can reach
`POST /sites`	`sites:write`	Create a client site
`POST /sites/{siteId}/showcases`	`showcases:write`	Create a showcase
`GET /showcases/{showcaseId}/embed`	`embed:read`	Embed code for a showcase and each category
`GET /videos/{videoId}/embed`	`embed:read`	Embed code for a video

The OpenAPI document lists every endpoint with its request and response schemas. Load it into your API client or code generator.

Errors

Errors return a JSON body with a stable code, a readable message, and fieldErrors when specific fields are wrong:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Please check the highlighted fields.",
    "fieldErrors": { "name": ["Enter a name."] }
  }
}

Codes specific to API keys:

Status	Code	Meaning
401	`INVALID_API_KEY`	The key is missing, unknown, revoked, or expired, or its creator is no longer an owner or admin
403	`INSUFFICIENT_SCOPE`	The key doesn't have the scope this endpoint needs
403	`SITE_RESTRICTED_KEY`	Keys limited to some client sites can't create client sites
409	`IDEMPOTENCY_KEY_IN_PROGRESS`	The first request with this `Idempotency-Key` is still running
422	`IDEMPOTENCY_KEY_REUSED`	This `Idempotency-Key` was used for a different request

Other endpoints return the same codes as the dashboard, like VALIDATION_FAILED.

Idempotency

Endpoints that create things accept an Idempotency-Key header, so a retry after a timeout doesn't create a second client site or showcase. The OpenAPI document marks which ones.

Use a unique value per operation, like a UUID, up to 255 characters.
Sending the same key and the same request again within 24 hours returns the first response. Replayed responses carry an Idempotent-Replayed header.
Reusing a key for a different request fails with IDEMPOTENCY_KEY_REUSED.

Rate limits

Each key can make up to 600 requests per minute, across every endpoint. Over the limit, requests get HTTP 429: wait a moment and retry.

Upload limits

Videos: up to 20 GB each.
Photos: JPEG, PNG, WebP, AVIF or HEIC, up to 20 MB each and 100 per request.

Your plan limits total storage and monthly delivery. See Pricing.

Building a command-line tool? Instead of asking people to paste a key, use the same browser sign-in as the MCP server (the OAuth device flow):

POST /auth/device returns a user_code and a verification_uri_complete. Show the code and open the link.
The person checks the code and approves on the Connect an app page.
Poll POST /auth/device/token every 5 seconds until it returns an access_token, which is a new API key.

The code expires after 10 minutes. Details are in the OpenAPI document.

Next steps

API keys: create and manage keys.
Set up with AI: let Cursor or Claude Code do this for you.