---
title: "Search notes (vector / keyword / hybrid)"
method: POST
path: "/api/search"
tags: ["Search"]
---

# Search notes (vector / keyword / hybrid)

`POST /api/search`

## Request

- Base URL: `https://api.engram.page`
- URL: `https://api.engram.page/api/search`
- Auth: HTTP bearer

Searches the current vault and returns one result per matching note (chunk hits are grouped by note, ranked by best chunk score). `mode` selects vector, keyword, or hybrid (default) retrieval, and results may be narrowed by `tags` or `folder`. Setting `cross_vault` searches across all of the user's vaults and requires the Pro plan (403 otherwise).

## Request body

- SearchRequest
  - `created_after` string, date-time: Only notes whose frontmatter created date is at or after this ISO 8601 instant.
  - `created_before` string, date-time: Only notes whose frontmatter created date is at or before this ISO 8601 instant.
  - `cross_vault` boolean: Pro plan only.
  - `diversity` number: Result diversity (MMR). 0 = most relevant (default, tuned per plan); 1 = most varied.
  - `folder` string
  - `limit` integer: 1..50, default 5
  - `mode` 'keyword' | 'vector' | 'hybrid'
  - `query` string, required
  - `tags` string[]
  - `type` string: Filter to notes whose frontmatter `type` equals this value (case-insensitive).
  - `updated_after` string, date-time: Only notes whose frontmatter timestamp is at or after this ISO 8601 instant.
  - `updated_before` string, date-time: Only notes whose frontmatter timestamp is at or before this ISO 8601 instant.

## Response `200`

Results

- SearchResponse
  - `results` SearchResult[], required
    - `folder` string, nullable
    - `heading_path` string, nullable
    - `id` string, uuid, nullable
    - `match_count` integer
    - `path` string
    - `score` number, float
    - `snippet` string
    - `title` string, nullable

## Other responses

- `403`: cross_vault requires Pro
- `422`: Missing query

---

[API](https://skmtc.dev/engram/apis/engram-api.md) · [All operations](https://skmtc.dev/engram/apis/engram-api/llms.txt) · [OpenAPI document](https://skmtc.dev/engram/apis/engram-api/revisions/8c4c2eec29dc?raw)