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

Permissions

Requires search.read. Without this scope the request returns 403 forbidden.

Parameters

Request Example

{
  "query": "release risks for the mobile launch",
  "page_size": 10,
  "score_threshold": 0.7
}

Response Example

{
  "object": "list",
  "results": [
    {
      "object": "search_result",
      "page_id": "11111111-1111-4111-8111-111111111111",
      "page_title": "Mobile Launch Plan",
      "score": 0.86,
      "snippet": "The mobile launch risk list includes app review timing and rollout coordination.",
      "url": "https://buildin.ai/11111111-1111-4111-8111-111111111111"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Behavior

• Results are ranked by semantic relevance and are capped in one response; this endpoint does not paginate.
• The endpoint searches content visible to the token.
• Supplying a different space_id is rejected; the endpoint never searches outside the token's workspace.
• 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: missing search.read.
• 429 rate_limited: too many requests.

Related Docs

Prerequisites

• Search Content
• Authentication and Scopes

Next Steps

• File Upload

References

• Conventions
• Error Codes