V2
Semantic Search
Run natural-language vector search and return relevant page fragments.
Semantic Search
Use Case
Use this endpoint when natural-language meaning is more important than exact keyword matching. It returns content fragments from pages that are semantically relevant to the query.
Endpoint
| Item | Value |
|---|---|
| Method | POST |
| Path | /v2/search/semantic |
| Request body | JSON |
| Returns | list of semantic search results |
| Scope | search.read |
Permissions
Requires search.read. Without this scope the request returns 403 forbidden.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
query |
string | Yes | Natural-language query. |
page_size |
number | No | Defaults to 10; maximum depends on service limits. |
start_cursor |
string | No | Pagination cursor when returned by a previous response. |
Request Example
{
"query": "release risks for the mobile launch",
"page_size": 10,
"start_cursor": null
}
Response Example
{
"object": "list",
"results": [
{
"object": "semantic_search_result",
"page_id": "11111111-1111-4111-8111-111111111111",
"block_id": "44444444-4444-4444-8444-444444444444",
"score": 0.86,
"text": "The mobile launch risk list includes app review timing and rollout coordination."
}
],
"next_cursor": null,
"has_more": false
}
Behavior
- Results are ranked by semantic relevance.
- The endpoint searches content visible to the token.
- Use keyword search when you need exact object filtering by type.
- Result snippets are for discovery; fetch the page or block for authoritative structured data.
Errors
400 validation_error: missing or invalid query.401 unauthorized: invalid or expired token.403 forbidden: missingsearch.read.429 rate_limited: too many requests.