No results
Search failed
No results
Narrow your search with type:list, type:token, #tag…↑↓ to move · Enter to open · Esc to close

Search a list

Search a list for items that match a query. Only values indexed by searchable list indexes will be used when searching for items.

While any searchable index in the list is being built, searching is refused with INDEX_BUILDING, because results would be missing items. See index builds.

GET https://api.jsonpad.io/lists/{listId}/search

Example

cURL
12curl https://api.jsonpad.io/lists/c46fdecf-b65d-47b1-bcd5-3b0fc5c7de30/search?query=example \ -H "x-api-token: <YOUR TOKEN>"

Parameters

  • required
    listIdstringA list id or path name.
  • required
    querystringhttps://api.jsonpad.io/lists/91e97c85-8e03-47a5-acb8-b425c05593ee/search?query=exampleA search query.
  • optional
    includeItemsbooleanhttps://api.jsonpad.io/lists/e5bbdfec-cc6b-4e37-b763-c256b158d42c/search?includeItems=trueWhether items be included in the response or not. Can be true or false. If true, the response will include the items that match the query, otherwise we only include the item ids.
  • optional
    includeDatabooleanhttps://api.jsonpad.io/lists/e782a4f7-3b37-4d3e-8039-17aa050f97bd/search?includeData=trueWhether item data be included in the response or not. Can be true or false. Only used if includeItems is true.
  • optional
    includeGuardedboolean?includeGuarded=true

    Include values hidden by guard indexes in the response. Can be true or false.

    This only applies when the request is authenticated as an identity, and only to the items that identity owns. Without an identity, guarded values stay hidden.

    Defaults to false.

Request headers

  • required
    x-api-tokenstringYour API token.

Request body

No request body

Response body

200 OK

With includeItems set to false:

[
0: {
id: "b698f9a9-bef9-4dc1-9691-b074a1e53f98"
relevance: 0.878783155153293
}
]

With includeItems set to true:

[
0: {
item: {
id: "b698f9a9-bef9-4dc1-9691-b074a1e53f98"
createdAt: "2026-09-23T21:08:08.092Z"
updatedAt: "2026-09-23T21:08:08.092Z"
description: "This is a sample item"
tags: [
0: "my-app"
]
readonly: false
activated: true
locked: false
identity: {
id: "82e0c7c3-cfba-4d42-b3dc-c50b96b3da21"
displayName: "Sample Display Name"
}
dataSize: 13
}
relevance: 0.9264599059084143
}
]

With both includeItems and includeData set to true:

[
0: {
item: {
id: "b698f9a9-bef9-4dc1-9691-b074a1e53f98"
createdAt: "2026-09-23T21:08:08.092Z"
updatedAt: "2026-09-23T21:08:08.092Z"
description: "This is a sample item"
tags: [
0: "my-app"
]
data: {
test: 123
}
readonly: false
activated: true
locked: false
identity: {
id: "6844e576-1d7f-454c-a233-bb9a2fe8b293"
displayName: "Sample Display Name"
}
dataSize: 13
}
relevance: 0.509898850549622
}
]

Response headers

No response headers

2026-09-13