Search notes (vector / keyword / hybrid)

POST

/search

curl --request POST \
  --url https://api.engram.page/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "diversity": 0.3, "limit": 5, "mode": "hybrid", "query": "omega-3 dosage", "type": "Playbook" }'

• Production

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).

Authorizations

• bearerAuth

Request Body^required

Search query

Media typeapplication/json

SearchRequest

object

created_after

Only notes whose frontmatter created date is at or after this ISO 8601 instant.

string format: date-time

created_before

Only notes whose frontmatter created date is at or before this ISO 8601 instant.

string format: date-time

cross_vault

Pro plan only.

boolean

diversity

Result diversity (MMR). 0 = most relevant (default, tuned per plan); 1 = most varied.

number

<= 1

folder

string

limit

1..50, default 5

integer

mode

string

Allowed values: keyword vector hybrid

query

required

string

tags

Array<string>

type

Filter to notes whose frontmatter type equals this value (case-insensitive).

string

updated_after

Only notes whose frontmatter timestamp is at or after this ISO 8601 instant.

string format: date-time

updated_before

Only notes whose frontmatter timestamp is at or before this ISO 8601 instant.

string format: date-time

Example

{
  "diversity": 0.3,
  "limit": 5,
  "mode": "hybrid",
  "query": "omega-3 dosage",
  "type": "Playbook"
}

Responses

200

Results

Media typeapplication/json

SearchResponse

object

results

required

Array<object>

SearchResult

object

folder

string

nullable

heading_path

string

nullable

id

string format: uuid

nullable

match_count

integer

path

string

score

number format: float

snippet

string

title

string

nullable

Example^generated

{
  "results": [
    {
      "folder": "example",
      "heading_path": "example",
      "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "match_count": 1,
      "path": "example",
      "score": 1,
      "snippet": "example",
      "title": "example"
    }
  ]
}

403

Cross_vault requires Pro

Media typeapplication/json

Error

object

errors

One of:

string

string

object

object

Example^generated

{
  "errors": {}
}

422

Missing query

Media typeapplication/json

Error

object

errors

One of:

string

string

object

object

Example^generated

{
  "errors": {}
}