Search

Semantic search across content, users, and spaces, plus streaming AI Q&A

The search module runs semantic (vector) search over your project’s content and powers a streaming, RAG-style question-answering endpoint.

These features require semantic search to be enabled for your project. See the Semantic Search & AI guide for setup.

The three search* functions return raw arrays of similarity-ranked results (not a PaginatedResponse); each element is { similarity, record }. askContent is different — it streams its answer (see below).

---

searchContent

Semantic search over content — entities, comments, and chat messages.

const results = await sublay.search.searchContent({
  query: "getting started guide",
  sourceTypes: ["entity", "comment"],
  spaceId: "spc_abc123",
  limit: 10,
});

for (const { sourceType, similarity, record } of results) {
  console.log(sourceType, similarity, record);
}

query · string · required

The search query string.

sourceTypes · ("entity" | "comment" | "message")[]

Which content types to search. Defaults to all.

spaceId · string

Scope the search to a specific space.

conversationId · string

Scope the search to a specific conversation.

limit · number

Maximum number of results to return.

spaceReputationId · string

Opts each result record’s author into a spaceReputation number. Accepts a space <uuid>, "none" (the project-general bucket), or "context" (the space derived from the request context). The empty string and the legacy general / null aliases are rejected. See Reputation.

spaceReputationDescendants · boolean

Only honored alongside an explicit space <uuid>. When true, spaceReputation is the subtree sum — the named space plus all of its descendants.

Returns — Promise<ContentSearchResult[]>, where each element is { sourceType: "entity" | "comment" | "message"; similarity: number; record: Entity | Comment | ChatMessage }.

---

searchUsers

Semantic search over the project’s users.

const results = await sublay.search.searchUsers({ query: "alice", limit: 10 });
// results: [{ similarity, record: User }, ...]

query · string · required

The search query string.

limit · number

Maximum number of results to return.

Returns — Promise<UserSearchResult[]>, where each element is { similarity: number; record: User }.

---

searchSpaces

Semantic search over the project’s spaces.

const results = await sublay.search.searchSpaces({ query: "photography", limit: 10 });
// results: [{ similarity, record: Space }, ...]

query · string · required

The search query string.

limit · number

Maximum number of results to return.

Returns — Promise<SpaceSearchResult[]>, where each element is { similarity: number; record: Space }.

---

askContent

Asks a natural-language question over your content and streams the answer back as it is generated. Unlike every other SDK function, askContent is an async generator over Server-Sent Events — you for await over it rather than awaiting a single result.

askContent streams via fetch rather than axios, so it does not get the automatic token-refresh-on-403 retry that other calls have. In SDK-managed mode, make sure a fresh access token is in place before starting a long stream.

const controller = new AbortController();

const stream = sublay.search.askContent({
  query: "What are the best practices for error handling?",
  spaceId: "spc_abc123",
  signal: controller.signal,
});

let answer = "";
let sources = [];

for await (const event of stream) {
  switch (event.type) {
    case "token":
      answer += event.content; // append streamed text
      break;
    case "sources":
      sources = event.sources; // ContentSearchResult[] the answer draws on
      break;
    case "done":
      break; // the stream is complete
    case "error":
      console.error(event.error);
      break;
  }
}

// Cancel early with controller.abort() — or simply `break` out of the loop.

query · string · required

The natural-language question to answer.

sourceTypes · ("entity" | "comment" | "message")[]

Which content types to draw from. Defaults to all.

spaceId · string

Scope the answer to content within a specific space.

conversationId · string

Scope the answer to a specific conversation.

limit · number

Maximum number of sources to draw from.

spaceReputationId · string

Opts each cited source record’s author into a spaceReputation number. Accepts a space <uuid>, "none" (the project-general bucket), or "context" (the space derived from the request context). The empty string and the legacy general / null aliases are rejected. See Reputation.

spaceReputationDescendants · boolean

Only honored alongside an explicit space <uuid>. When true, spaceReputation is the subtree sum — the named space plus all of its descendants.

signal · AbortSignal

Aborts the in-flight stream (e.g. when the user navigates away). You can also stop consuming by breaking out of the for await loop.

Returns — AsyncGenerator<AskContentEvent, void, unknown>. Each yielded event is one of:

type AskContentEvent =
  | { type: "token"; content: string }              // a chunk of answer text
  | { type: "sources"; sources: ContentSearchResult[] } // the cited sources
  | { type: "done" }                                 // stream finished
  | { type: "error"; error: string };                // a stream/server error

Completion and errors are signalled in-band as done / error events — the generator itself returns void and does not throw on a server-reported error.