---
title: "Droppy public API and MCP server"
description: "Read-only access to Droppy's docs, droplets, releases and pricing over REST and MCP. No key needed."
canonical: "https://getdroppy.app/api.md"
---

# Droppy public API and MCP server

getdroppy.app answers questions about Droppy for Mac over two read-only surfaces: a REST API at `https://getdroppy.app/api/v1` and a remote MCP server at `https://getdroppy.app/mcp`. Both read the same sources the website is built from, so an answer from them matches what the site says.

Neither surface needs a key, an account or a sign-up. Every operation is a GET of public facts, so there is nothing an agent can change or break, and no separate sandbox is needed: the live API is safe to explore. Controlling Droppy on someone's Mac is a different, local server; see [MCP inside Droppy](#mcp-inside-droppy).

## When to use it

- An assistant answering "how do I…" questions about Droppy: search, then read the page.
- A comparison or recommendation that needs current pricing, the latest version or the list of droplets.
- A tool or bot that links people to the right page of the Droppy docs.

## REST API

Base URL: `https://getdroppy.app/api/v1`. Description: [openapi.json](https://getdroppy.app/openapi.json) (OpenAPI 3.1). Catalog: [/.well-known/api-catalog](https://getdroppy.app/.well-known/api-catalog) (RFC 9727).

| Operation | Request | Returns |
| --- | --- | --- |
| searchDocs | `GET /search?q={words}&section={all,site,docs,droplets,droppykit,blog}&limit={1-25}` | Ranked pages with a snippet and a Markdown URL |
| listPages | `GET /pages?section=&limit=&cursor=` | Every published page with its Markdown URL |
| lookupPage | `GET /pages/lookup?url=/docs/shelf` | One page's record and headings |
| listDroplets | `GET /droplets?q=&kind={built-in,store}&ids=a,b&limit=&cursor=` | Built-in and Store droplets; `ids` fetches several in one request |
| getDroplet | `GET /droplets/{id}` | One droplet, for example `ring` |
| getLatestRelease | `GET /releases/latest` | The newest version, its notes and the download link |
| listReleases | `GET /releases?limit=&cursor=` | Every release on the changelog, newest first |
| getPricing | `GET /pricing` | Price, license, trial, discounts and refund window |
| getStatus | `GET /status` | Whether the API is up |

Example:

```
curl -s 'https://getdroppy.app/api/v1/search?q=clipboard%20shortcut&limit=3'
```

```
{
  "query": "clipboard shortcut",
  "section": "all",
  "results": [
    {
      "title": "Clipboard",
      "url": "https://getdroppy.app/docs/clipboard",
      "markdown_url": "https://getdroppy.app/docs/clipboard.md",
      "section": "docs",
      "description": "…",
      "snippet": "…",
      "score": 41.5
    }
  ]
}
```

### Pagination

List operations take `limit` and `cursor` and answer `{ "data": [...], "next_cursor": "o50", "total": 389 }`. Pass `next_cursor` back as `cursor` for the next page; it is `null` on the last one. The response also carries `Link: <…>; rel="next"`.

### Rate limit

120 requests per 60 seconds per client. Every response carries `RateLimit-Policy: "default";q=120;w=60`. Beyond the limit you get `429` with `Retry-After: 60`. Responses are cacheable for five minutes (`Cache-Control`), so cache them.

### Errors

Errors are [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) `application/problem+json`:

```
{
  "type": "https://getdroppy.app/api.md#invalid_parameter",
  "title": "Invalid limit",
  "status": 400,
  "detail": "limit must be a whole number from 1 to 25; got \"500\".",
  "code": "invalid_parameter",
  "hint": "Pass limit=1 to limit=25, or leave it out for 8.",
  "docs": "https://getdroppy.app/api.md"
}
```

| Code | Status | Meaning |
| --- | --- | --- |
| <span id="invalid_parameter">`invalid_parameter`</span> | 400 | A parameter has the wrong type or value. |
| <span id="missing_parameter">`missing_parameter`</span> | 400 | A required parameter is missing. |
| <span id="invalid_cursor">`invalid_cursor`</span> | 400 | The cursor was not issued by this API. |
| <span id="not_found">`not_found`</span> | 404 | No such endpoint. |
| <span id="droplet_not_found">`droplet_not_found`</span> | 404 | No droplet has that id. |
| <span id="page_not_found">`page_not_found`</span> | 404 | No published page matches. |
| <span id="method_not_allowed">`method_not_allowed`</span> | 405 | Only GET, HEAD and OPTIONS are supported. |
| <span id="rate_limited">`rate_limited`</span> | 429 | Too many requests; wait for `Retry-After`. |
| <span id="upstream_unavailable">`upstream_unavailable`</span> | 503 | A data source is briefly unavailable; retry. |
| <span id="internal_error">`internal_error`</span> | 500 | Something unexpected; retry once. |

### Versioning

The major version is in the path. Additions (new fields, new endpoints) arrive without notice and never break a client that ignores fields it does not know. Breaking changes ship as `/api/v2`. A version that is going away answers with `Deprecation` and `Sunset` headers at least 90 days before it stops.

### CORS

Every endpoint sends `Access-Control-Allow-Origin: *`, so browser code on any site can call it.

## MCP server

`https://getdroppy.app/mcp` is a Model Context Protocol server over Streamable HTTP (protocol versions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05). It is stateless, needs no authentication and answers JSON. Its card is at [/mcp/server-card](https://getdroppy.app/mcp/server-card).

| Tool | Arguments | What it does |
| --- | --- | --- |
| `search_droppy_docs` | `query`, `section`, `limit` | Searches every page of getdroppy.app and returns ranked results with snippets. |
| `fetch_droppy_page` | `url`, `max_characters` | Returns one page as Markdown, by URL or path (`/docs/shelf`, `/pricing.md`). |
| `list_droplets` | `query`, `kind` | Lists built-in and Store droplets. Hosts that support MCP Apps render the result as cards. |

All three are read-only (`readOnlyHint: true`).

Add it to an MCP client:

```
{
  "mcpServers": {
    "droppy-docs": { "type": "http", "url": "https://getdroppy.app/mcp" }
  }
}
```

Claude Code: `claude mcp add --transport http droppy-docs https://getdroppy.app/mcp`

## MCP inside Droppy

The server above only reads the website. To let an AI app act on Droppy on a Mac (search clipboard history, start a Pomodoro, add a note, install a droplet), the person who owns the Mac switches on the MCP droplet in Droppy, under Settings, Droplet Store, MCP, and chooses which permissions AI apps get. That server runs locally through the helper at `/Applications/Droppy.app/Contents/Helpers/droppy-mcp` and is never reachable from the internet. Setup for Claude, Claude Code, Cursor and Codex: [MCP for AI apps](https://getdroppy.app/docs/mcp.md).

## More for agents

- [llms.txt](https://getdroppy.app/llms.txt): the index of this site.
- Markdown: add `.md` to any page path, or send `Accept: text/markdown`.
- [Agent skills](https://getdroppy.app/.well-known/agent-skills/index.json).
- [AI catalog](https://getdroppy.app/.well-known/ai-catalog.json).
- WebMCP: every page registers tools for browser agents (`search_droppy_docs`, `read_droppy_page`, `list_droplets`, `get_droppy_pricing`, `get_latest_droppy_release`, `open_droppy_page`).

Questions or a broken answer: hi@getdroppy.app, or post it on [The Trench](https://getdroppy.app/trench).