Skip to main content
POST
SearchIntelHistory

Authorizations

X-WorldMonitor-Key
string
header
required

User-issued WorldMonitor API key.

Headers

Idempotency-Key
string

Optional client-generated idempotency key. Retrying a POST with the same key and an identical request body replays the original response (only the status, body, and Content-Type are reproduced) instead of re-executing; reusing the key with a different body is rejected with 422. For mutations this avoids duplicating the side effect, while for batch-read POSTs it replays a cached snapshot that can be up to 24 hours stale. Keys are scoped per authenticated caller (falling back to the source IP for unauthenticated endpoints) and retained for 24 hours.

Required string length: 1 - 255
Pattern: ^[\x21-\x7E]{1,255}$

Body

application/json

SearchIntelHistoryRequest asks for stored historical intelligence events semantically similar to a free-text query. The handler embeds query and runs a vector search over convex/intelHistory.ts; the optional filters narrow the candidate set before ranking.

query
string
required

Free-text search query, e.g. "artillery strikes near Kharkiv". Embedded with the same model and normalization the seed writer used, so query and stored vectors are comparable.

Required string length: 2 - 500
domain
string

Restrict to one producing domain. Empty searches every domain.

Pattern: ^(conflict|military|energy)?$
country
string

Restrict to one ISO 3166-1 alpha-2 country. Empty searches every country.

Pattern: ^([A-Z]{2})?$
from
integer<int64>

Earliest occurred_at to consider, Unix epoch milliseconds, inclusive. 0 or omitted means no lower bound.. Warning: Values > 2^53 may lose precision in JavaScript

Required range: x >= 0
to
integer<int64>

Latest occurred_at to consider, Unix epoch milliseconds, inclusive. 0 or omitted means no upper bound.. Warning: Values > 2^53 may lose precision in JavaScript

Required range: x >= 0
limit
integer<int32>

Maximum matches to return. Defaults to 20 server-side when omitted or <= 0; the handler caps it at 64, the SEARCH_MAX_LIMIT the Convex action clamps to (convex/intelHistory.ts).

Required range: 0 <= x <= 64

Response

Successful response

SearchIntelHistoryResponse returns the matching historical events, most similar first.

records
object[]
query
string

Echo of the search query, so a caller multiplexing requests can pair a response back to its input.

partial
boolean

True when a bounded candidate window may omit further matches.

upstreamUnavailable
boolean

True when the embedding provider or the history store could not be reached. The gateway reads this flag out of the body and switches the response to Cache-Control: no-store, so a transient outage is never pinned as a false-empty result for the tier's full TTL.