By ontology

Retrieve events classified into one ontology field and value, including ranked top-three matches.

GET/api/ontology/events

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

Parameters

query & path

fieldstringrequiredquery

Base ontology slot name, such as gics_sector.

Example: gics_sector

valuestringrequiredquery

Ontology class to retrieve.

Example: Energy

matchstringquery

top1 precision match or top3 recall match.

Example: top3

fromdatequery

Inclusive lower date bound in YYYY-MM-DD format.

Example: 2026-01-01

todatequery

Inclusive upper date bound in YYYY-MM-DD format.

Example: 2026-07-20

limitintegerquery

Page size.

Example: 100

cursorstringquery

Opaque cursor returned by the previous page.

Example: eyJ2Ijox...

orderenumquery

Event ordering, newest or oldest first.

Example: desc

includeenumquery

Projection selector: event_lite or event_full. This is a single query value, not an array.

Example: event_lite

include_vectorbooleanquery

Include stored event vectors when available and permitted.

Example: false

How to use this endpoint

guidance

Use ontology retrieval to turn a taxonomy class into a clean event universe. Choose top1 for precision; choose top3 when recall matters and you are comfortable with parent/child class overlap.

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 ontology retrieval contract identifier.

Example: nosible_world_ontology_events_v1

classificationobject

The base ontology field, class value, and top1/top3 match policy applied.

Example: { "field": "gics_sector", "value": "Energy", "match": "top3" }

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 }]

next_cursorstring | null

Opaque cursor for the next page. Send it back unchanged; null means the result set is exhausted.

Example: eyJ2Ijox...

orderstring

Applied event order, newest or oldest first.

Example: desc

date_windowobject

Effective date range and archive cutoff.

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

hydration_missesinteger

Events that could not be hydrated into the requested projection.

Example: 0

as_ofobject

Index build and archive freshness markers.

Example: { "index_build": "world-v1.2", "archive_cutoff": "2026-07-01" }

took_msnumber

Ontology query duration in milliseconds.

Example: 31

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 belongs to a replaced index build; restart 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.

404unknown_ontology_value — The field/value combination is valid but the requested class has no indexed match; check the schema or resolve the class again.

400cursor_filter_mismatch — The cursor was created for a different ontology field, value, or match mode.