V2
Search Content
Search pages, databases, folders, and mind maps that the current token can access.
Search Content
Use Case
Use this endpoint when you need keyword search across content the current token can access. It returns normal pages and databases. Buildin page extensions such as folders and mind maps are returned as page objects with a more specific page_type.
Endpoint
| Item | Value |
|---|---|
| Method | POST |
| Path | /v2/search |
| Request body | JSON |
| Returns | list of page and database objects |
| Scope | search.read |
Permissions
Requires search.read. Without this scope the request returns 403 forbidden.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
query |
string | No | Search keyword. Omit or pass an empty value to avoid keyword filtering. |
filter |
object | No | Filter object. filter.property must be object. |
filter.value |
string | No | One of page, database, folder, or mind_map. |
sort.timestamp |
string | No | One of last_edited_time or created_time. |
sort.direction |
string | No | One of ascending or descending. |
start_cursor |
string | No | Pagination cursor. |
page_size |
number | No | Defaults to 20; maximum is 100. |
Request Example
{
"query": "project plan",
"filter": {
"property": "object",
"value": "page"
},
"sort": {
"timestamp": "last_edited_time",
"direction": "descending"
},
"start_cursor": null,
"page_size": 20
}
Response Example
{
"object": "list",
"results": [
{
"object": "page",
"id": "11111111-1111-4111-8111-111111111111",
"page_type": "page",
"created_time": "2026-04-09T08:00:00.000Z",
"last_edited_time": "2026-04-09T09:30:00.000Z",
"created_by": {
"object": "user",
"id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"
},
"last_edited_by": {
"object": "user",
"id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"
},
"parent": {
"type": "page_id",
"page_id": "55555555-5555-4555-8555-555555555555"
},
"in_trash": false,
"icon": null,
"cover": null,
"properties": {
"title": {
"id": "title",
"type": "title",
"title": [
{
"type": "text",
"text": {
"content": "Project Plan",
"link": null
},
"plain_text": "Project Plan",
"href": null
}
]
}
},
"url": "https://buildin.ai/docs/11111111-1111-4111-8111-111111111111"
},
{
"object": "database",
"id": "66666666-6666-4666-8666-666666666666",
"created_time": "2026-04-09T08:00:00.000Z",
"last_edited_time": "2026-04-09T09:30:00.000Z",
"created_by": {
"object": "user",
"id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"
},
"last_edited_by": {
"object": "user",
"id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"
},
"title": [
{
"type": "text",
"text": {
"content": "Task Board",
"link": null
},
"plain_text": "Task Board",
"href": null
}
],
"description": [],
"icon": null,
"cover": null,
"parent": {
"type": "page_id",
"page_id": "55555555-5555-4555-8555-555555555555"
},
"properties": {
"Name": {
"id": "title",
"type": "title",
"name": "Name"
},
"Status": {
"id": "16161616-1616-4616-8616-161616161616",
"type": "select",
"name": "Status"
}
},
"in_trash": false,
"is_inline": false,
"url": "https://buildin.ai/database/66666666-6666-4666-8666-666666666666"
}
],
"next_cursor": null,
"has_more": false
}
Behavior
filter.value = "page"returns page-like resources, including normal pages, folders, and mind maps.filter.value = "database"returns database objects only.filter.value = "folder"returns folder pages only.filter.value = "mind_map"returns mind map pages only.- Unsupported filters or sorts return an error instead of silently degrading.
Errors
400 validation_error: invalid request shape.400 unsupported_filter: unsupported filter.400 unsupported_sort: unsupported sort.401 unauthorized: invalid or expired token.403 forbidden: missing scope or inaccessible resource.