# Look up items by title (/build/look-up-items-by-title)

Turn the names a person typed, such as the targets of links in their notes, into the items those names title, many names in one request.



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](/typescript-sdk#create-a-client) shows.

## Look up names [#look-up-names]

[Find items by title](/api-reference/items/findItemsByTitle) takes the names and answers each one:



**CLI**

```bash  
marfa items titles "Reading list" Plans
```

**HTTP**

```http
POST /items/titles
Authorization: Bearer <key>
Content-Type: application/json

{ "names": ["Reading list", "Plans"] }
```

**TypeScript**

```ts
const { data } = await marfa.POST("/items/titles", {
  body: { names: ["Reading list", "Plans"] },
});
```

Response (200 OK):

```json
{
  "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 matches [#how-a-name-matches]

* **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 refused [#when-a-lookup-is-refused]

* **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](/run/sync-a-folder) looks up its links' names this way, and says so when the instance refuses: [Links by name wait for the server](/run/troubleshooting/folders#links-by-name-wait-for-the-server).

The rules behind this guide are under [`items/titles`](https://github.com/withmarfa/marfa/blob/main/conformance/spec/items.md#itemstitles) in the contract.