Curated

Verify the connected account and its readiness before creating or changing lists. Returns account requirements, recovery URLs and what this connection may do. Never ask for a token in chat.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Return the person's own lists (slug, title, status, Inbox flag) and the lists they have access to. Call before add_item when unsure which list to target.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Create a new private list and return the exact slug to reuse in add_item. Repeating the same request dedupes instead of creating another recent list.

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "List title, 120 characters or fewer."
    },
    "subtitle": {
      "type": "string",
      "description": "One-line description of what the list is and who it's for."
    },
    "category": {
      "type": "string",
      "description": "Usually omit: Curated picks the category from the title and picks. Set it only when the person names one: Food & Drink, Travel, Books, Music, Movies & TV, Gear & Tools, Software, Fashion, Home & Garden, Ideas & Essays, Art, or Spirituality."
    },
    "idempotency_key": {
      "type": "string",
      "maxLength": 200,
      "description": "Optional retry key. Reusing it with identical input replays the first result."
    }
  },
  "required": [
    "title"
  ],
  "additionalProperties": false
}

Edit a list's title, subtitle, or category. Saves the working version without publishing. Readers keep seeing the last approved version until the owner approves a list update.

{
  "type": "object",
  "properties": {
    "list": {
      "type": "string",
      "description": "Which list: slug, exact title, or id. Must match exactly one list or the call fails."
    },
    "title": {
      "type": "string",
      "description": "New title."
    },
    "subtitle": {
      "type": "string",
      "description": "New subtitle. Pass an empty string to clear."
    },
    "category": {
      "type": "string",
      "description": "The category the person chose: Food & Drink, Travel, Books, Music, Movies & TV, Gear & Tools, Software, Fashion, Home & Garden, Ideas & Essays, Art, or Spirituality. Their choice stays; an empty string clears it."
    }
  },
  "required": [
    "list"
  ],
  "additionalProperties": false
}

Archive one of the person's lists: it leaves their profile, search and readers' view, and its page stops working. Nothing is lost; unarchive_list brings it back. Confirm with the person first.

{
  "type": "object",
  "properties": {
    "list": {
      "type": "string",
      "description": "Which list: slug, exact title, or id. Must match exactly one list or the call fails."
    }
  },
  "required": [
    "list"
  ],
  "additionalProperties": false
}

Bring an archived list back. It returns as a private list: going live again is a separate publish the person chooses.

{
  "type": "object",
  "properties": {
    "list": {
      "type": "string",
      "description": "Which archived list: slug, exact title, or id."
    }
  },
  "required": [
    "list"
  ],
  "additionalProperties": false
}

Delete one of the person's lists for good. It disappears for them and for readers and cannot be brought back. Refused for Inbox. Only after the person asks to delete that exact list by name; offer archive_list when they may want it back.

{
  "type": "object",
  "properties": {
    "list": {
      "type": "string",
      "description": "Which list: slug, exact title, or id. Must match exactly one list or the call fails."
    },
    "confirmTitle": {
      "type": "string",
      "description": "The list's exact title, after the person confirms deleting it. A different title deletes nothing."
    }
  },
  "required": [
    "list",
    "confirmTitle"
  ],
  "additionalProperties": false
}

Capture one pick with the person's own note. Omit `list` only to deliberately use Inbox. An ambiguous or missing list writes nothing and returns candidates; ask the person, or set `create_if_missing` when they explicitly want a new list. Report the returned details status exactly.

{
  "type": "object",
  "properties": {
    "list": {
      "type": "string",
      "description": "List slug or title. Fuzzy-matched against the curator's lists. Omit to use Inbox."
    },
    "url": {
      "type": "string",
      "description": "The URL being captured, if any."
    },
    "title": {
      "type": "string",
      "description": "Short title for the pick (e.g. restaurant name, book title). Required when url is absent."
    },
    "note": {
      "type": "string",
      "description": "The curator's own note on why they like or recommend this pick. Shown to readers as written and never rewritten by AI, so capture it in the curator's voice when they give a reason."
    },
    "author": {
      "type": "string",
      "description": "Author or creator as the person gives it (books, articles, posts), e.g. from \"Title - Author - why\". Stored as the pick's author and never replaced by added details. Keep it out of the note."
    },
    "create_if_missing": {
      "type": "boolean",
      "description": "When true and no list matches `list`, create that private list and save there."
    },
    "idempotency_key": {
      "type": "string",
      "maxLength": 200,
      "description": "Optional retry key. Reusing it with identical input replays the first result."
    }
  },
  "additionalProperties": false
}

Add up to 50 picks to one list in a single call, in order. Unlike add_item this never falls back to the Inbox: `list` must resolve to exactly one of the curator's lists or nothing is written.

{
  "type": "object",
  "properties": {
    "idempotency_key": {
      "type": "string",
      "maxLength": 200,
      "description": "Stable key for this reviewed batch. Reuse the same key and identical picks after a lost response."
    },
    "list": {
      "type": "string",
      "description": "Which list: exact slug, handle/slug, or id from a previous result."
    },
    "items": {
      "type": "array",
      "maxItems": 50,
      "description": "Up to 50 picks, added in the order given.",
      "items": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "Item title. Required unless a url is given."
          },
          "url": {
            "type": "string",
            "description": "The pick URL, if any."
          },
          "note": {
            "type": "string",
            "description": "The curator's own reason for recommending it. Stored verbatim and never AI-rewritten."
          },
          "author": {
            "type": "string",
            "description": "Author or creator as the person gives it (books, articles, posts), e.g. from \"Title - Author - why\". Stored as the pick's author and never replaced by added details. Keep it out of the note."
          }
        },
        "additionalProperties": false
      }
    }
  },
  "required": [
    "list",
    "items"
  ],
  "additionalProperties": false
}

Import picks into a list from one link: a Google Maps list shared with "Anyone with the link" (every place, in order, with the owner's notes; pasting it again adds only new places), a Google Maps place (one pick) or a public YouTube playlist (up to 500 videos). Spotify playlists and Letterboxd lists no longer let apps read them; the tool says so, and the person can bring their export in Curated instead. For a whole list you want to sort first, use start_import.

{
  "type": "object",
  "properties": {
    "list": {
      "type": "string",
      "description": "Which list: exact slug, handle/slug, or id from a previous result."
    },
    "url": {
      "type": "string",
      "description": "A Google Maps shared list or place link (maps.app.goo.gl works), Spotify playlist, YouTube playlist (a link with list=) or Letterboxd list URL."
    }
  },
  "required": [
    "list",
    "url"
  ],
  "additionalProperties": false
}

Bring a whole list in to sort, privately. Pass `url` for a Google Maps list shared with "Anyone with the link" (Curated reads every place), or `picks` you read yourself from anywhere else: a page, an account, a document or an export (up to 1,000 per call; send more with stage_picks). Nothing is added to a list until commit_import, and nothing is published.

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "A Google Maps shared-list link (maps.app.goo.gl works). Omit when sending picks."
    },
    "title": {
      "type": "string",
      "description": "The source list's own name, e.g. \"@tinnedfish's posts\" or \"Films I rewatch\". Required with picks."
    },
    "source_owner": {
      "type": "string",
      "description": "Whose list or account it is, when it is not the person's own, e.g. \"@tinnedfish\". Credits them on the list."
    },
    "own_list": {
      "type": "boolean",
      "description": "True (default) when the source is the person's own: their notes become their notes. False for someone else's list or account: words stay credited to them."
    },
    "sort": {
      "type": "boolean",
      "description": "True when most entries are probably not recommendations (an account's posts, saved posts): everything arrives unsorted for the person to keep or skip. Default false: everything arrives kept."
    },
    "list": {
      "type": "string",
      "description": "Optional destination list. Otherwise commit_import can make a new private list."
    },
    "picks": {
      "type": "array",
      "maxItems": 1000,
      "items": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "note": {
            "type": "string",
            "description": "The person's own words, only when the source is theirs."
          },
          "author": {
            "type": "string",
            "description": "Author or creator as the person gives it (books, articles, posts), e.g. from \"Title - Author - why\". Stored as the pick's author and never replaced by added details. Keep it out of the note."
          },
          "source_text": {
            "type": "string",
            "description": "Someone else's words about it (a caption or review), quoted exactly and short. Kept credited, never the person's note."
          },
          "source_account": {
            "type": "string",
            "description": "Who wrote source_text, e.g. \"@tinnedfish\"."
          },
          "saved_at": {
            "type": "string",
            "description": "When it was posted or saved at the source, ISO 8601."
          },
          "entry_key": {
            "type": "string",
            "description": "A stable id for this entry in its source (a post's permalink id), so running again brings only new entries."
          },
          "item_type": {
            "type": "string",
            "description": "place, book, movie, music, post, product or another Curated type, when obvious."
          }
        },
        "required": [
          "title"
        ],
        "additionalProperties": false
      }
    },
    "idempotency_key": {
      "type": "string",
      "maxLength": 200,
      "description": "Optional retry key. Reusing it with identical input replays the first result."
    }
  },
  "additionalProperties": false
}

Add up to 1,000 more picks to an import started with start_import, for sources longer than one call.

{
  "type": "object",
  "properties": {
    "import_id": {
      "type": "string",
      "description": "The id start_import returned."
    },
    "picks": {
      "type": "array",
      "maxItems": 1000,
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "sort": {
      "type": "boolean",
      "description": "Same meaning as in start_import."
    }
  },
  "required": [
    "import_id",
    "picks"
  ],
  "additionalProperties": false
}

Read an import's entries with their ids and states (kept, skipped, unsorted), to show the person or to sort.

{
  "type": "object",
  "properties": {
    "import_id": {
      "type": "string"
    },
    "state": {
      "type": "string",
      "enum": [
        "pending",
        "kept",
        "skipped",
        "committed"
      ],
      "description": "Only entries in this state."
    },
    "offset": {
      "type": "integer",
      "minimum": 0
    }
  },
  "required": [
    "import_id"
  ],
  "additionalProperties": false
}

Keep or skip entries in an import, by id or all unsorted at once, as the person decides. Never decide for them which posts are recommendations; suggest, then ask.

{
  "type": "object",
  "properties": {
    "import_id": {
      "type": "string"
    },
    "keep": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Entry ids to keep."
    },
    "skip": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Entry ids to skip."
    },
    "rest": {
      "type": "string",
      "enum": [
        "keep",
        "skip"
      ],
      "description": "Then keep or skip every entry still unsorted."
    }
  },
  "required": [
    "import_id"
  ],
  "additionalProperties": false
}

Add the kept entries of an import to a list, privately: the list given at start_import, another list of theirs, or a new private list. Safe to retry; nothing is added twice. A Google Maps list can stay connected so new saves there show up later.

{
  "type": "object",
  "properties": {
    "import_id": {
      "type": "string"
    },
    "list": {
      "type": "string",
      "description": "Destination, when start_import had none. Omit to make a new private list."
    },
    "new_list_title": {
      "type": "string",
      "description": "Title for a new list. Defaults to the source's title."
    },
    "connect": {
      "type": "boolean",
      "description": "Keep a Google Maps list connected (default true)."
    }
  },
  "required": [
    "import_id"
  ],
  "additionalProperties": false
}

Show what one of the person's lists is connected to: when it was last checked, what is new and waiting, and what is gone at the source.

{
  "type": "object",
  "properties": {
    "list": {
      "type": "string",
      "description": "Which list: exact slug, handle/slug, or id from a previous result."
    }
  },
  "required": [
    "list"
  ],
  "additionalProperties": false
}

Read a connected list's source again now (up to 10 times a day per list). New entries arrive by the list's policy; nothing is removed.

{
  "type": "object",
  "properties": {
    "source_id": {
      "type": "string",
      "description": "A connection id from list_sources."
    },
    "policy": {
      "type": "string",
      "enum": [
        "ask",
        "add_private"
      ],
      "description": "Optionally change what happens to new entries first: wait to be sorted (ask) or be added privately (add_private). Add and publish is set in Curated, after the person verifies the list is theirs."
    }
  },
  "required": [
    "source_id"
  ],
  "additionalProperties": false
}

Read every pick in one of your lists, in reader order, with item ids. Call this before update_item or remove_item to get the id you need.

{
  "type": "object",
  "properties": {
    "list": {
      "type": "string",
      "description": "Which list: exact slug, handle/slug, or id from a previous result."
    }
  },
  "required": [
    "list"
  ],
  "additionalProperties": false
}

Search the curator's own picks by title or URL. Useful to check for a duplicate before add_item.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Search string."
    },
    "list": {
      "type": "string",
      "description": "Optional list slug or title to scope the search."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}

Edit one pick's title, curator note, URL or author. The note is the curator's own words and is never rewritten by AI, so preserve their voice.

{
  "type": "object",
  "properties": {
    "itemId": {
      "type": "string",
      "description": "Item id from list_items or search_items."
    },
    "title": {
      "type": "string",
      "description": "New title."
    },
    "note": {
      "type": "string",
      "description": "New curator note. Pass an empty string to clear it."
    },
    "url": {
      "type": "string",
      "description": "New URL. Pass an empty string to clear it."
    },
    "author": {
      "type": "string",
      "description": "Author or creator as the person gives it (books, articles, posts), e.g. from \"Title - Author - why\". Stored as the pick's author and never replaced by added details. Keep it out of the note. Pass an empty string to remove it."
    }
  },
  "required": [
    "itemId"
  ],
  "additionalProperties": false
}

Remove one pick from a list. Curated keeps it with its note, links and saves, and restore_item puts it back. Confirm with the curator first. Changes the working version only; readers keep seeing the last approved version until the owner approves a list update.

{
  "type": "object",
  "properties": {
    "itemId": {
      "type": "string",
      "description": "Item id from list_items or search_items."
    }
  },
  "required": [
    "itemId"
  ],
  "additionalProperties": false
}

List picks removed from one of the person's lists that have not been put back, newest first, with their notes and ids for restore_item. Follow nextCursor as cursor to reach older picks.

{
  "type": "object",
  "properties": {
    "list": {
      "type": "string",
      "description": "Which list: exact slug, handle/slug, or id from a previous result."
    },
    "cursor": {
      "type": "string",
      "description": "nextCursor from the previous removed_items page; omit for the newest picks."
    }
  },
  "required": [
    "list"
  ],
  "additionalProperties": false
}

Put a removed pick back on its list where it was, with the same id, note, details, links and saves. Changes the working version only; readers keep seeing the last approved version until the owner approves a list update.

{
  "type": "object",
  "properties": {
    "itemId": {
      "type": "string",
      "description": "removedId from remove_item, or an id from removed_items."
    }
  },
  "required": [
    "itemId"
  ],
  "additionalProperties": false
}

Put a list's picks in a new order. Pass every item id exactly once, first to last, and the `revision` from list_items; if the list changed since, nothing is written and the current revision comes back. Changes the working order only; readers keep seeing the last approved version until the owner approves a list update. Private lists stay private.

{
  "type": "object",
  "properties": {
    "list": {
      "type": "string",
      "description": "Which list: exact slug, handle/slug, or id from a previous result."
    },
    "order": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 1000,
      "description": "Every item id in the list, in the new order."
    },
    "revision": {
      "type": "string",
      "description": "The `revision` list_items returned."
    }
  },
  "required": [
    "list",
    "order",
    "revision"
  ],
  "additionalProperties": false
}

Move picks from one of the person's lists to another, keeping each pick's note, details and history. They go to the end of the destination in the order given. Pass the source list's `revision` from list_items; if it changed since, nothing moves. Changes the working versions only; readers keep seeing the last approved versions. On a live destination, call review_items and confirm_items for the moved picks after the person's approval. Updating the source's published version requires separate owner approval. Private lists stay private.

{
  "type": "object",
  "properties": {
    "from": {
      "type": "string",
      "description": "The list the picks are in now."
    },
    "to": {
      "type": "string",
      "description": "The list to move them to."
    },
    "itemIds": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 100,
      "description": "Item ids from list_items on the `from` list."
    },
    "revision": {
      "type": "string",
      "description": "The `revision` list_items returned for the `from` list."
    },
    "toRevision": {
      "type": "string",
      "description": "Optional: the destination revision, to refuse the move if it changed too."
    }
  },
  "required": [
    "from",
    "to",
    "itemIds",
    "revision"
  ],
  "additionalProperties": false
}

After adding or importing picks, fetch their enriched preview here. If preparing, wait briefly and call again. Render previewMarkdown: supplied artwork, title/byline, original note, short description and labeled links for every pick. Keep reviewId and itemRefs internal. Omit IDs, positions, confidence scores and provenance commentary. Ask once if it looks good. No app visit or later list update is needed. An unfinished preview survives reconnecting.

{
  "type": "object",
  "properties": {
    "list": {
      "type": "string",
      "description": "Which list: exact slug, handle/slug, or id from a previous result."
    }
  },
  "required": [
    "list"
  ],
  "additionalProperties": false
}

Read whether an exact pick preview was already confirmed, is pending, or expired. Use when reopening a previous preview or checking a lost confirmation response. Never adds picks, starts enrichment, or changes the review. Keep reviewId internal. If confirmed, do not ask for approval again.

{
  "type": "object",
  "properties": {
    "reviewId": {
      "type": "string",
      "description": "reviewId from review_items."
    }
  },
  "required": [
    "reviewId"
  ],
  "additionalProperties": false
}

After the person approves the enriched preview from review_items, finish adding those exact picks. Published lists show them immediately; private lists stay private. Never approves unrelated edits. Requires lists.publish only for a published destination. If the preview changed, call review_items and show the refreshed picks.

{
  "type": "object",
  "properties": {
    "reviewId": {
      "type": "string",
      "description": "reviewId from review_items."
    }
  },
  "required": [
    "reviewId"
  ],
  "additionalProperties": false
}

Prepare first publication or a list-wide update. For new picks use review_items and confirm_items during addition. Publishes nothing. Returns exactly what would become public and, when this connection may publish from chat, a review to confirm with confirm_publication after the owner agrees. Otherwise it returns a browser link where the owner publishes. Show the supplied public URL as a clickable link labeled "Link after publishing", distinct from the owner-only review link. The returned preview is the exact public content: present it as written, with no added images, layouts or caveats.

{
  "type": "object",
  "properties": {
    "list": {
      "type": "string",
      "description": "Which list: exact slug, handle/slug, or id from a previous result."
    }
  },
  "required": [
    "list"
  ],
  "additionalProperties": false
}

Publish the exact list the owner reviewed, after they explicitly agree to that summary in this conversation. Never on an earlier general instruction like 'publish when done'. If anything changed since the review, nothing is published and a fresh review comes back to show them.

{
  "type": "object",
  "properties": {
    "reviewId": {
      "type": "string",
      "description": "review.reviewId from publish_list."
    },
    "handle": {
      "type": "string",
      "description": "Only when the review showed an unconfirmed handle: the same handle, after the owner confirms it's theirs to show publicly."
    }
  },
  "required": [
    "reviewId"
  ],
  "additionalProperties": false
}

Search every live list on Curated, not just the person's own. Each result carries `access` (yours, unlocked or locked) and a `ref` of the form handle/slug, the unambiguous way to name a list in get_list.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "What to look for, e.g. \"natural wine bars in Lisbon\"."
    },
    "category": {
      "type": "string",
      "description": "Optional category slug to narrow results, e.g. \"restaurants\"."
    },
    "limit": {
      "type": "number",
      "description": "Max results, 1 to 25. Defaults to 10."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}

Search live Curated lists by topic, title, or curator handle. Returns exact slugs; use get_list_items to read one.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "What the user is looking for."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}

Read one list: every pick of a live list, or of one of the person's own. Accepts handle/slug, a bare slug, a title, or an id.

{
  "type": "object",
  "properties": {
    "list": {
      "type": "string",
      "description": "Which list: handle/slug, slug, title, or id."
    },
    "format": {
      "type": "string",
      "enum": [
        "text",
        "markdown"
      ],
      "description": "How to render the reply text. 'text' (default): numbered rows, one field per line, best for reading the list yourself. 'markdown': linked bold titles and quoted notes, for relaying the list to the user as-is."
    }
  },
  "required": [
    "list"
  ],
  "additionalProperties": false
}

Read one list and report each pick's details status. The capture read-back check; use the exact slug returned by create_list or list_my_lists.

{
  "type": "object",
  "properties": {
    "list": {
      "type": "string",
      "description": "Exact returned slug, handle/slug, title, or id."
    },
    "format": {
      "type": "string",
      "enum": [
        "text",
        "markdown"
      ],
      "description": "How to render the reply text. 'text' (default): numbered rows, one field per line, best for reading the list yourself. 'markdown': linked bold titles and quoted notes, for relaying the list to the user as-is."
    }
  },
  "required": [
    "list"
  ],
  "additionalProperties": false
}

Save a live list to Library under Saved lists, with its new picks. Never follows the curator, turns on email or publishes. Idempotent across retries.

{
  "type": "object",
  "properties": {
    "list": {
      "type": "string",
      "description": "Exact list id or slug."
    }
  },
  "required": [
    "list"
  ],
  "additionalProperties": false
}

Read back Saved lists, matching the app. Each one brings its new picks.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 100
    }
  },
  "additionalProperties": false
}

Save one pick from a list you can read, yours or anyone's, to Library under Saved picks. Use the item id from get_list_items or list_items. Does not copy the pick, follow or publish. Idempotent across retries.

{
  "type": "object",
  "properties": {
    "itemId": {
      "type": "string",
      "description": "Item id from get_list_items, list_items or search_items."
    },
    "list": {
      "type": "string",
      "description": "Optional list id, slug or handle/slug the pick came from; rejected if the pick is on a different list."
    }
  },
  "required": [
    "itemId"
  ],
  "additionalProperties": false
}

Remove one pick from Saved picks. Idempotent. Never changes the list or the pick.

{
  "type": "object",
  "properties": {
    "itemId": {
      "type": "string",
      "description": "Item id from saved_items."
    }
  },
  "required": [
    "itemId"
  ],
  "additionalProperties": false
}

Read back your saved picks across every list, newest first, matching Saved picks in the app. Separate from saved_lists and from my_library access.

{
  "type": "object",
  "properties": {
    "list": {
      "type": "string",
      "description": "Optional list id, slug or handle/slug to show saves from one list."
    },
    "limit": {
      "type": "number",
      "minimum": 1,
      "maximum": 100
    },
    "cursor": {
      "type": "string",
      "description": "The cursor from a previous saved_items result, to read further."
    }
  },
  "additionalProperties": false
}

Add a pick you can read, usually one from saved_items, to one of your own lists as a new pick. Carries the facts (title, link, place, type) and records where it was found; the note starts empty because the source curator's words are theirs. Does not change the source list or the save.

{
  "type": "object",
  "properties": {
    "itemId": {
      "type": "string",
      "description": "Item id from saved_items or get_list_items."
    },
    "list": {
      "type": "string",
      "description": "Your list slug or title. Call list_my_lists if unsure."
    },
    "idempotency_key": {
      "type": "string",
      "description": "Stable across retries so a lost response does not add the pick twice."
    }
  },
  "required": [
    "itemId",
    "list"
  ],
  "additionalProperties": false
}

The lists this person saved, each bringing its new picks. Their own lists are not included; use list_my_lists for those.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "number",
      "description": "Max lists, 1 to 200. Defaults to 50."
    }
  },
  "additionalProperties": false
}

Search inside the lists this person has access to: "what was that ramen place from the Tokyo list?". Only searches lists they can read in full.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Search string, matched against pick titles, URLs, and descriptions."
    },
    "list": {
      "type": "string",
      "description": "Optional: restrict to one list (handle/slug, slug, title, or id)."
    },
    "limit": {
      "type": "number",
      "description": "Max picks, 1 to 50. Defaults to 20."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}

What's new in the lists this person has access to since a point in time. Defaults to the last 7 days. Pass the returned `checkedAt` back as `since` next time for a gap-free diff.

{
  "type": "object",
  "properties": {
    "since": {
      "type": "string",
      "description": "ISO 8601 timestamp. Defaults to 7 days ago."
    },
    "limit": {
      "type": "number",
      "description": "Max new picks, 1 to 200. Defaults to 50."
    }
  },
  "additionalProperties": false
}

Older name for save_list on a live free list: saves it to Library with its new picks. Only when asked. Idempotent; no curator follow, email or payment. Read back with saved_lists.

{
  "type": "object",
  "properties": {
    "list": {
      "type": "string"
    }
  },
  "required": [
    "list"
  ],
  "additionalProperties": false
}

Explicitly follow or unfollow a curator by handle. Idempotent desired state, never a toggle. Does not save a list or enable email.

{
  "type": "object",
  "properties": {
    "handle": {
      "type": "string"
    },
    "following": {
      "type": "boolean"
    }
  },
  "required": [
    "handle",
    "following"
  ],
  "additionalProperties": false
}

Read a followed curator's email preference, or set `enabled` only on an explicit email request. Follow is separate consent; list access and bookmarks are unchanged.

{
  "type": "object",
  "properties": {
    "handle": {
      "type": "string"
    },
    "enabled": {
      "type": "boolean"
    }
  },
  "required": [
    "handle"
  ],
  "additionalProperties": false
}

Read every notification setting when `push` and `email` are omitted. Only on an explicit request, set push and/or email about new picks on one list the person gets updates for. Never changes access, saves or follows.

{
  "type": "object",
  "properties": {
    "list": {
      "type": "string",
      "description": "List id, slug or handle/slug; required when setting."
    },
    "push": {
      "type": "boolean"
    },
    "email": {
      "type": "boolean"
    }
  },
  "additionalProperties": false
}

Save a live free list with its new picks, only when the person asks. Same result as save_list. Idempotent; never charges anyone.

{
  "type": "object",
  "properties": {
    "list": {
      "type": "string",
      "description": "Which list: handle/slug, slug, title, or id."
    }
  },
  "required": [
    "list"
  ],
  "additionalProperties": false
}