ListDrop for AI agents

Chat assistants produce list-shaped answers all day (reading lists, itineraries, step-by-step plans) and they die in the transcript. ListDrop is where they can live: saved, checkable, forkable, followable. One API call, no account, no key.

What to save (and when)

The test: would the user want this list after the conversation ends? Then save it and hand back the claim URL. Just connected the MCP connector and wondering what to ask your assistant for? These are the moves:

And when not: Skip throwaway answers nobody asked to keep, secrets or sensitive data (a draft is unowned until claimed), and content that isn't list-shaped.Don't offer a claim URL for every three-bullet answer; save when the user asks to keep, share, or track something, or when the keep test clearly passes.

Save a list (write)

Machine contract: /openapi.json (OpenAPI 3.1, typed, with operation ids). Errors are JSON with a stable code. The major version lives in the path (/api/v1); a breaking change ships as a new major and the old one keeps working for at least 90 days with Deprecation and Sunset headers. Every response carries API-Version and RateLimit / RateLimit-Policy headers (Retry-After on 429), so you can throttle yourself. No versions are deprecated today.

POST /api/v1/agent/lists (alias: /api/agent/lists): anonymous, CORS-open. The list is created unlisted and owned by no one; the response's claimUrl is the only way to see it. Treat it like a password. Give that URL to your user: they open it, press “Save my list”, and it becomes theirs (signing up on the spot if needed), private to them from that moment on. Unclaimed drafts expire after 30 days.

curl -X POST https://www.listdrop.co/api/v1/agent/lists \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Weekend in Oaxaca",
    "emoji": "🌮",
    "description": "Three days, mostly food",
    "tags": ["travel", "mexico"],
    "items": [
      "Tlayudas at Mercado 20 de Noviembre",
      { "text": "Monte Albán at sunrise", "note": "go before 9am" },
      "https://en.wikipedia.org/wiki/Hierve_el_Agua"
    ]
  }'

Response:

{
  "id": "…",
  "claimUrl": "https://www.listdrop.co/claim/…",
  "expiresAt": 1789068736808,
  "message": "Draft created. Give the claim URL to the user…"
}

Agent-only extras

A few capabilities live only on this API and the MCP tools (no UI yet) because agents are their natural first users. All optional: leave them out and the classic flow above is unchanged.

Share a private list with specific people (email gate)

Add allowed_emails (max 20) to create_list / POST /api/v1/agent/lists and the private list gets a guest list. The response includes a shareUrl: anyone opening it sees an unlock card, verifies one of the allowed addresses, and reads the list. No ListDrop account needed:

Access is strictly view-only and re-checked on every request; update the guest list (owner, OAuth) with PUT /api/v1/lists/<id>/allowed-emails— an empty array removes the gate. Verification sticks per browser for 90 days. Keyless drafts can be gated too: the guests can read the list while it's still unclaimed (give them shareUrl, never the claim URL), and the gate survives claiming. Gated lists stay out of feeds, search, /md, and every public surface.

Self-archiving lists

expires_in_days(1–365) makes a list wind down on schedule: past the date it is visible to its owner only (public lists unpublish, email gates close). Good for trip plans, event checklists, anything with a natural end date.

Webhooks on list changes

Polling /l/<id>/md works, but you can also be told. POST /api/v1/lists/<id>/webhooks with { "url": "https://…" } (OAuth, lists:read; the list must be visible to your account) registers an endpoint that receives a JSON POST on every content change: events added, removed, edited, sorted, renamed, deleted. Each delivery is signed: X-ListDrop-Signature: sha256=<hex HMAC-SHA256 of the raw body> with the per-hook secret returned once at registration. Ten consecutive failures disable a hook. Manage with GET /api/v1/webhooks and DELETE /api/v1/webhooks/<id>.

Bulk item edits

PATCH /api/v1/lists/<id>/items (OAuth, lists:write, lists you can edit) applies up to 100 structured operations in one call: { "ops": [{ "op": "add", "text": "…" }, { "op": "update", "id": "…", "note": "…" }, { "op": "remove", "id": "…" }], "order": ["id1", "id2"] }. Adds go through magic paste (URLs unfurl), followers see one activity entry per verb, and order reorders root items. Schemas for everything in the OpenAPI spec.

Read lists (read)

Every public list is available as clean markdown: append /md to its canonical URL (e.g. https://www.listdrop.co/l/<id>/md), or simply request the list page with an Accept: text/markdown header. Tag pages work the same way (https://www.listdrop.co/t/<tag>/md) and link every public list on a topic. Good entry points for finding lists: /llms.txt (curated index), /explore, and the sitemap. Lists are living documents. Re-fetch rather than caching long-term.

Prefer JSON? GET https://www.listdrop.co/api/v1/lists/<id> returns a typed list (items with url/note, owner, counts, canonical URL) and GET https://www.listdrop.co/api/v1/tags/<tag> every public list on a topic. Schemas are in the OpenAPI spec.

MCP connector

ListDrop is a remote MCP server (streamable HTTP; works keyless, and supports OAuth for account access). Add it to Claude, ChatGPT, or any MCP-capable client and your assistant gets create_list, get_list, and (once connected with OAuth) my_lists natively:

https://www.listdrop.co/mcp

To connect it yourself:

Easiest of all: open your assistant with a ready-made prompt and let it walk you through its own settings, or copy the prompt anywhere else.

ClaudeChatGPTPerplexityGrok

CLI

The official listdrop CLI (npm install -g listdrop) wraps this whole surface for terminals and agent shells: listdrop create -t "Title" item… (or pipe items in), listdrop get <url>, listdrop tag <tag>, and after listdrop login (OAuth), listdrop lists and account-direct creation. --json everywhere for typed output.

Account access (OAuth 2.1)

Everything above works with no account. If your agent should act on a user's own ListDrop account (create lists directly in it, read their private lists), use OAuth 2.1: authorization-code with PKCE (S256, required), public clients via dynamic client registration (RFC 7591), refresh-token rotation. Discovery is standard:

Tell us what's missing

Agents are first-class users here, so there is a first-class way to complain. Send anything useful: a call that failed, a field this API should have, documentation that lied, a limit that got in the way, or what your user said when they saw the list you saved for them. A person reads every message, and this is how the API changes.

curl -X POST https://www.listdrop.co/api/v1/feedback \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "create_list rejects items over 50; I had a 120-item reading list and had to split it.",
    "kind": "problem",
    "source": "mcp",
    "context": { "client": "claude-desktop", "tool": "create_list" }
  }'

For humans

No integration needed: copy any AI answer and drop it on listdrop.co/paste. Bullets become a real list you can keep.