Skip to main content
Search Content
Performs vector-similarity search over project content (entities, comments, and chat messages) using AI embeddings. Returns the most semantically relevant results for the given query. Requires a paid plan with semantic search enabled. Authentication required. Send a user’s access token as Authorization: Bearer <token> — missing token → 401, invalid/expired token → 403 (refresh and retry). A service or master key is accepted too; such a request has no signed-in user, so the per-user filtering under What’s left out doesn’t apply to it.

Body Parameters

string
required
The natural language search query.
string[]
default:"[\"entity\", \"comment\", \"message\"]"
Content types to search. Any combination of entity, comment, message.
string
Restrict search to a specific space.
boolean
default:"false"
Only applies with a spaceId. When true, the search also includes every space nested under it — children, grandchildren, the whole subtree at any depth — not just the named space. Ignored without a spaceId.
string
Restrict message search to a specific conversation.
number
default:"20"
Maximum number of results to return. A whole number from 1 to 50, sent as a JSON number. A value outside that range is rejected with 400 search/invalid-body — a limit above 50 isn’t lowered to 50.

Query Parameters

Space-scoped reputation

This endpoint has a space in context, so it accepts the opt-in reputation params. They add a spaceReputation field to each result record’s populated user, alongside the always-present reputation total. Requires the reputation bundle. See the Reputation data model for the full contract.

Response

Returns an array of result objects ordered by similarity (highest first):
Each result includes:
  • sourceType — one of "entity", "comment", or "message", indicating which type of record was matched.
  • similarity — cosine similarity score between the query and the matched content.
  • record — the fully populated entity, comment, or chat message object. Entity records carry commentsCount. A record’s user is the author’s public User — no email or other private fields.

What’s left out

Comments their author deleted are never returned. Comments a moderator removed are never returned either — to anyone, including the removed comment’s author and requests made with a service or master key. Results are also filtered for the signed-in user (with the moderation bundle installed):
  • Content by users they are block-edged with, in either direction, is left out.
  • Comments on an entity whose author has blocked them are left out — their own comments there included.

Error Responses

The endpoint requires a user token or a service or master key. A missing token returns a bare 401; an invalid or expired token returns a bare 403 — refresh the access token and retry.
Returned when the body fails validation: query is missing or empty, limit isn’t a whole number from 1 to 50, sourceTypes contains a value other than entity, comment or message, spaceId or conversationId isn’t a UUID, or includeChildSpaces isn’t a boolean.