Skip to main content
POST
Semantic search over tenant notes.

Authorizations

x-api-key
string
header
required

Body

application/json
query
string
required

Search query text.

active_opportunities_only
boolean
default:false

Restrict to notes associated with an open/active-stage opportunity. Combines with opportunity_uuids (intersection) when both are given, or applies tenant-wide when omitted.

end_date
string | null

ISO datetime upper bound on note creation date.

entity_type
enum<string> | null

Type of entity_uuid (PERSON/COMPANY/OPPORTUNITY). Must be paired with entity_uuid.

Available options:
PERSON,
COMPANY,
OPPORTUNITY
entity_uuid
string | null

Scope results to notes associated with this single entity. Must be paired with entity_type.

limit
integer
default:10

Max number of notes to return (1-200).

opportunity_uuids
string[] | null

Scope results to notes associated with any of these opportunities — use for asks spanning multiple opportunities at once, e.g. 'data-room concerns across all active opportunities this quarter'. At most 200 UUIDs.

search_mode
enum<string> | null

Controls how results are ranked. Defaults to 'recency' when omitted. Choose based on the user's intent:

  • 'recency': favours recent notes with a time-decay score boost. Use for: 'latest notes', 'recent conversations', 'what happened last week'.
  • 'historical': favours older notes. Use for: 'first meeting', 'earliest notes', 'how did we start with X'.
  • 'comprehensive': widens the candidate pool AND reranks results with a cross-encoder scored against each note's associated person/company context (job title, company description, mentions), not just raw note text — use for broad/ambiguous asks like 'give me everyone I've researched who fits this profile' or 'all notes mentioning Y'. Slower (~4-5s) and has a small per-request cost; every other mode stays on the fast, cheap path, so prefer this only for genuinely broad asks, not direct/precise lookups.
  • 'balanced': distributes results evenly across time. Use when a representative sample across full history is needed.
  • 'relevance': pure semantic match, no time factor. Use when recency is explicitly irrelevant.
Available options:
recency,
historical,
relevance,
comprehensive,
balanced
start_date
string | null

ISO datetime lower bound on note creation date.

Response

200 - application/json

Response body for notes semantic search.

query
string
required
results
NoteSearchResult · object[]
required
total
integer
required