For a day

Find semantically related events inside one dated World archive slice.

POST/api/search/{date}/semantic

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

Body

application/json

querystringrequiredbody

Natural-language semantic query.

Example: AI chip supply constraints

limitintegerbody

Maximum events to return.

Example: 20

embedding_modelenumbody

Embedding model. The supported value is openai.

Example: openai

How to use this endpoint

guidance

Use semantic search for concept-level recall when exact keywords are too brittle. Keep the query focused and compare similarity scores across a consistent date and limit. The route returns the same lite event records used by day search, plus explicit HNSW score metadata.

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.

totalinteger

Number of semantic matches returned after the similarity floor for this request.

Example: 20

countinteger

Number of event records in this response.

Example: 20

limitinteger

Applied result cap.

Example: 20

offsetinteger

Applied offset; this route currently starts at zero.

Example: 0

eventsobject[]

Lite event records ranked by semantic similarity.

Example: [{ event_id, event, signals, coverage, _score, _hnsw_distance, _cosine_similarity }]

events[]._scorenumber

Rank-derived score, calculated as 1 / (rank + 1).

Example: 1

events[]._hnsw_distancenumber

Distance returned by the HNSW index. Lower is better.

Example: 0.13

events[]._cosine_similaritynumber

Cosine similarity derived from HNSW distance. Higher is better; the endpoint applies its configured floor.

Example: 0.87

facetsobject

Facet counts; currently an empty object for this route.

Example: {}

query_took_msinteger

Total request duration in milliseconds.

Example: 84

embedding_msinteger

Time spent creating the query embedding.

Example: 21

search_msinteger

Time spent searching the date HNSW index.

Example: 48

embedding_modelstring

Embedding model requested.

Example: openai

models_usedstring[]

Embedding models used to answer the request.

Example: ["openai"]

per_index_kinteger

Candidate count requested from the per-date index.

Example: 60

min_cosine_similaritynumber

Configured similarity floor applied before results are returned.

Example: 0.35

matched_tokensstring[]

Query token list echoed by the handler.

Example: ["AI infrastructure demand"]

errorsobject[]

Non-fatal errors reported by the semantic stage.

Example: []

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.