For a day

Find semantically related events inside one dated World archive slice.

POST/api/v2.0/search/{date}/semantic

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

viewenumbody

The record each event is returned as: lite (the default), the event without its evidence, or full, the complete record. Any other value is a 422 validation_error. About records on Event details lists both.

Example: lite

include_vectorbooleanbody

true adds each event's embedding, oai_vector (3,072 values, comma-separated), to either view. Defaults to false.

Example: false

querystringrequiredbody

Natural-language semantic query. Required: a request without it is a 422 validation_error.

Example: AI chip supply constraints

limitintegerbody

Maximum events to return.

Example: 20

embedding_modelenumbody

Embedding model. The supported value is openai.

Example: openai

includestring[]body

Optional. ["event_full"] returns complete records, as view=full does.

Example: ["event_full"]

semantic_candidatesintegerbody

Candidate budget: the nearest events of the day retrieved from its vector index; total counts those at or above the 0.20 similarity floor. Defaults to 5,000, at most 10,000. It never changes with limit.

Example: 5000

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. It takes query (required), limit, embedding_model, semantic_candidates, view, include_vector and include, and nothing else: filters, sort, facets and offset are a 422 validation_error. For those, POST /api/v2.0/search with search_type semantic and a one-day date window.

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.

viewstring

The view the events are returned in: lite (the default) or full. See About records on Event details.

include_vectorboolean

true when the request asked for the embedding with include_vector=true; absent otherwise.

totalinteger

Events of the day at or above the 0.20 similarity floor among the semantic_candidates nearest to the query (5,000 unless sent): the same for any limit.

total_exactboolean

true when total counts every event of the day above the floor. false when the candidate budget filled with the last candidate still above the floor, so more may exist: send a larger semantic_candidates.

total_capped_atinteger

Only when total_exact is false: the candidate budget that capped total.

countinteger

Events in this response.

limitinteger

Result cap applied: 50 unless limit is sent.

offsetinteger

Always 0.

eventsobject[]

The events, as lite records unless view=full (About records on Event details lists both). A full record adds provenance, availability, triples, each ticker's why and v2_preview_success.

events[].event_idstring

Stable event identifier.

events[].versionstring

Event record version: "2.0-preview".

events[].eventobject

The event in its original language: date, language, title, description and points.

events[].event.datedate

World archive date of the event.

events[].event.languagestring

ISO 639-1 code of the event's original language.

events[].event.titlestring

Headline, in the original language.

events[].event.descriptionstring

Short narrative, in the original language.

events[].event.pointsstring[]

Key facts of the event, one sentence each.

events[].englishobject

The event in English: title, description and points, translated when the original language is not English.

events[].coverageobject

total_coverage, total_netlocs, coverage_concentration_index, first_seen, last_seen and most_seen, as in Event details.

events[].locationsobject[]

Places of the event, its own place first, then places named in it, as in Event details.

events[].signalsobject

Sentiment, materiality, time horizon and forward-looking signals with their class probabilities, as in Event details.

events[].tickersobject[]

Listed companies the event concerns, in the Event details format without why. Empty when has_tickers is false.

events[].has_tickersboolean

Whether tickers is non-empty.

events[].entitiesobject

Named entities by NER type, {TYPE: [{name, mention_count, confidence}]}, as in Event details.

events[].sentimentsobject

Entity-level sentiment grouped by entity type. Each item has name, sentiment_label (positive, neutral or negative), and sentiment_score, the final Percentage Margin Z-score.

events[].ontologiesobject[]

Classifications of the event, most probable first, as in Event details.

events[].oai_vectorstring

Only with include_vector=true: the event's 3,072-dimension embedding (text-embedding-3-large), comma-separated.

events[]._scorenumber

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

events[]._hnsw_distancenumber

Distance in the day's vector index; lower is closer.

events[]._cosine_similaritynumber

Cosine similarity to the query; higher is closer.

facetsobject

Always empty on this route.

query_took_msinteger

Total time in milliseconds.

embedding_msinteger

Time spent embedding the query.

search_msinteger

Time spent searching the day's index.

embedding_modelstring

Embedding model requested.

models_usedstring[]

Embedding models used.

per_index_kinteger

Candidates requested from the day's index: the candidate budget.

min_cosine_similaritynumber

Similarity floor applied.

matched_tokensstring[]

The query, echoed.

errorsobject[]

Non-fatal errors; empty when none.

Responses and errors

HTTP

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

400invalid_json — The request body is not JSON. Every error body, 401 included, is {error, message, status}.

401api_key_required — No API key was sent. Send it as Authorization: Bearer <key> or the api-key header.

401invalid_api_key — The API key is invalid or has been revoked.

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

422validation_error — The request is well formed but the API cannot decode or validate it: an unknown body field or query parameter, a missing required parameter, a value of the wrong type, an empty and, or or not, a date that is not a calendar date (in the path, the query or the body), an unknown enum value or a reversed range. The message names the parameter and what is wrong.

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.

503api_key_auth_unavailable — API key authentication is temporarily unavailable; retry shortly.

503api_key_metering_unavailable — API key usage metering is temporarily unavailable, so the request was not served; wait for the Retry-After header (30 seconds) and retry.

502backend_error — The World backend could not be reached or did not return a valid response; retry shortly.

504backend_timeout — The World backend did not answer within 300 seconds; narrow the request (for example with a date window) or retry.