For all time

Search the dated event archive with metadata, lexical, semantic, or hybrid retrieval.

POST/api/search

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

Authorizationstringheader

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_...

Body

application/json

search_typeenumbody

metadata, lexical, semantic, or hybrid.

Example: hybrid

qstringbody

Text query. Used for lexical, semantic, and hybrid retrieval.

Example: oil supply disruption

dateobjectbody

Optional inclusive from/to window; include_live opts into newest slices. Set from explicitly for reproducible public-window queries.

Example: {"from":"2026-07-01","to":"2026-07-20","include_live":true}

filtersobjectbody

Filter DSL over entities, tickers, taxonomies, signals, and geography.

Example: {"gics_sector":"Energy"}

limitintegerbody

Number of events to return.

Example: 20

offsetintegerbody

Number of matching events to skip before returning the page.

Example: 0

vectornumber[]body

Caller-supplied embedding for semantic retrieval. Its length must match the configured HNSW dimension.

Example: [0.012, -0.004, ...]

query_vectornumber[]body

Alias for vector.

Example: [0.012, -0.004, ...]

sortobject[]body

Sort rules such as [{ by: 'total_coverage', desc: true }].

Example: [{"by":"total_coverage","desc":true}]

facetsstring[]body

Field names for which to return facet counts.

Example: ["country","sentiment"]

embedding_modelenumbody

Embedding model for semantic or hybrid retrieval. The supported value is openai.

Example: openai

semantic_filter_modeenumbody

Semantic filter strategy: auto, usearch, or exact.

Example: auto

max_datesintegerbody

Maximum archive dates the planner may visit.

Example: 30

explainbooleanbody

Include retrieval planning details where supported.

Example: false

querystringbody

Alias for q. Use one name consistently in a client; q is the canonical short form.

Example: oil supply disruption

includestring[]body

Projection controls such as event_lite, event_full, or explain. Use event_lite to keep payloads compact.

Example: ["event_lite"]

exact_vector_max_candidatesintegerbody

Maximum metadata-qualified candidates to score exactly when semantic_filter_mode is exact.

Example: 100000

semantic_candidatesintegerbody

Candidate budget for approximate semantic retrieval before hydration and reranking.

Example: 500

How to use this endpoint

guidance

Use global World Search when the question spans dates and you need metadata, lexical, semantic, or hybrid retrieval over event records. Keep the date window explicit in production so results are reproducible.

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

Stable global-search response schema identifier.

Example: nosible_world_search_v1

totalinteger

Total number of matching events before the current page is sliced.

Example: 1842

countinteger

Number of events returned in this page.

Example: 100

eventsobject[]

Event records for the route. The projection varies by endpoint: dated list/search routes return lite records, while global search and full-detail routes can include richer fields.

Example: [{ event_id, event, signals, ontology, coverage }]

facetsobject

Facet counts requested by the query, when facet fields are available.

Example: { "country": [{ "value": "US", "count": 38 }] }

date_windowobject

Effective date range and archive/live boundary used by the search.

Example: { "from": "2026-07-01", "to": "2026-07-20", "include_live": true, "archive_cutoff": "2026-07-20" }

search_typestring

Retrieval mode used for the request.

Example: hybrid

query_took_msnumber

End-to-end query duration in milliseconds.

Example: 184.2

embedding_msnumber

Time spent creating or loading a semantic query embedding.

Example: 31.4

search_msnumber

Time spent executing the indexed search after planning.

Example: 12.8

errorsobject[]

Non-fatal retrieval or hydration errors. An empty array means no such errors were reported.

Example: []

events[]._scorenumber

Overall retrieval score when the selected search mode ranks results.

Example: 0.9821

events[]._semantic_scorenumber

Semantic component of the retrieval score when available.

Example: 0.91

events[]._lexical_scorenumber

Lexical component of the retrieval score when available.

Example: 0.74

events[]._retrievalstring

Retrieval path used for the event.

Example: global_hnsw

events[]._search_datedate

Archive date from which the event record was hydrated.

Example: 2026-07-20

limitinteger

Applied page size.

Example: 100

offsetinteger

Applied result offset.

Example: 0

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.