Using the API
Where the REST APIs and the MCP server answer, the key they take, and a first call to each.
DataDrop has two REST APIs, one for the vendor side and one for the buyer side, and an MCP server that lets an AI assistant read your organization's data. All three take an organization API key and nothing else: a browser's sign-in is not read there. Every operation and tool is listed in the references: Vendor API, Buyer API, Vendor MCP tools and Buyer MCP tools.
The address
The API is reached through the web app: an operation's address is your DataDrop site's address, then /api, then the operation's path. The examples on this page keep the first part in a variable:
export DATADROP_API="https://YOUR-SITE/api"So the reference's GET /v2/listings/browse is https://YOUR-SITE/api/v2/listings/browse. An address whose path holds a percent-encoded character is not passed on to the API.
The API does not serve its OpenAPI documents itself. The references on this site are made from them.
Make a key
A Team admin makes a key at Settings, API keys (the address /settings/api-keys, or API keys in the search menu): a name, what the key may do, and a lifetime of 30, 90 or 365 days. The whole key is shown once, when it is made; copy it then. Every member sees the organization's keys and when each was last used; only a Team admin renames or revokes one.
What a key may do is its scopes. Choose at least one:
| Scope | In the web app | What it opens |
|---|---|---|
uploads | Uploads | the upload routes the datadrop create command uses (Add assets) |
read | Read | every GET operation of the vendor and buyer APIs, and the MCP server |
write | Write | every other operation of the vendor API (POST, PATCH, PUT, DELETE) |
write does not include read: a program that changes listings and reads them back needs both.
- A key acts for its own organization only, as the Team admin who made it. No operation names an organization: the key decides which one.
- The vendor API answers only an organization that sells, and the buyer API only one that buys. The MCP server lists the tools of the sides your organization has.
- A key stops working at once when it is revoked, when it expires, or when the Team admin who made it is no longer one. An organization holds at most 20 keys that still work.
Send the key
A key is written ddk_, eight characters from 0 to 9 and a to f, an underscore, and the secret. Send it in the Authorization: Bearer header of every request, and nowhere else: a key in an address (its path or its query) is refused, and the request is answered as one with no key.
export DATADROP_API_KEY="ddk_..."A request with no key, a key that does not work, or a key without the scope the operation needs is answered 401, with {"error": "unauthenticated", "source": "user", "detail": "Not signed in"}. Every refusal of the REST APIs and of the MCP server's address has that shape: error names what went wrong, source is user for a refusal of the request and platform for a fault on our side, and detail says it in words.
A first REST call
One listing of the catalog, with a read key of any organization:
curl -sS "$DATADROP_API/v2/listings/browse?limit=1" \
-H "Authorization: Bearer $DATADROP_API_KEY"The answer is JSON: items (the listings), limit, and next_cursor, which you send back as cursor for the next page. This list takes a limit from one to a hundred.
An organization that sells, does not buy and has published fewer than two listings of its own gets the catalog's preview instead (locked is true): the first six listings of each type, whatever limit it asks, as in the web app (How it works).
The MCP server
The MCP server is the API's /v2/mcp/ operation, a POST; it answers without the slash too, so its address through the web app is $DATADROP_API/v2/mcp (the web app sends an address that ends in a slash on to the one without it, keeping the POST). It takes one JSON-RPC message per POST, answered with one JSON answer (no event stream, and no session to keep). It takes a key with the read scope, sent in the same Authorization: Bearer header, and every tool only reads: each one is a GET operation of the REST APIs, made with your key, so it sees exactly what that operation would.
These are the messages a client sends. First, as every MCP client does:
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}The answer names the server (datadrop) and the protocol version it will speak: the one you asked for when it knows it (2025-06-18, 2025-03-26 or 2024-11-05), else the newest. Then the tools your organization has:
{"jsonrpc":"2.0","id":2,"method":"tools/list"}And a call of one, here for one listing of the catalog:
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"browse_listings","arguments":{"limit":1}}}A tool's answer is the REST operation's JSON, as text in content; isError is true when the operation refused, with its error inside. An unknown method or tool, or an argument the tool does not take, is answered with a JSON-RPC error. The tools each side has, and their arguments, are in Vendor MCP tools and Buyer MCP tools.
Limits
Calls are counted in windows of a minute: at most 120 in a window for one key, 600 for all of an organization's keys together, and 300 from one network address, refused calls included. A call over a limit is answered 429, with a Retry-After header that gives the seconds until the window ends. These are the platform's current settings, and they can change.
Creating a listing (POST /v2/listings) takes an Idempotency-Key header: the same key and body sent again within a day answer the first create again and make nothing; the same key with another body is refused.