---
title: "Search items and lists"
method: GET
path: "/api/v1/search"
tags: ["Search"]
---

# Search items and lists

`GET /api/v1/search`

## Request

- Base URL: `https://api.roma.app`
- URL: `https://api.roma.app/api/v1/search`
- Auth: HTTP bearer

Search the user's Roma workspace — their items (tasks, notes, the rows of every list they keep) and their lists, and what others shared with them (an item shared on its own, a list they joined and every item on it, each marked `isSharedWithMe`) — by meaning or keyword (hybrid semantic + keyword retrieval). Use this when the user asks about their own information, plans or anything they may have saved, and before adding something that may already exist. Their wording often won't match their notes' wording; the semantic arm bridges that gap (and across languages). Returns the best-matching passage per item, each with its list; get_item returns an item in full. An empty result means nothing relevant is saved. Not for general web knowledge.

## Query parameters

- `q` string, required: Natural-language query — what the user is trying to find, in their words.
- `limit` integer: Max results (default 10).
- `after` string: Only items CREATED on/after this ISO 8601 timestamp. Use when scoping by when it was saved ("last week", "in March").
- `before` string: Only items CREATED before this ISO 8601 timestamp (exclusive). Pair with `after` to bound a window.

## Response `200`

The tool's result.

- object
  - `count` number, required
  - `results` object[], required
    - `type` 'item' | 'list', required
    - `id` string, required
    - `title` string, required
    - `snippet` string, required
    - `listId` string, nullable
    - `listName` string, nullable
    - `isSharedWithMe` boolean: Shared with the person by its owner: an item shared with them (on its own, or on a list they joined) or a list they joined. An item shared on its own names no list.

## Other responses

- `400`: The request was understood and refused; the error says what to change.
- `401`: No usable bearer token.
- `404`: No such item for this account.
- `405`: The path exists but not with this method; Allow lists the ones that work.
- `429`: Over the rate limit; wait for Retry-After.

---

[API](https://skmtc.dev/roma/apis/roma-api.md) - [All operations](https://skmtc.dev/roma/apis/roma-api/llms.txt) - [OpenAPI document](https://skmtc.dev/roma/apis/roma-api/revisions/3dd91459b0fb?raw)