Similar events

Find semantically similar events to a canonical event.

GET/api/events/{date}/{event_id}/similar

Related NOSIBLE resources

research & data

Explore the NOSIBLE World interface, inspect the World data dictionary, and browse the classification ontologies used by World.

Authorizations

Bearer

Authorizationstringrequiredheader

Required Bearer API key. Programmatic access to the World API needs a key; browsing nosible.world in a browser does not.

Example: Bearer nos_sk_...

Parameters

query & path

datedaterequiredpath

Archive date in YYYY-MM-DD format.

Example: 2026-07-20

event_idstringrequiredpath

Canonical event identifier.

Example: 2026-07-20_en_US_v1_...

limitintegerquery

Maximum neighbors to return.

Example: 10

include_livebooleanquery

Include live-window neighbors when enabled.

Example: false

include_threadbooleanquery

Include stored story-thread predecessors.

Example: true

floornumberquery

Minimum similarity floor for HNSW neighbors.

Example: 0.35

How to use this endpoint

guidance

Use Similar Events to discover historical analogues and story threads. Similarity is a ranking signal, not a claim that two events are causally related. neighbors are computed against the archive-wide HNSW index; thread is the persisted backwards story chain.

Response body

application/json

These are the fields you can build against. Nested names use dot notation; optional sections are called out in their descriptions.

schemastring

Similar-events contract identifier.

Example: nosible_world_similar_events_v1

event_idstring

The anchor event used for retrieval.

Example: 2026-07-20_en_US_v1_...

datedate

Date of the anchor event.

Example: 2026-07-20

limitinteger

Applied neighbor cap.

Example: 10

min_similaritynumber

Similarity floor applied to neighbors.

Example: 0.35

neighborsobject[]

Nearest event neighbors ordered by similarity descending. Each result includes event identity, date, title, country, similarity, and retrieval source.

Example: [{ event_id, date, title, country, similarity, retrieval }]

threadobject[]

Stored story-chain predecessors, newest first, when include_thread is enabled.

Example: [{ event_id, date, title, similarity }]

errorsobject[]

Non-fatal retrieval-stage errors, such as a missing global HNSW index.

Example: []

floornumber

Effective similarity floor used by the neighbor search.

Example: 0.35

Responses and errors

HTTP

200Request succeeded. The response body is shown in the panel on the right.

400invalid_request — The date, filter, cursor, identifier, or request combination is invalid.

403access_denied — The requested archive date is outside the caller's World tier.

404not_found — The requested date, entity, ticker, or event does not exist in the accessible index.

410cursor_expired — The cursor was minted against a replaced index build. Restart pagination from the first page.

429rate_limited — The request exceeded the endpoint or account rate limit. Respect Retry-After when supplied.

501backend_not_configured — The World backend is not configured for this deployment.

502backend_error — The BFF could not obtain a valid response from the World backend.

504backend_timeout — The World backend or an upstream data source timed out.