Sign in

v2

latestOpenAPI 3.1.0Proprietary2026-07-26127193620.1 KB
Search

Semantic search across received and sent mail

Ranked search across both received and sent mail. The mode field selects the ranking strategy:

  • keyword: lexical full-text matching only (no embeddings).
  • semantic: meaning-based matching using vector embeddings.
  • hybrid (default): blends the semantic and keyword signals.

Results are ordered by a relevance score. Every row reports the fields it matched (matched_fields), a match-centered excerpt per field (snippets), and a score_breakdown whose components account for the score. Page through results by passing the prior response's meta.cursor back as cursor.

Requires the Pro plan and the semantic_search_enabled entitlement; callers without them receive 403.

Host routing: this operation is served only by the search host (https://api.primitive.dev/v1). The typed SDKs route it there automatically.

post/semantic-search

Headers

Idempotency-Keystring

Optional client-supplied idempotency key. Retrying a request with the same key returns the original result instead of performing the action a second time; if omitted the server derives one from the canonical payload hash. Safe to retry network failures without duplicating side effects.

Request body

querystring

Free-text query. Required for semantic and hybrid modes; optional for keyword mode.

mode'hybrid' | 'semantic' | 'keyword'

Ranking strategy. keyword is lexical only, semantic is embedding-based, hybrid blends both.

corpusstring[]

Which mail to search. Defaults to both received (inbound) and sent (outbound).

search_instring[]

Restrict matching to these fields. Defaults to all.

excludestring[]

Exclude these fields from matching.

date_fromstring date-time

Only include mail at or after this timestamp.

date_tostring date-time

Only include mail at or before this timestamp.

includestring[]

Opt-in extras. coverage adds an index-coverage snapshot to meta. Matched fields, snippets, and the score breakdown are always returned regardless of this field.

limitinteger

Maximum number of results to return.

cursorstring

Opaque pagination cursor from a prior response's meta.cursor.

Response

Ranked search results

successtrue required