Skip to main content
POST
GetSimilarEvents

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

GetSimilarEventsRequest asks "has anything like this happened before?".

Same vector search as SearchIntelHistory, different input: situation is a description of a developing situation rather than a search phrase, and the result set is deliberately small because it is read as a precedent list — by a human or an LLM — not scrolled.

situation
string
required

Free-text description of the situation to find precedents for, e.g. "a naval blockade closes a major grain export corridor for weeks". Longer than a search query on purpose: more context ranks better.

Required string length: 10 - 1000
domain
string

Restrict precedents to one producing domain. Empty searches every domain.

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

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

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

Maximum precedents to return. Defaults to 10 server-side when omitted or <= 0, capped at 32 by the handler.

Required range: 0 <= x <= 32

Response

Successful response

GetSimilarEventsResponse returns historical precedents for the described situation, most similar first.

records
object[]
situation
string

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

partial
boolean

True when a bounded candidate window may omit further precedents.

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 precedent list for the tier's full TTL.