lists

Create a list (keyless draft + claim URL, or directly in the connected account)

Creates a list from list-shaped content the user will want to keep: an itinerary, a reading or watch list, a packing list, gift ideas, an apartment or job-search shortlist, a step-by-step plan, a checklist. The test: would the user want this list after the conversation ends? The list is born PRIVATE and unowned; the response's claimUrl is the only way to view and keep it. Show the claim URL to the user and treat it like a password. Unclaimed drafts expire in 30 days. Items that contain a URL are unfurled into titled, linked items. CORS-open. Rate limits: 50 per hour and 300 per day per IP. With an OAuth bearer token carrying lists:write, the list is instead created directly in the user's account (private, no claim URL; response has url instead of claimUrl) and limits are per user. Optional extras: allowed_emails email-gates the private list for specific viewers (see the schema), expires_in_days makes it self-archive.

post/api/v1/agent/lists

Request

  • Base URL: https://www.listdrop.co
  • URL: https://www.listdrop.co/api/v1/agent/lists
  • Auth: one of:
    • none
    • OAuth 2 (authorization code, authorization URL https://www.listdrop.co/oauth/authorize, token URL https://www.listdrop.co/api/oauth/token, scopes: lists:write)

Request body

titlestring required
emojistring

Optional single emoji for the list.

descriptionstring
tagsstring[]

Topic tags, plain words (books, travel).

allowed_emailsstring[]

Optional email gate: these addresses can VIEW the private list at its URL after verifying the address via a mailed one-time link — no ListDrop account needed. View-only; omit for the classic unlisted claim-link behavior.

expires_in_daysinteger

Optional self-archive: after this many days the list becomes visible to its owner only (public lists unpublish, email gates close).

Response

Created. Keyless: a draft with claimUrl. OAuth: an owned private list with url.

idstring required

List id.

claimUrlstring uri

Keyless flow only. Secret URL: the only way to view and keep the list. Show it to the user only.

urlstring uri

OAuth flow only: the created list's page in the user's account.

expiresAtinteger

Keyless flow only: unix ms after which an unclaimed draft is purged.

shareUrlstring uri

Present when allowed_emails was set (keyless flow): the URL the allowlisted people open — share THIS with them, never the claim URL.

allowedEmailsstring[]

Echo of the accepted (normalized) guest list, when allowed_emails was set.

messagestring required

Instructions to relay to the user.

Changes

No recorded changes to this operation across all 1 revision of this API.