Look up items by title

A person names items by their titles, as in a link written [[Reading list]]. To turn such names into items, ask for up to 200 of them in one request. In the TypeScript example, marfa is a client made as the TypeScript SDK shows.

Look up namesCopy anchor link

Find items by title takes the names and answers each one:

marfa items titles "Reading list" Plans

{
  "results": [
    {
      "name": "Reading list",
      "items": [],
      "more": false
    },
    {
      "name": "Plans",
      "items": [
        { "id": "01a1231c-986c-7edd-8d1f-235e036b7986", "type": "core.note", "title": "Plans", "has_blob": false },
        { "id": "01a15f3c-13ee-70ba-8ba1-6e00b9a76552", "type": "core.collection", "title": "plans", "has_blob": false }
      ],
      "more": false
    }
  ]
}

Each name gets one result, in the order you sent them, with the name as you sent it. A name that titles nothing gets no items, as Reading list does here, and a name that titles several gets them all, so the person can choose.

How a name matchesCopy anchor link

• The whole title must match. Case, the Unicode form and blank characters at either end don't count, so Plans finds plans. A name never matches part of a title.
• The title is the property the item's type is titled by, its display_hints.title_field or a parent type's, or title where no type up the line names one.
• Only items the key can list count, active or archived. Items in the bin, system.* items and items of a type the key can't read are left out, so a lookup never tells a key about an item it couldn't list.
• A name that matches more than 20 items answers the first 20 by id, with more set to true. Treat that name as naming no one item.
• A title longer than 1,000 UTF-16 code units matches no name, and a blank name matches nothing.

When a lookup is refusedCopy anchor link

• More than 200 names, a name longer than 1,000 UTF-16 code units, or a body that isn't a list of names answers 400 validation_error.
• A key that reaches no type answers 403 type_not_permitted.

A synced folder looks up its links' names this way, and says so when the instance refuses: Links by name wait for the server.

The rules behind this guide are under items/titles in the contract.