{ "openapi": "3.0.3", "info": { "title": "NOSIBLE World V1.2 API", "version": "1.2", "description": "Public World V1.2 API contract. Examples illustrate responses and do not require optional fields to be present. Existing API URLs remain supported." }, "servers": [ { "url": "https://nosible.world" } ], "externalDocs": { "url": "https://docs.nosible.com/" }, "paths": { "/api/events/{date}": { "get": { "operationId": "world_events", "summary": "By day", "description": "List the events in a dated World archive slice with sorting and pagination.\n\nUse Events for a date-scoped snapshot when you want deterministic ordering and pagination rather than relevance ranking.", "tags": [ "EVENT LISTS" ], "externalDocs": { "description": "Interactive reference", "url": "https://docs.nosible.com/endpoints/world-events" }, "x-nosible-reference-pages": [ "world-events" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "date", "in": "path", "required": true, "description": "Archive date in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date", "description": "Archive date in YYYY-MM-DD format.", "example": "2026-07-20" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "description": "Page size.", "example": 100 } }, { "name": "sort_by", "in": "query", "required": false, "description": "total_coverage, total_netlocs, or event_id.", "schema": { "type": "string", "description": "total_coverage, total_netlocs, or event_id.", "example": "total_coverage" } }, { "name": "desc", "in": "query", "required": false, "description": "Sort descending when true.", "schema": { "type": "boolean", "description": "Sort descending when true.", "example": true } }, { "name": "offset", "in": "query", "required": false, "description": "Number of events to skip.", "schema": { "type": "integer", "description": "Number of events to skip.", "example": 0 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total events available for the date before pagination." }, "count": { "type": "integer", "description": "Number of events in this page." }, "limit": { "type": "integer", "description": "Applied page size." }, "offset": { "type": "integer", "description": "Applied offset." }, "sort_by": { "type": "string", "description": "Effective ordering key. Supported aliases include total_coverage, total_netlocs/n_sources, event_id, and materiality_then_coverage." }, "desc": { "type": "boolean", "description": "Whether the applied sort is descending." }, "events": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Lite event records for the date. Fetch event detail for the complete record." } }, "additionalProperties": true }, "example": { "total": 7418, "count": 100, "limit": 100, "offset": 0, "sort_by": "total_coverage", "desc": true, "events": [ { "event_id": "2026-07-20_en_US_v1_...", "event": { "title": "..." }, "coverage": { "total_netlocs": 42 } } ] } } } }, "400": { "description": "invalid_request: The date, filter, cursor, identifier, or request combination is invalid.", "x-nosible-error-codes": [ "invalid_request" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "api_key_required: No API key was sent. Send it as Authorization: Bearer or the api-key header.\n\ninvalid_api_key: The API key is invalid or has been revoked.", "x-nosible-error-codes": [ "api_key_required", "invalid_api_key" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "access_denied: The requested archive date is outside the caller's World tier.", "x-nosible-error-codes": [ "access_denied" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "not_found: The requested date, entity, ticker, or event does not exist in the accessible index.", "x-nosible-error-codes": [ "not_found" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "cursor_expired: The cursor was minted against a replaced index build. Restart pagination from the first page.", "x-nosible-error-codes": [ "cursor_expired" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "validation_error: A body field has the wrong type or form, such as a limit sent as a string; the message names it.", "x-nosible-error-codes": [ "validation_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "rate_limited: The request exceeded the endpoint or account rate limit. Respect Retry-After when supplied.", "x-nosible-error-codes": [ "rate_limited" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "501": { "description": "backend_not_configured: The World backend is not configured for this deployment.", "x-nosible-error-codes": [ "backend_not_configured" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "502": { "description": "backend_error: The World backend could not be reached or did not return a valid response; retry shortly.", "x-nosible-error-codes": [ "backend_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "api_key_auth_unavailable: API key authentication is temporarily unavailable; retry shortly.\n\napi_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.", "x-nosible-error-codes": [ "api_key_auth_unavailable", "api_key_metering_unavailable" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "504": { "description": "backend_timeout: The World backend did not answer within 300 seconds; narrow the request (for example with a date window) or retry.", "x-nosible-error-codes": [ "backend_timeout" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/entities/events": { "get": { "operationId": "world_entity_events", "summary": "By entity", "description": "Retrieve cursor-paged events that mention one canonical entity across any date window.\n\nUse this route to build a company or person timeline. Resolve the canonical name first, then page with the opaque cursor; do not infer a cursor from dates or offsets. Store the as_of markers with research results.", "tags": [ "EVENT LISTS" ], "externalDocs": { "description": "Interactive reference", "url": "https://docs.nosible.com/endpoints/world-entity-events" }, "x-nosible-reference-pages": [ "world-entity-events" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "type", "in": "query", "required": true, "description": "NER type, or ANY to merge all indexed entity types.", "schema": { "type": "string", "description": "NER type, or ANY to merge all indexed entity types.", "example": "ORG" } }, { "name": "name", "in": "query", "required": true, "description": "Canonical display name returned by /resolve.", "schema": { "type": "string", "description": "Canonical display name returned by /resolve.", "example": "Nvidia" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size. Defaults to 50, maximum 500.", "schema": { "type": "integer", "description": "Page size. Defaults to 50, maximum 500.", "example": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous response.", "schema": { "type": "string", "description": "Opaque cursor returned by the previous response.", "example": "eyJ2Ijox..." } }, { "name": "from", "in": "query", "required": false, "description": "Inclusive lower date bound in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date", "description": "Inclusive lower date bound in YYYY-MM-DD format.", "example": "2026-01-01" } }, { "name": "to", "in": "query", "required": false, "description": "Inclusive upper date bound in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date", "description": "Inclusive upper date bound in YYYY-MM-DD format.", "example": "2026-07-20" } }, { "name": "order", "in": "query", "required": false, "description": "Event ordering, newest or oldest first.", "schema": { "type": "string", "description": "Event ordering, newest or oldest first.", "example": "desc" } }, { "name": "include", "in": "query", "required": false, "description": "Projection selector: event_lite or event_full. This is a single query value, not an array.", "schema": { "type": "string", "description": "Projection selector: event_lite or event_full. This is a single query value, not an array.", "example": "event_lite" } }, { "name": "include_vector", "in": "query", "required": false, "description": "Include the event embedding when the caller's tier and the selected projection allow it.", "schema": { "type": "boolean", "description": "Include the event embedding when the caller's tier and the selected projection allow it.", "example": false } }, { "name": "include_live", "in": "query", "required": false, "description": "Include the newest live slices when enabled for the deployment.", "schema": { "type": "boolean", "description": "Include the newest live slices when enabled for the deployment.", "example": true } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema": { "type": "string", "description": "Stable entity timeline contract identifier." }, "entity": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "normalized": { "type": "string" } }, "additionalProperties": true, "description": "Canonical entity type, display name, and normalized lookup form." }, "total": { "type": "integer", "description": "Total number of matching events before the current page is sliced." }, "count": { "type": "integer", "description": "Number of events returned in this page." }, "order": { "type": "string", "description": "Applied event order, newest or oldest first." }, "events": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "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." }, "next_cursor": { "type": "string", "nullable": true, "description": "Opaque cursor for the next page. Send it back unchanged; null means the result set is exhausted." }, "date_window": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "archive_cutoff": { "type": "string" }, "include_live": { "type": "boolean" } }, "additionalProperties": true, "description": "Effective date window, indexed last date, archive cutoff, and live-overlay decision." }, "took_ms": { "type": "number", "description": "Timeline query duration in milliseconds." }, "live_events": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Ephemeral live-overlay events when include_live is enabled; they are not included in total or cursor pagination." }, "hydration_misses": { "type": "integer", "description": "Number of events that could not be hydrated into the requested projection." }, "as_of": { "type": "object", "additionalProperties": true, "description": "Index build and archive freshness markers for reproducible downstream analysis." } }, "additionalProperties": true }, "example": { "schema": "nosible_world_entity_events_v1", "entity": { "type": "ORG", "name": "Nvidia", "normalized": "nvidia" }, "total": 48213, "count": 50, "order": "desc", "events": [ { "event_id": "2026-07-20_en_US_v1_..." } ], "next_cursor": "eyJ2Ijox...", "date_window": { "from": "2026-01-01", "to": "2026-07-20", "archive_cutoff": "2026-07-20", "include_live": false }, "took_ms": 59 } } } }, "400": { "description": "invalid_request: The date, filter, cursor, identifier, or request combination is invalid.", "x-nosible-error-codes": [ "invalid_request" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "api_key_required: No API key was sent. Send it as Authorization: Bearer or the api-key header.\n\ninvalid_api_key: The API key is invalid or has been revoked.", "x-nosible-error-codes": [ "api_key_required", "invalid_api_key" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "access_denied: The requested archive date is outside the caller's World tier.", "x-nosible-error-codes": [ "access_denied" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "not_found: The requested date, entity, ticker, or event does not exist in the accessible index.\n\nunknown_entity: The requested entity is not present in the index.", "x-nosible-error-codes": [ "not_found", "unknown_entity" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "cursor_expired: The cursor belongs to a replaced index build; restart from the first page.", "x-nosible-error-codes": [ "cursor_expired" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "validation_error: A body field has the wrong type or form, such as a limit sent as a string; the message names it.", "x-nosible-error-codes": [ "validation_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "rate_limited: The request exceeded the endpoint or account rate limit. Respect Retry-After when supplied.", "x-nosible-error-codes": [ "rate_limited" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "501": { "description": "backend_not_configured: The World backend is not configured for this deployment.", "x-nosible-error-codes": [ "backend_not_configured" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "502": { "description": "backend_error: The World backend could not be reached or did not return a valid response; retry shortly.", "x-nosible-error-codes": [ "backend_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "api_key_auth_unavailable: API key authentication is temporarily unavailable; retry shortly.\n\napi_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.", "x-nosible-error-codes": [ "api_key_auth_unavailable", "api_key_metering_unavailable" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "504": { "description": "backend_timeout: The World backend did not answer within 300 seconds; narrow the request (for example with a date window) or retry.", "x-nosible-error-codes": [ "backend_timeout" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/tickers/{symbol}/events": { "get": { "operationId": "world_ticker_events", "summary": "By ticker", "description": "Retrieve the event timeline for a ticker or alternate security identifier.\n\nUse this route when the security identifier is the natural key for your model. Prefer the canonical symbol from Resolve; id_type lets you query by ISIN, FIGI, LEI, or Wikidata QID when that is what your security master contains.", "tags": [ "EVENT LISTS" ], "externalDocs": { "description": "Interactive reference", "url": "https://docs.nosible.com/endpoints/world-ticker-events" }, "x-nosible-reference-pages": [ "world-ticker-events" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Canonical symbol returned by Resolve, for example NVDA.", "schema": { "type": "string", "description": "Canonical symbol returned by Resolve, for example NVDA.", "example": "NVDA" } }, { "name": "id_type", "in": "query", "required": false, "description": "symbol, isin, figi, lei, or qid.", "schema": { "type": "string", "description": "symbol, isin, figi, lei, or qid.", "example": "symbol" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size. Use a bounded page size for predictable payloads.", "schema": { "type": "integer", "description": "Page size. Use a bounded page size for predictable payloads.", "example": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "description": "Opaque cursor returned by the previous page.", "example": "eyJ2Ijox..." } }, { "name": "order", "in": "query", "required": false, "description": "Event ordering, newest or oldest first.", "schema": { "type": "string", "description": "Event ordering, newest or oldest first.", "example": "desc" } }, { "name": "include", "in": "query", "required": false, "description": "Projection selector: event_lite or event_full. This is a single query value, not an array.", "schema": { "type": "string", "description": "Projection selector: event_lite or event_full. This is a single query value, not an array.", "example": "event_lite" } }, { "name": "include_vector", "in": "query", "required": false, "description": "Include stored event vectors when available and permitted.", "schema": { "type": "boolean", "description": "Include stored event vectors when available and permitted.", "example": false } }, { "name": "include_live", "in": "query", "required": false, "description": "Include the newest live slices when enabled for the deployment.", "schema": { "type": "boolean", "description": "Include the newest live slices when enabled for the deployment.", "example": true } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema": { "type": "string", "description": "Stable ticker timeline contract identifier." }, "ticker": { "type": "object", "properties": { "symbol": { "type": "string" }, "id_type": { "type": "string" }, "normalized": { "type": "string" } }, "additionalProperties": true, "description": "Resolved symbol, identifier type, and normalized lookup value." }, "total": { "type": "integer", "description": "Total number of matching events before the current page is sliced." }, "count": { "type": "integer", "description": "Number of events returned in this page." }, "order": { "type": "string", "description": "Applied event order, newest or oldest first." }, "events": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "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." }, "next_cursor": { "type": "string", "nullable": true, "description": "Opaque cursor for the next page. Send it back unchanged; null means the result set is exhausted." }, "date_window": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "archive_cutoff": { "type": "string" }, "include_live": { "type": "boolean" } }, "additionalProperties": true, "description": "Effective date range and archive/live boundary." }, "live_events": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Ephemeral page-one live overlay when requested." }, "hydration_misses": { "type": "integer", "description": "Events that could not be hydrated into the requested projection." }, "as_of": { "type": "object", "properties": { "archive_cutoff": { "type": "string" } }, "additionalProperties": true, "description": "Index build and archive freshness markers." }, "took_ms": { "type": "number", "description": "Timeline query duration in milliseconds." } }, "additionalProperties": true }, "example": { "schema": "nosible_world_ticker_events_v1", "ticker": { "symbol": "NVDA", "id_type": "symbol", "normalized": "nvda" }, "total": 14901, "count": 50, "order": "desc", "events": [ { "event_id": "2026-07-20_en_US_v1_..." } ], "next_cursor": null, "date_window": { "from": "2026-01-01", "to": "2026-07-20", "archive_cutoff": "2026-07-20", "include_live": false }, "live_events": [], "hydration_misses": 0, "as_of": { "archive_cutoff": "2026-07-20" }, "took_ms": 42 } } } }, "400": { "description": "invalid_request: The date, filter, cursor, identifier, or request combination is invalid.", "x-nosible-error-codes": [ "invalid_request" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "api_key_required: No API key was sent. Send it as Authorization: Bearer or the api-key header.\n\ninvalid_api_key: The API key is invalid or has been revoked.", "x-nosible-error-codes": [ "api_key_required", "invalid_api_key" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "access_denied: The requested archive date is outside the caller's World tier.", "x-nosible-error-codes": [ "access_denied" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "not_found: The requested date, entity, ticker, or event does not exist in the accessible index.\n\nunknown_ticker: The requested symbol or identifier does not resolve to an indexed security.", "x-nosible-error-codes": [ "not_found", "unknown_ticker" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "cursor_expired: The cursor belongs to a replaced index build; restart from the first page.", "x-nosible-error-codes": [ "cursor_expired" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "validation_error: A body field has the wrong type or form, such as a limit sent as a string; the message names it.", "x-nosible-error-codes": [ "validation_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "rate_limited: The request exceeded the endpoint or account rate limit. Respect Retry-After when supplied.", "x-nosible-error-codes": [ "rate_limited" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "501": { "description": "backend_not_configured: The World backend is not configured for this deployment.", "x-nosible-error-codes": [ "backend_not_configured" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "502": { "description": "backend_error: The World backend could not be reached or did not return a valid response; retry shortly.", "x-nosible-error-codes": [ "backend_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "api_key_auth_unavailable: API key authentication is temporarily unavailable; retry shortly.\n\napi_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.", "x-nosible-error-codes": [ "api_key_auth_unavailable", "api_key_metering_unavailable" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "504": { "description": "backend_timeout: The World backend did not answer within 300 seconds; narrow the request (for example with a date window) or retry.", "x-nosible-error-codes": [ "backend_timeout" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/ontology/events": { "get": { "operationId": "world_ontology_events", "summary": "By ontology", "description": "Retrieve events classified into one ontology field and value, including ranked top-three matches.\n\nUse 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.", "tags": [ "EVENT LISTS" ], "externalDocs": { "description": "Interactive reference", "url": "https://docs.nosible.com/endpoints/world-ontology-events" }, "x-nosible-reference-pages": [ "world-ontology-events" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "field", "in": "query", "required": true, "description": "Base ontology slot name, such as gics_sector.", "schema": { "type": "string", "description": "Base ontology slot name, such as gics_sector.", "example": "gics_sector" } }, { "name": "value", "in": "query", "required": true, "description": "Ontology class to retrieve.", "schema": { "type": "string", "description": "Ontology class to retrieve.", "example": "Energy" } }, { "name": "match", "in": "query", "required": false, "description": "top1 precision match or top3 recall match.", "schema": { "type": "string", "description": "top1 precision match or top3 recall match.", "example": "top3" } }, { "name": "from", "in": "query", "required": false, "description": "Inclusive lower date bound in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date", "description": "Inclusive lower date bound in YYYY-MM-DD format.", "example": "2026-01-01" } }, { "name": "to", "in": "query", "required": false, "description": "Inclusive upper date bound in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date", "description": "Inclusive upper date bound in YYYY-MM-DD format.", "example": "2026-07-20" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "description": "Page size.", "example": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string", "description": "Opaque cursor returned by the previous page.", "example": "eyJ2Ijox..." } }, { "name": "order", "in": "query", "required": false, "description": "Event ordering, newest or oldest first.", "schema": { "type": "string", "description": "Event ordering, newest or oldest first.", "example": "desc" } }, { "name": "include", "in": "query", "required": false, "description": "Projection selector: event_lite or event_full. This is a single query value, not an array.", "schema": { "type": "string", "description": "Projection selector: event_lite or event_full. This is a single query value, not an array.", "example": "event_lite" } }, { "name": "include_vector", "in": "query", "required": false, "description": "Include stored event vectors when available and permitted.", "schema": { "type": "boolean", "description": "Include stored event vectors when available and permitted.", "example": false } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema": { "type": "string", "description": "Stable ontology retrieval contract identifier." }, "classification": { "type": "object", "properties": { "field": { "type": "string" }, "value": { "type": "string" }, "match": { "type": "string" } }, "additionalProperties": true, "description": "The base ontology field, class value, and top1/top3 match policy applied." }, "total": { "type": "integer", "description": "Total number of matching events before the current page is sliced." }, "count": { "type": "integer", "description": "Number of events returned in this page." }, "events": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "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." }, "next_cursor": { "type": "string", "nullable": true, "description": "Opaque cursor for the next page. Send it back unchanged; null means the result set is exhausted." }, "date_window": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "archive_cutoff": { "type": "string" } }, "additionalProperties": true, "description": "Effective date range and archive cutoff." }, "hydration_misses": { "type": "integer", "description": "Events that could not be hydrated into the requested projection." }, "as_of": { "type": "object", "properties": { "archive_cutoff": { "type": "string" } }, "additionalProperties": true, "description": "Index build and archive freshness markers." }, "took_ms": { "type": "number", "description": "Ontology query duration in milliseconds." }, "order": { "type": "string", "description": "Applied event order, newest or oldest first." } }, "additionalProperties": true }, "example": { "schema": "nosible_world_ontology_events_v1", "classification": { "field": "gics_sector", "value": "Energy", "match": "top3" }, "total": 192041, "count": 100, "events": [ { "event_id": "2026-07-20_en_US_v1_..." } ], "next_cursor": "eyJ2Ijox...", "date_window": { "from": "2026-01-01", "to": "2026-07-20", "archive_cutoff": "2026-07-20" }, "hydration_misses": 0, "as_of": { "archive_cutoff": "2026-07-01" }, "took_ms": 31 } } } }, "400": { "description": "invalid_request: The date, filter, cursor, identifier, or request combination is invalid.\n\ncursor_filter_mismatch: The cursor was created for a different ontology field, value, or match mode.", "x-nosible-error-codes": [ "invalid_request", "cursor_filter_mismatch" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "api_key_required: No API key was sent. Send it as Authorization: Bearer or the api-key header.\n\ninvalid_api_key: The API key is invalid or has been revoked.", "x-nosible-error-codes": [ "api_key_required", "invalid_api_key" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "access_denied: The requested archive date is outside the caller's World tier.", "x-nosible-error-codes": [ "access_denied" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "not_found: The requested date, entity, ticker, or event does not exist in the accessible index.\n\nunknown_ontology_value: The field/value combination is valid but the requested class has no indexed match; check the schema or resolve the class again.", "x-nosible-error-codes": [ "not_found", "unknown_ontology_value" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "cursor_expired: The cursor belongs to a replaced index build; restart from the first page.", "x-nosible-error-codes": [ "cursor_expired" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "validation_error: A body field has the wrong type or form, such as a limit sent as a string; the message names it.", "x-nosible-error-codes": [ "validation_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "rate_limited: The request exceeded the endpoint or account rate limit. Respect Retry-After when supplied.", "x-nosible-error-codes": [ "rate_limited" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "501": { "description": "backend_not_configured: The World backend is not configured for this deployment.", "x-nosible-error-codes": [ "backend_not_configured" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "502": { "description": "backend_error: The World backend could not be reached or did not return a valid response; retry shortly.", "x-nosible-error-codes": [ "backend_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "api_key_auth_unavailable: API key authentication is temporarily unavailable; retry shortly.\n\napi_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.", "x-nosible-error-codes": [ "api_key_auth_unavailable", "api_key_metering_unavailable" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "504": { "description": "backend_timeout: The World backend did not answer within 300 seconds; narrow the request (for example with a date window) or retry.", "x-nosible-error-codes": [ "backend_timeout" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/search/{date}/semantic": { "post": { "operationId": "world_semantic_search", "summary": "For a day", "description": "Find semantically related events inside one dated World archive slice.\n\nUse 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.", "tags": [ "EVENT SEARCH" ], "externalDocs": { "description": "Interactive reference", "url": "https://docs.nosible.com/endpoints/world-semantic-search" }, "x-nosible-reference-pages": [ "world-semantic-search" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "date", "in": "path", "required": true, "description": "Archive date in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date", "description": "Archive date in YYYY-MM-DD format.", "example": "2026-07-20" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "description": "Number of semantic matches returned after the similarity floor for this request." }, "count": { "type": "integer", "description": "Number of event records in this response." }, "limit": { "type": "integer", "description": "Applied result cap." }, "offset": { "type": "integer", "description": "Applied offset; this route currently starts at zero." }, "events": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "_score": { "type": "number", "description": "Rank-derived score, calculated as 1 / (rank + 1)." }, "_hnsw_distance": { "type": "number", "description": "Distance returned by the HNSW index. Lower is better." }, "_cosine_similarity": { "type": "number", "description": "Cosine similarity derived from HNSW distance. Higher is better; the endpoint applies its configured floor." } } }, "description": "Lite event records ranked by semantic similarity." }, "facets": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Facet counts; currently an empty object for this route." }, "query_took_ms": { "type": "integer", "description": "Total request duration in milliseconds." }, "embedding_ms": { "type": "integer", "description": "Time spent creating the query embedding." }, "search_ms": { "type": "integer", "description": "Time spent searching the date HNSW index." }, "embedding_model": { "type": "string", "description": "Embedding model requested." }, "models_used": { "type": "array", "items": { "type": "string" }, "description": "Embedding models used to answer the request." }, "per_index_k": { "type": "integer", "description": "Candidate count requested from the per-date index." }, "min_cosine_similarity": { "type": "number", "description": "Configured similarity floor applied before results are returned." }, "matched_tokens": { "type": "array", "items": { "type": "string" }, "description": "Query token list echoed by the handler." }, "errors": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Non-fatal errors reported by the semantic stage." } }, "additionalProperties": true }, "example": { "total": 2, "count": 2, "limit": 20, "offset": 0, "events": [ { "event_id": "2026-07-20_en_US_v1_...", "_score": 1, "_hnsw_distance": 0.13, "_cosine_similarity": 0.87 } ], "facets": {}, "query_took_ms": 84, "embedding_ms": 21, "search_ms": 48, "embedding_model": "openai", "models_used": [ "openai" ], "per_index_k": 60, "min_cosine_similarity": 0.35, "matched_tokens": [ "AI infrastructure demand" ], "errors": [] } } } }, "400": { "description": "invalid_request: The date, filter, cursor, identifier, or request combination is invalid.", "x-nosible-error-codes": [ "invalid_request" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "api_key_required: No API key was sent. Send it as Authorization: Bearer or the api-key header.\n\ninvalid_api_key: The API key is invalid or has been revoked.", "x-nosible-error-codes": [ "api_key_required", "invalid_api_key" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "access_denied: The requested archive date is outside the caller's World tier.", "x-nosible-error-codes": [ "access_denied" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "not_found: The requested date, entity, ticker, or event does not exist in the accessible index.", "x-nosible-error-codes": [ "not_found" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "cursor_expired: The cursor was minted against a replaced index build. Restart pagination from the first page.", "x-nosible-error-codes": [ "cursor_expired" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "validation_error: A body field has the wrong type or form, such as a limit sent as a string; the message names it.", "x-nosible-error-codes": [ "validation_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "rate_limited: The request exceeded the endpoint or account rate limit. Respect Retry-After when supplied.", "x-nosible-error-codes": [ "rate_limited" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "501": { "description": "backend_not_configured: The World backend is not configured for this deployment.", "x-nosible-error-codes": [ "backend_not_configured" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "502": { "description": "backend_error: The World backend could not be reached or did not return a valid response; retry shortly.", "x-nosible-error-codes": [ "backend_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "api_key_auth_unavailable: API key authentication is temporarily unavailable; retry shortly.\n\napi_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.", "x-nosible-error-codes": [ "api_key_auth_unavailable", "api_key_metering_unavailable" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "504": { "description": "backend_timeout: The World backend did not answer within 300 seconds; narrow the request (for example with a date window) or retry.", "x-nosible-error-codes": [ "backend_timeout" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Natural-language semantic query.", "example": "AI chip supply constraints" }, "limit": { "type": "integer", "description": "Maximum events to return.", "example": 20 }, "embedding_model": { "type": "string", "description": "Embedding model. The supported value is openai.", "example": "openai" } }, "additionalProperties": true, "required": [ "query" ] }, "examples": { "world_semantic_search": { "summary": "For a day", "value": { "query": "AI chip supply constraints" } } } } } } } }, "/api/search": { "post": { "operationId": "world_search", "summary": "Search events (all time or grouped by date)", "description": "Search the dated event archive with metadata, lexical, semantic, or hybrid retrieval.\n\nUse 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.\n\nFor a date range\n\nRetrieve bounded semantic results grouped by date, with an optional live overlay for the newest slices.\n\nUse this endpoint when a semantic definition must be evaluated independently across dates. Request the factor projection and set date.include_live=true when the newest active slices should be included.", "tags": [ "EVENT SEARCH" ], "externalDocs": { "description": "Interactive reference", "url": "https://docs.nosible.com/endpoints/world-search" }, "x-nosible-reference-pages": [ "world-search", "world-grouped-search" ], "security": [ { "BearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "schema": { "type": "string", "description": "Stable global-search response schema identifier." }, "total": { "type": "integer", "description": "Total number of matching events before the current page is sliced." }, "count": { "type": "integer", "description": "Number of events returned in this page." }, "limit": { "type": "integer", "description": "Applied page size." }, "offset": { "type": "integer", "description": "Applied result offset." }, "events": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "_score": { "type": "number", "description": "Overall retrieval score when the selected search mode ranks results." }, "_semantic_score": { "type": "number", "description": "Semantic component of the retrieval score when available." }, "_lexical_score": { "type": "number", "description": "Lexical component of the retrieval score when available." }, "_retrieval": { "type": "string", "description": "Retrieval path used for the event." }, "_search_date": { "type": "string", "format": "date", "description": "Archive date from which the event record was hydrated." } } }, "description": "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." }, "facets": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Facet counts requested by the query, when facet fields are available." }, "search_type": { "type": "string", "description": "Retrieval mode used for the request." }, "query_took_ms": { "type": "number", "description": "End-to-end query duration in milliseconds." }, "embedding_ms": { "type": "number", "description": "Time spent creating or loading a semantic query embedding." }, "search_ms": { "type": "number", "description": "Time spent executing the indexed search after planning." }, "date_window": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "archive_cutoff": { "type": "string" } }, "additionalProperties": true, "description": "Effective date range and archive/live boundary used by the search." }, "errors": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Non-fatal retrieval or hydration errors. An empty array means no such errors were reported." } }, "additionalProperties": true }, { "type": "object", "properties": { "schema": { "type": "string", "description": "Stable grouped semantic search response contract identifier." }, "revision": { "type": "number" }, "search_type": { "type": "string" }, "group_by": { "type": "string", "description": "Grouping dimension; currently date." }, "vector_aggregate": { "type": "string" }, "per_date_limit": { "type": "number" }, "min_score": { "type": "number" }, "total": { "type": "number" }, "candidate_events": { "type": "number" }, "events": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Flat matched event rows; join them to groups by date." }, "groups": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "One summary per scanned date, including matches, candidates, truncation, and eligible denominators." }, "date_window": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "include_live": { "type": "boolean" }, "archive_cutoff": { "type": "string" } }, "additionalProperties": true, "description": "Requested window, live-slice decision, and archive cutoff." }, "stats": { "type": "object", "properties": { "dates_requested": { "type": "number" }, "dates_scanned": { "type": "number" }, "matched_events": { "type": "number" }, "truncated": { "type": "boolean" } }, "additionalProperties": true, "description": "Aggregate date, candidate, match, and truncation counters." } }, "additionalProperties": true } ] }, "examples": { "allTime": { "value": { "schema": "nosible_world_search_response_v1", "total": 1842, "count": 50, "limit": 50, "offset": 0, "events": [ { "event_id": "2026-07-20_en_US_v1_...", "_score": 0.9821, "_retrieval": "global_hnsw", "_search_date": "2026-07-20" } ], "facets": {}, "search_type": "hybrid", "query_took_ms": 184.2, "embedding_ms": 31.4, "search_ms": 12.8, "date_window": { "from": "2026-07-01", "to": "2026-07-20", "archive_cutoff": "2026-07-20" }, "errors": [] } }, "byDate": { "value": { "schema": "nosible_world_factor_search_v1", "revision": 3, "search_type": "semantic", "group_by": "date", "vector_aggregate": "max", "per_date_limit": 1000, "min_score": 0.35, "total": 412, "candidate_events": 30140, "events": [ { "date": "2026-09-17", "event_id": "2026-09-17_en_US_v1_...", "score": 0.4812, "vector_scores": [ 0.4812 ], "sentiment": "negative" } ], "groups": [ { "date": "2026-09-17", "matched_count": 12, "candidate_count": 991, "truncated": true } ], "date_window": { "from": "2026-09-15", "to": "2026-09-17", "include_live": true, "archive_cutoff": "2026-09-15" }, "stats": { "dates_requested": 3, "dates_scanned": 3, "matched_events": 412, "truncated": true } } } } } } }, "400": { "description": "invalid_request: The date, filter, cursor, identifier, or request combination is invalid.\n\ninvalid_request: The grouped request is invalid or omits required date, vector, or projection fields.", "x-nosible-error-codes": [ "invalid_request" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "api_key_required: No API key was sent. Send it as Authorization: Bearer or the api-key header.\n\ninvalid_api_key: The API key is invalid or has been revoked.\n\napi_key_required: No API key was sent. Send it as Authorization: Bearer or the api-key header.\n\ninvalid_api_key: The API key is invalid or has been revoked.", "x-nosible-error-codes": [ "api_key_required", "invalid_api_key" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "access_denied: The requested archive date is outside the caller's World tier.\n\naccess_denied: The requested archive date is outside the caller's World tier.", "x-nosible-error-codes": [ "access_denied" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "not_found: The requested date, entity, ticker, or event does not exist in the accessible index.\n\nnot_found: The requested date, entity, ticker, or event does not exist in the accessible index.", "x-nosible-error-codes": [ "not_found" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "cursor_expired: The cursor was minted against a replaced index build. Restart pagination from the first page.\n\ncursor_expired: The cursor was minted against a replaced index build. Restart pagination from the first page.", "x-nosible-error-codes": [ "cursor_expired" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "validation_error: A body field has the wrong type or form, such as a limit sent as a string; the message names it.\n\nvalidation_error: A body field has the wrong type or form, such as a limit sent as a string; the message names it.\n\ngrouped_response_too_large: The request exceeds the bounded grouped response budget; shorten the window or raise the score floor.\n\narchive_date_gap: The window includes days the archive has no data for; the message names them and the days either side. Missing days are never shown as zero activity: choose a window that avoids them.", "x-nosible-error-codes": [ "validation_error", "grouped_response_too_large", "archive_date_gap" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "rate_limited: The request exceeded the endpoint or account rate limit. Respect Retry-After when supplied.\n\nrate_limited: The request exceeded the endpoint or account rate limit. Respect Retry-After when supplied.", "x-nosible-error-codes": [ "rate_limited" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "501": { "description": "backend_not_configured: The World backend is not configured for this deployment.\n\nbackend_not_configured: The World backend is not configured for this deployment.", "x-nosible-error-codes": [ "backend_not_configured" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "502": { "description": "backend_error: The World backend could not be reached or did not return a valid response; retry shortly.\n\nbackend_error: The World backend could not be reached or did not return a valid response; retry shortly.", "x-nosible-error-codes": [ "backend_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "api_key_auth_unavailable: API key authentication is temporarily unavailable; retry shortly.\n\napi_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.\n\napi_key_auth_unavailable: API key authentication is temporarily unavailable; retry shortly.\n\napi_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.\n\ngrouped_search_busy: The grouped-search worker pool is full; retry after backoff.", "x-nosible-error-codes": [ "api_key_auth_unavailable", "api_key_metering_unavailable", "grouped_search_busy" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "504": { "description": "backend_timeout: The World backend did not answer within 300 seconds; narrow the request (for example with a date window) or retry.\n\nbackend_timeout: The World backend did not answer within 300 seconds; narrow the request (for example with a date window) or retry.", "x-nosible-error-codes": [ "backend_timeout" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "search_type": { "type": "string", "description": "metadata, lexical, semantic, or hybrid.", "example": "hybrid" }, "q": { "type": "string", "description": "Text query. Used for lexical, semantic, and hybrid retrieval.", "example": "oil supply disruption" }, "date": { "type": "object", "additionalProperties": true, "description": "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 } }, "filters": { "type": "object", "additionalProperties": true, "description": "Filter DSL over entities, tickers, taxonomies, signals, and geography.", "example": { "gics_sector": "Energy" } }, "limit": { "type": "integer", "description": "Number of events to return.", "example": 20 }, "offset": { "type": "integer", "description": "Number of matching events to skip before returning the page.", "example": 0 }, "vector": { "type": "array", "items": { "type": "number" }, "description": "Caller-supplied embedding for semantic retrieval. Its length must match the configured HNSW dimension." }, "query_vector": { "type": "array", "items": { "type": "number" }, "description": "Alias for vector." }, "sort": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Sort rules such as [{ by: 'total_coverage', desc: true }].", "example": [ { "by": "total_coverage", "desc": true } ] }, "facets": { "type": "array", "items": { "type": "string" }, "description": "Field names for which to return facet counts.", "example": [ "country", "sentiment" ] }, "embedding_model": { "type": "string", "description": "Embedding model for semantic or hybrid retrieval. The supported value is openai.", "example": "openai" }, "semantic_filter_mode": { "type": "string", "description": "Semantic filter strategy: auto, usearch, or exact.", "example": "auto" }, "max_dates": { "type": "integer", "description": "Maximum archive dates the planner may visit.", "example": 30 }, "explain": { "type": "boolean", "description": "Include retrieval planning details where supported.", "example": false }, "query": { "type": "string", "description": "Alias for q. Use one name consistently in a client; q is the canonical short form.", "example": "oil supply disruption" }, "include": { "type": "array", "items": { "type": "string" }, "description": "Projection controls such as event_lite, event_full, or explain. Use event_lite to keep payloads compact.", "example": [ "event_lite" ] }, "exact_vector_max_candidates": { "type": "integer", "description": "Maximum metadata-qualified candidates to score exactly when semantic_filter_mode is exact.", "example": 100000 }, "semantic_candidates": { "type": "integer", "description": "Candidate budget for approximate semantic retrieval before hydration and reranking.", "example": 500 } }, "additionalProperties": true }, { "type": "object", "properties": { "group_by": { "type": "string", "description": "Grouping dimension; currently date.", "example": "date", "enum": [ "date" ] }, "vectors": { "type": "array", "items": { "type": "array", "items": { "type": "number" } }, "description": "One or more anchor embeddings. Each production vector must contain exactly 3,072 floating-point values." }, "date": { "type": "object", "additionalProperties": true, "description": "Inclusive date window. Set include_live=true to include newest active slices.", "example": { "from": "2026-09-15", "to": "2026-09-17", "include_live": true } }, "filters": { "type": "object", "additionalProperties": true, "description": "The World Search filter DSL.", "example": { "language": "en" } }, "include": { "type": "array", "items": { "type": "string" }, "description": "Projection selector; include factor for the grouped factor response.", "example": [ "factor" ] }, "per_date_limit": { "type": "integer", "description": "Candidate retrieval budget for each date; defaults to 1000.", "example": 1000 }, "min_score": { "type": "number", "description": "Inclusive semantic score floor; defaults to 0.2.", "example": 0.35 } }, "additionalProperties": true, "required": [ "group_by", "vectors", "date", "include" ] } ] }, "examples": { "world_search": { "summary": "For all time", "value": { "search_type": "hybrid", "q": "oil supply disruption", "date": { "from": "2026-09-20", "to": "2026-09-26" }, "limit": 20 } }, "world_grouped_search": { "summary": "For a date range", "value": { "group_by": "date", "vectors": [ [ 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ] ], "date": { "from": "2026-09-20", "to": "2026-09-21" }, "include": [ "factor" ], "min_score": 0.35 } } } } } } } }, "/api/event-trends": { "post": { "operationId": "world_event_trends", "summary": "Create Event Trend", "description": "Aggregate semantic event matches into a compact, dense time series on the server.\n\nUse Event Trend for a semantic signal over time without downloading the matching events. Buckets are stable under wider date ranges because retrieval uses fixed calendar-quarter partitions. Treat truncated buckets as lower bounds.", "tags": [ "EVENT TRENDS" ], "externalDocs": { "description": "Interactive reference", "url": "https://docs.nosible.com/endpoints/world-event-trends" }, "x-nosible-reference-pages": [ "world-event-trends" ], "security": [ { "BearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Short-lived handle for bucket drill-down." }, "approximate": { "type": "boolean", "description": "Always true because semantic candidate retrieval is bounded." }, "buckets": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "start": { "type": "string", "format": "date", "description": "Inclusive bucket start date." }, "event_count": { "type": "integer", "description": "Retained semantic matches in the bucket." }, "coverage_sum": { "type": "integer", "description": "Sum of distinct-source coverage across retained events." }, "similarity_sum": { "type": "number", "description": "Sum of exact semantic similarities across retained events." }, "truncated": { "type": "boolean", "description": "True when the quarter candidate budget filled and more matches may exist." }, "groups": { "type": "object", "additionalProperties": true, "description": "Optional group-value metrics." } } }, "description": "Dense chronological time-series buckets." } }, "additionalProperties": true }, "example": { "id": "tr_4a45c76c941f482e", "approximate": true, "buckets": [ { "start": "2026-06-01", "event_count": 184, "coverage_sum": 612, "similarity_sum": 123.84, "truncated": false, "groups": { "negative": { "event_count": 91, "coverage_sum": 318, "similarity_sum": 62.17 } } } ] } } } }, "400": { "description": "invalid_request: The date, filter, cursor, identifier, or request combination is invalid.", "x-nosible-error-codes": [ "invalid_request" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "api_key_required: No API key was sent. Send it as Authorization: Bearer or the api-key header.\n\ninvalid_api_key: The API key is invalid or has been revoked.", "x-nosible-error-codes": [ "api_key_required", "invalid_api_key" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "access_denied: The requested archive date is outside the caller's World tier.", "x-nosible-error-codes": [ "access_denied" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "not_found: The requested date, entity, ticker, or event does not exist in the accessible index.", "x-nosible-error-codes": [ "not_found" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "cursor_expired: The cursor was minted against a replaced index build. Restart pagination from the first page.", "x-nosible-error-codes": [ "cursor_expired" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "validation_error: A body field has the wrong type or form, such as a limit sent as a string; the message names it.", "x-nosible-error-codes": [ "validation_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "rate_limited: The request exceeded the endpoint or account rate limit. Respect Retry-After when supplied.", "x-nosible-error-codes": [ "rate_limited" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "501": { "description": "backend_not_configured: The World backend is not configured for this deployment.", "x-nosible-error-codes": [ "backend_not_configured" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "502": { "description": "backend_error: The World backend could not be reached or did not return a valid response; retry shortly.", "x-nosible-error-codes": [ "backend_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "api_key_auth_unavailable: API key authentication is temporarily unavailable; retry shortly.\n\napi_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.", "x-nosible-error-codes": [ "api_key_auth_unavailable", "api_key_metering_unavailable" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "504": { "description": "backend_timeout: The World backend did not answer within 300 seconds; narrow the request (for example with a date window) or retry.", "x-nosible-error-codes": [ "backend_timeout" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Semantic topic definition.", "example": "openai lawsuits" }, "from": { "type": "string", "format": "date", "description": "Inclusive UTC start date.", "example": "2026-06-01" }, "to": { "type": "string", "format": "date", "description": "Exclusive UTC end date.", "example": "2026-09-01" }, "interval": { "type": "string", "description": "day, week, month, or quarter.", "example": "month" }, "min_similarity": { "type": "number", "description": "Inclusive exact-cosine threshold; defaults to 0.35.", "example": 0.35 }, "filters": { "type": "object", "additionalProperties": true, "description": "World Search filter DSL.", "example": {} }, "group_by": { "type": "string", "description": "Optional single categorical split such as sentiment or country.", "example": "sentiment" } }, "additionalProperties": true, "required": [ "query", "from", "to" ] }, "examples": { "world_event_trends": { "summary": "Create Event Trend", "value": { "query": "openai lawsuits", "from": "2026-06-01", "to": "2026-09-01", "interval": "month", "group_by": "sentiment" } } } } } } } }, "/api/event-trends/{id}/events": { "get": { "operationId": "world_event_trend_events", "summary": "Get Events in Trend", "description": "Page through the event evidence behind one recent Event Trend bucket.\n\nUse this route immediately after Event Trend to inspect evidence for a bucket or one group. The handle is short-lived; restart the trend request if it expires.", "tags": [ "EVENT TRENDS" ], "externalDocs": { "description": "Interactive reference", "url": "https://docs.nosible.com/endpoints/world-event-trend-events" }, "x-nosible-reference-pages": [ "world-event-trend-events" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Trend result ID returned by Event Trend.", "schema": { "type": "string", "description": "Trend result ID returned by Event Trend.", "example": "tr_4a45c76c941f482e" } }, { "name": "bucket", "in": "query", "required": true, "description": "Bucket start date returned by Event Trend.", "schema": { "type": "string", "format": "date", "description": "Bucket start date returned by Event Trend.", "example": "2026-06-01" } }, { "name": "group", "in": "query", "required": false, "description": "Optional group value to inspect.", "schema": { "type": "string", "description": "Optional group value to inspect.", "example": "negative" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, up to 200.", "schema": { "type": "integer", "description": "Page size, up to 200.", "example": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque next-page cursor.", "schema": { "type": "string", "description": "Opaque next-page cursor.", "example": "AAAAAAAAADI" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "description": "Events retained for the selected bucket and optional group." }, "count": { "type": "integer", "description": "Events returned in this page." }, "limit": { "type": "integer", "description": "Applied page size." }, "events": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Lite event records with semantic retrieval metadata." }, "next_cursor": { "type": "string", "nullable": true, "description": "Opaque next-page cursor." } }, "additionalProperties": true }, "example": { "total": 91, "count": 50, "limit": 50, "events": [ { "event_id": "2026-06-18_en_US_v1_...", "_semantic_score": 0.78 } ], "next_cursor": "AAAAAAAAADI" } } } }, "400": { "description": "invalid_request: The date, filter, cursor, identifier, or request combination is invalid.", "x-nosible-error-codes": [ "invalid_request" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "api_key_required: No API key was sent. Send it as Authorization: Bearer or the api-key header.\n\ninvalid_api_key: The API key is invalid or has been revoked.", "x-nosible-error-codes": [ "api_key_required", "invalid_api_key" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "access_denied: The requested archive date is outside the caller's World tier.", "x-nosible-error-codes": [ "access_denied" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "not_found: The requested date, entity, ticker, or event does not exist in the accessible index.", "x-nosible-error-codes": [ "not_found" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "cursor_expired: The cursor was minted against a replaced index build. Restart pagination from the first page.", "x-nosible-error-codes": [ "cursor_expired" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "validation_error: A body field has the wrong type or form, such as a limit sent as a string; the message names it.", "x-nosible-error-codes": [ "validation_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "rate_limited: The request exceeded the endpoint or account rate limit. Respect Retry-After when supplied.", "x-nosible-error-codes": [ "rate_limited" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "501": { "description": "backend_not_configured: The World backend is not configured for this deployment.", "x-nosible-error-codes": [ "backend_not_configured" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "502": { "description": "backend_error: The World backend could not be reached or did not return a valid response; retry shortly.", "x-nosible-error-codes": [ "backend_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "api_key_auth_unavailable: API key authentication is temporarily unavailable; retry shortly.\n\napi_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.", "x-nosible-error-codes": [ "api_key_auth_unavailable", "api_key_metering_unavailable" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "504": { "description": "backend_timeout: The World backend did not answer within 300 seconds; narrow the request (for example with a date window) or retry.", "x-nosible-error-codes": [ "backend_timeout" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/events/{date}/{event_id}": { "get": { "operationId": "world_event_detail", "summary": "Event details", "description": "Retrieve one event with classifications, entities, coverage, and source evidence.\n\nFetch event detail after discovery. The detail record is the source of truth for a factual claim: it includes the narrative, classifications, entities, coverage counters, and canonical event identity.", "tags": [ "EVENT DETAILS" ], "externalDocs": { "description": "Interactive reference", "url": "https://docs.nosible.com/endpoints/world-event-detail" }, "x-nosible-reference-pages": [ "world-event-detail" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "date", "in": "path", "required": true, "description": "Archive date in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date", "description": "Archive date in YYYY-MM-DD format.", "example": "2026-07-20" } }, { "name": "event_id", "in": "path", "required": true, "description": "Canonical event identifier.", "schema": { "type": "string", "description": "Canonical event identifier.", "example": "2026-07-20_en_US_v1_..." } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorldEvent" }, "example": { "event_id": "2026-07-20_en_US_v1_...", "event": { "date": "2026-07-20", "title": "NVIDIA reports record data center demand", "description": "..." }, "signals": { "sentiment": "positive", "materiality": "high", "time_horizon": "months" }, "coverage": { "total_coverage": 238, "total_netlocs": 61 }, "entities": { "ORG": [ "NVIDIA" ] } } } } }, "400": { "description": "invalid_request: The date, filter, cursor, identifier, or request combination is invalid.", "x-nosible-error-codes": [ "invalid_request" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "api_key_required: No API key was sent. Send it as Authorization: Bearer or the api-key header.\n\ninvalid_api_key: The API key is invalid or has been revoked.", "x-nosible-error-codes": [ "api_key_required", "invalid_api_key" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "access_denied: The requested archive date is outside the caller's World tier.", "x-nosible-error-codes": [ "access_denied" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "not_found: The requested date, entity, ticker, or event does not exist in the accessible index.", "x-nosible-error-codes": [ "not_found" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "cursor_expired: The cursor was minted against a replaced index build. Restart pagination from the first page.", "x-nosible-error-codes": [ "cursor_expired" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "validation_error: A body field has the wrong type or form, such as a limit sent as a string; the message names it.", "x-nosible-error-codes": [ "validation_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "rate_limited: The request exceeded the endpoint or account rate limit. Respect Retry-After when supplied.", "x-nosible-error-codes": [ "rate_limited" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "501": { "description": "backend_not_configured: The World backend is not configured for this deployment.", "x-nosible-error-codes": [ "backend_not_configured" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "502": { "description": "backend_error: The World backend could not be reached or did not return a valid response; retry shortly.", "x-nosible-error-codes": [ "backend_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "api_key_auth_unavailable: API key authentication is temporarily unavailable; retry shortly.\n\napi_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.", "x-nosible-error-codes": [ "api_key_auth_unavailable", "api_key_metering_unavailable" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "504": { "description": "backend_timeout: The World backend did not answer within 300 seconds; narrow the request (for example with a date window) or retry.", "x-nosible-error-codes": [ "backend_timeout" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/events/{date}/{event_id}/similar": { "get": { "operationId": "world_event_similar", "summary": "Similar events", "description": "Find semantically similar events to a canonical event.\n\nUse 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 reserved for a stored backwards story chain; the current archive stores none, so it is empty.", "tags": [ "EVENT DETAILS" ], "externalDocs": { "description": "Interactive reference", "url": "https://docs.nosible.com/endpoints/world-event-similar" }, "x-nosible-reference-pages": [ "world-event-similar" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "date", "in": "path", "required": true, "description": "Archive date in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date", "description": "Archive date in YYYY-MM-DD format.", "example": "2026-07-20" } }, { "name": "event_id", "in": "path", "required": true, "description": "Canonical event identifier.", "schema": { "type": "string", "description": "Canonical event identifier.", "example": "2026-07-20_en_US_v1_..." } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum neighbors to return.", "schema": { "type": "integer", "description": "Maximum neighbors to return.", "example": 10 } }, { "name": "include_live", "in": "query", "required": false, "description": "Also search the live days after the archive cutoff. Defaults to false.", "schema": { "type": "boolean", "description": "Also search the live days after the archive cutoff. Defaults to false.", "example": false } }, { "name": "include_thread", "in": "query", "required": false, "description": "Include stored story-thread predecessors (none are stored in the current archive).", "schema": { "type": "boolean", "description": "Include stored story-thread predecessors (none are stored in the current archive).", "example": true } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema": { "type": "string", "description": "Similar-events contract identifier." }, "event_id": { "type": "string", "description": "The anchor event used for retrieval." }, "date": { "type": "string", "format": "date", "description": "Date of the anchor event." }, "limit": { "type": "integer", "description": "Applied neighbor cap." }, "min_similarity": { "type": "number", "description": "Similarity floor applied to neighbors." }, "neighbors": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Nearest event neighbors ordered by similarity descending. Each result includes event identity, date, title, country, similarity, and retrieval source." }, "thread": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Stored story-chain predecessors, newest first, when include_thread is enabled. The current archive stores no story chains, so it is empty: use neighbors." }, "errors": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Non-fatal retrieval-stage errors, such as a missing global HNSW index." }, "floor": { "type": "string", "format": "date", "description": "Earliest date a neighbor may have: the start of the archive your key can read. Set by NOSIBLE, not by the request." } }, "additionalProperties": true }, "example": { "schema": "nosible_world_similar_events_v1", "event_id": "2026-07-20_en_US_v1_...", "date": "2026-07-20", "limit": 10, "min_similarity": 0.35, "neighbors": [ { "event_id": "2026-07-18_en_US_v1_...", "title": "...", "country": "United States", "similarity": 0.91, "retrieval": "archive_hnsw" } ], "thread": [], "errors": [] } } } }, "400": { "description": "invalid_request: The date, filter, cursor, identifier, or request combination is invalid.", "x-nosible-error-codes": [ "invalid_request" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "api_key_required: No API key was sent. Send it as Authorization: Bearer or the api-key header.\n\ninvalid_api_key: The API key is invalid or has been revoked.", "x-nosible-error-codes": [ "api_key_required", "invalid_api_key" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "access_denied: The requested archive date is outside the caller's World tier.", "x-nosible-error-codes": [ "access_denied" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "not_found: The requested date, entity, ticker, or event does not exist in the accessible index.", "x-nosible-error-codes": [ "not_found" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "cursor_expired: The cursor was minted against a replaced index build. Restart pagination from the first page.", "x-nosible-error-codes": [ "cursor_expired" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "validation_error: A body field has the wrong type or form, such as a limit sent as a string; the message names it.", "x-nosible-error-codes": [ "validation_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "rate_limited: The request exceeded the endpoint or account rate limit. Respect Retry-After when supplied.", "x-nosible-error-codes": [ "rate_limited" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "501": { "description": "backend_not_configured: The World backend is not configured for this deployment.", "x-nosible-error-codes": [ "backend_not_configured" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "502": { "description": "backend_error: The World backend could not be reached or did not return a valid response; retry shortly.", "x-nosible-error-codes": [ "backend_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "api_key_auth_unavailable: API key authentication is temporarily unavailable; retry shortly.\n\napi_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.", "x-nosible-error-codes": [ "api_key_auth_unavailable", "api_key_metering_unavailable" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "504": { "description": "backend_timeout: The World backend did not answer within 300 seconds; narrow the request (for example with a date window) or retry.", "x-nosible-error-codes": [ "backend_timeout" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/resolve": { "get": { "operationId": "world_resolve", "summary": "Find entities", "description": "Find the canonical entity or security identifier before retrieving its event timeline.\n\nResolve first, retrieve second. The returned canonical spelling and identifier are the safe inputs for the entity and ticker routes; guessing a display name can produce a 404 even when the entity exists. For a security master, keep the identifiers block rather than trying to normalize symbols yourself.", "tags": [ "HELPERS" ], "externalDocs": { "description": "Interactive reference", "url": "https://docs.nosible.com/endpoints/world-resolve" }, "x-nosible-reference-pages": [ "world-resolve" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Entity, company, ticker, or identifier to resolve.", "schema": { "type": "string", "description": "Entity, company, ticker, or identifier to resolve.", "example": "nvidia" } }, { "name": "types", "in": "query", "required": false, "description": "Comma-separated entity types or TICKER.", "schema": { "type": "string", "description": "Comma-separated entity types or TICKER.", "example": "ORG,TICKER" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of candidates. Defaults to 10, maximum 50.", "schema": { "type": "integer", "description": "Maximum number of candidates. Defaults to 10, maximum 50.", "example": 3 } }, { "name": "min_events", "in": "query", "required": false, "description": "Drop candidates with fewer than this many indexed events. Useful for avoiding one-off name collisions.", "schema": { "type": "integer", "description": "Drop candidates with fewer than this many indexed events. Useful for avoiding one-off name collisions.", "example": 25 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema": { "type": "string", "description": "Stable resolver contract identifier." }, "q": { "type": "string", "description": "The original lookup query." }, "count": { "type": "integer", "description": "Number of candidates returned." }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "kind": { "type": "string", "description": "Candidate family: entity or ticker." }, "type": { "type": "string", "description": "NER type present on entity candidates." }, "ticker": { "type": "string", "description": "Canonical security symbol present on ticker candidates." }, "name": { "type": "string", "description": "Canonical entity or issuer display name." }, "match": { "type": "string", "description": "Match quality, such as exact or fuzzy." }, "score": { "type": "number", "description": "Resolver ranking score." }, "total_events": { "type": "integer", "description": "Indexed event count for the candidate." }, "first_date": { "type": "string", "format": "date", "description": "Earliest indexed event date for the candidate when available." }, "last_date": { "type": "string", "format": "date", "description": "Latest indexed event date for the candidate when available." }, "identifiers": { "type": "object", "additionalProperties": true, "description": "Alternate security identifiers when the candidate is a ticker." }, "events_url": { "type": "string", "description": "Canonical follow-up URL for the selected candidate." }, "filter": { "type": "object", "additionalProperties": true, "description": "Ready-to-use filter expression for POST /api/search." }, "profile": { "type": "object", "additionalProperties": true, "description": "The same indexed identity and date-range fields returned by the corresponding profile endpoint." }, "metadata": { "type": "object", "additionalProperties": true, "description": "The same observed event metadata returned by the corresponding profile endpoint." }, "reference": { "type": "object", "additionalProperties": true, "description": "CompanyV4 reference metadata on ticker candidates, when available." } } }, "description": "Ranked entity and ticker candidates. Candidate fields vary by kind; use the selected candidate's name or ticker, filter, or events_url in the next request." }, "as_of": { "type": "object", "properties": { "archive_cutoff": { "type": "string" } }, "additionalProperties": true, "description": "Index build and archive cutoff used for the lookup." }, "took_ms": { "type": "number", "description": "Resolver duration in milliseconds." } }, "additionalProperties": true }, "example": { "schema": "nosible_world_resolve_v1", "q": "nvidia", "count": 2, "results": [ { "kind": "entity", "type": "ORG", "name": "Nvidia", "total_events": 18742, "first_date": "2010-01-07", "last_date": "2026-09-16", "profile": { "kind": "entity", "type": "ORG", "name": "Nvidia", "normalized": "nvidia", "total_events": 18742, "first_date": "2010-01-07", "last_date": "2026-09-16" }, "metadata": { "events_by_year": [ { "year": "2026", "count": 4799 } ], "facets": {}, "numeric": {} }, "match": "exact", "events_url": "/world/v1/entities/events?type=ORG&name=Nvidia", "filter": { "entity_org": { "eq": "Nvidia" } } }, { "kind": "ticker", "type": "TICKER", "ticker": "NVDA", "name": "NVIDIA Corporation", "score": 0.998, "total_events": 15905, "first_date": "2010-01-07", "last_date": "2026-09-16", "profile": { "kind": "ticker", "type": "TICKER", "name": "NVDA", "normalized": "nvda", "total_events": 15905, "first_date": "2010-01-07", "last_date": "2026-09-16" }, "metadata": { "events_by_year": [ { "year": "2026", "count": 4186 } ], "facets": {}, "numeric": {} }, "reference": { "company_name": "NVIDIA Corporation" }, "match": "exact", "events_url": "/world/v1/tickers/NVDA/events", "filter": { "ticker": { "eq": "NVDA" } } } ], "as_of": { "archive_cutoff": "2026-09-16" }, "took_ms": 3 } } } }, "400": { "description": "invalid_request: The date, filter, cursor, identifier, or request combination is invalid.", "x-nosible-error-codes": [ "invalid_request" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "api_key_required: No API key was sent. Send it as Authorization: Bearer or the api-key header.\n\ninvalid_api_key: The API key is invalid or has been revoked.", "x-nosible-error-codes": [ "api_key_required", "invalid_api_key" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "access_denied: The requested archive date is outside the caller's World tier.", "x-nosible-error-codes": [ "access_denied" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "not_found: The requested date, entity, ticker, or event does not exist in the accessible index.\n\nunknown_entity_or_ticker: No entity or ticker candidate matched the query within the resolver's accessible universe.", "x-nosible-error-codes": [ "not_found", "unknown_entity_or_ticker" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "cursor_expired: The cursor was minted against a replaced index build. Restart pagination from the first page.", "x-nosible-error-codes": [ "cursor_expired" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "validation_error: A body field has the wrong type or form, such as a limit sent as a string; the message names it.", "x-nosible-error-codes": [ "validation_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "rate_limited: The request exceeded the endpoint or account rate limit. Respect Retry-After when supplied.", "x-nosible-error-codes": [ "rate_limited" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "501": { "description": "backend_not_configured: The World backend is not configured for this deployment.", "x-nosible-error-codes": [ "backend_not_configured" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "502": { "description": "backend_error: The World backend could not be reached or did not return a valid response; retry shortly.", "x-nosible-error-codes": [ "backend_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "api_key_auth_unavailable: API key authentication is temporarily unavailable; retry shortly.\n\napi_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.", "x-nosible-error-codes": [ "api_key_auth_unavailable", "api_key_metering_unavailable" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "504": { "description": "backend_timeout: The World backend did not answer within 300 seconds; narrow the request (for example with a date window) or retry.", "x-nosible-error-codes": [ "backend_timeout" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/resolve/ticker": { "get": { "operationId": "world_resolve_ticker", "summary": "Find tickers", "description": "Resolve a ticker symbol, issuer name, or alternate security identifier without returning entity candidates.\n\nUse the ticker resolver when the input is a symbol, issuer name, or alternate security identifier. Each result includes the same profile metadata as Ticker Profile.", "tags": [ "HELPERS" ], "externalDocs": { "description": "Interactive reference", "url": "https://docs.nosible.com/endpoints/world-resolve-ticker" }, "x-nosible-reference-pages": [ "world-resolve-ticker" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Ticker symbol, issuer name, or alternate security identifier.", "schema": { "type": "string", "description": "Ticker symbol, issuer name, or alternate security identifier.", "example": "NVDA" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of ticker candidates; defaults to 10 and is capped at 50.", "schema": { "type": "integer", "description": "Maximum number of ticker candidates; defaults to 10 and is capped at 50.", "example": 3 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema": { "type": "string", "description": "Stable resolver contract identifier." }, "q": { "type": "string", "description": "Original ticker lookup query." }, "count": { "type": "integer", "description": "Number of ticker candidates returned." }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Ranked ticker candidates with type, profile, metadata, reference, filter, and events URL." }, "as_of": { "type": "object", "properties": { "archive_cutoff": { "type": "string" } }, "additionalProperties": true, "description": "Index build and archive cutoff used for the lookup." } }, "additionalProperties": true }, "example": { "schema": "nosible_world_resolve_v1", "q": "NVDA", "count": 1, "results": [ { "kind": "ticker", "type": "TICKER", "ticker": "NVDA", "name": "NVIDIA Corporation", "profile": { "kind": "ticker", "type": "TICKER", "name": "NVDA", "normalized": "nvda", "total_events": 15905, "first_date": "2010-01-07", "last_date": "2026-09-16" }, "metadata": { "events_by_year": [ { "year": "2026", "count": 4186 } ], "facets": {}, "numeric": {} }, "reference": { "company_name": "NVIDIA Corporation" }, "events_url": "/world/v1/tickers/NVDA/events", "filter": { "ticker": { "eq": "NVDA" } } } ], "as_of": { "archive_cutoff": "2026-09-16" } } } } }, "400": { "description": "invalid_request: The date, filter, cursor, identifier, or request combination is invalid.", "x-nosible-error-codes": [ "invalid_request" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "api_key_required: No API key was sent. Send it as Authorization: Bearer or the api-key header.\n\ninvalid_api_key: The API key is invalid or has been revoked.", "x-nosible-error-codes": [ "api_key_required", "invalid_api_key" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "access_denied: The requested archive date is outside the caller's World tier.", "x-nosible-error-codes": [ "access_denied" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "not_found: The requested date, entity, ticker, or event does not exist in the accessible index.\n\nunknown_entity_or_ticker: No ticker candidate matched the query within the resolver's accessible universe.", "x-nosible-error-codes": [ "not_found", "unknown_entity_or_ticker" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "cursor_expired: The cursor was minted against a replaced index build. Restart pagination from the first page.", "x-nosible-error-codes": [ "cursor_expired" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "validation_error: A body field has the wrong type or form, such as a limit sent as a string; the message names it.", "x-nosible-error-codes": [ "validation_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "rate_limited: The request exceeded the endpoint or account rate limit. Respect Retry-After when supplied.", "x-nosible-error-codes": [ "rate_limited" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "501": { "description": "backend_not_configured: The World backend is not configured for this deployment.", "x-nosible-error-codes": [ "backend_not_configured" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "502": { "description": "backend_error: The World backend could not be reached or did not return a valid response; retry shortly.", "x-nosible-error-codes": [ "backend_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "api_key_auth_unavailable: API key authentication is temporarily unavailable; retry shortly.\n\napi_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.", "x-nosible-error-codes": [ "api_key_auth_unavailable", "api_key_metering_unavailable" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "504": { "description": "backend_timeout: The World backend did not answer within 300 seconds; narrow the request (for example with a date window) or retry.", "x-nosible-error-codes": [ "backend_timeout" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/entities": { "get": { "operationId": "world_entity_catalog", "summary": "Entity directory", "description": "Enumerate raw entity names found in indexed documents, ordered by event mentions, with observed metadata for each name.\n\nUse the Entity Directory once per index build, then cache the pages locally. It enumerates raw entity names in mentions-desc order; each item carries the same observed metadata as Entity Profile.", "tags": [ "HELPERS" ], "externalDocs": { "description": "Interactive reference", "url": "https://docs.nosible.com/endpoints/world-entity-catalog" }, "x-nosible-reference-pages": [ "world-entity-catalog" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Optional NER type such as ORG, PERSON, or ANY.", "schema": { "type": "string", "description": "Optional NER type such as ORG, PERSON, or ANY.", "example": "ORG" } }, { "name": "page", "in": "query", "required": false, "description": "1-based page number; each page contains up to 50 entities.", "schema": { "type": "integer", "description": "1-based page number; each page contains up to 50 entities.", "example": 1 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema": { "type": "string", "description": "Stable entity directory contract identifier." }, "entity_type": { "type": "string", "nullable": true, "description": "Optional NER type filter." }, "order": { "type": "string", "description": "Popularity order; mentions_desc puts the most-mentioned names first." }, "page": { "type": "integer", "description": "1-based page number." }, "has_more": { "type": "boolean", "description": "Whether another page exists." }, "entities": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Observed entity records with identity, date range, event count, filter, and complete indexed metadata." }, "as_of": { "type": "object", "properties": { "archive_cutoff": { "type": "string" } }, "additionalProperties": true, "description": "Index build and archive cutoff used for the page." } }, "additionalProperties": true }, "example": { "schema": "nosible_world_entity_catalog_v1", "entity_type": "ORG", "order": "mentions_desc", "page": 1, "has_more": true, "entities": [ { "kind": "entity", "type": "ORG", "name": "Nvidia", "normalized": "nvidia", "total_events": 18742, "first_date": "2010-01-07", "last_date": "2026-09-16", "events_url": "/world/v1/entities/events?type=ORG&name=Nvidia", "metadata": { "events_by_year": [ { "year": "2026", "count": 4799 } ], "facets": {}, "numeric": {} }, "filter": { "entity_org": { "eq": "Nvidia" } } } ], "as_of": { "archive_cutoff": "2026-09-16" } } } } }, "400": { "description": "invalid_request: The date, filter, cursor, identifier, or request combination is invalid.\n\ninvalid_entity_type: The type filter is not one of the indexed NER types or ANY.", "x-nosible-error-codes": [ "invalid_request", "invalid_entity_type" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "api_key_required: No API key was sent. Send it as Authorization: Bearer or the api-key header.\n\ninvalid_api_key: The API key is invalid or has been revoked.", "x-nosible-error-codes": [ "api_key_required", "invalid_api_key" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "access_denied: The requested archive date is outside the caller's World tier.", "x-nosible-error-codes": [ "access_denied" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "not_found: The requested date, entity, ticker, or event does not exist in the accessible index.", "x-nosible-error-codes": [ "not_found" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "cursor_expired: The cursor was minted against a replaced index build. Restart pagination from the first page.", "x-nosible-error-codes": [ "cursor_expired" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "validation_error: A body field has the wrong type or form, such as a limit sent as a string; the message names it.", "x-nosible-error-codes": [ "validation_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "rate_limited: The request exceeded the endpoint or account rate limit. Respect Retry-After when supplied.", "x-nosible-error-codes": [ "rate_limited" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "501": { "description": "backend_not_configured: The World backend is not configured for this deployment.", "x-nosible-error-codes": [ "backend_not_configured" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "502": { "description": "backend_error: The World backend could not be reached or did not return a valid response; retry shortly.", "x-nosible-error-codes": [ "backend_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "api_key_auth_unavailable: API key authentication is temporarily unavailable; retry shortly.\n\napi_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.\n\ninverted_index_unavailable: The entity directory index is not loaded; retry after the next index publish.", "x-nosible-error-codes": [ "api_key_auth_unavailable", "api_key_metering_unavailable", "inverted_index_unavailable" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "504": { "description": "backend_timeout: The World backend did not answer within 300 seconds; narrow the request (for example with a date window) or retry.", "x-nosible-error-codes": [ "backend_timeout" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/entities/profile": { "get": { "operationId": "world_entity_profile", "summary": "Entity profile", "description": "Retrieve one indexed entity name with the same observed metadata returned by the Entity Directory.\n\nUse Entity Profile for one known raw entity name. Its profile and metadata shape is identical to the corresponding item in Entity Directory.", "tags": [ "HELPERS" ], "externalDocs": { "description": "Interactive reference", "url": "https://docs.nosible.com/endpoints/world-entity-profile" }, "x-nosible-reference-pages": [ "world-entity-profile" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "type", "in": "query", "required": true, "description": "NER entity type, such as ORG or PERSON.", "schema": { "type": "string", "description": "NER entity type, such as ORG or PERSON.", "example": "ORG" } }, { "name": "name", "in": "query", "required": true, "description": "Canonical raw entity name, normally taken from /api/entities or /api/resolve.", "schema": { "type": "string", "description": "Canonical raw entity name, normally taken from /api/entities or /api/resolve.", "example": "Nvidia" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema": { "type": "string", "description": "Stable entity profile contract identifier." }, "profile": { "type": "object", "properties": { "kind": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "normalized": { "type": "string" }, "total_events": { "type": "number" }, "first_date": { "type": "string" }, "last_date": { "type": "string" }, "events_url": { "type": "string" } }, "additionalProperties": true, "description": "Raw indexed entity identity, date range, event count, and events URL." }, "metadata": { "type": "object", "properties": { "events_by_year": { "type": "array", "items": { "type": "object", "properties": { "year": { "type": "string" }, "count": { "type": "number" } }, "additionalProperties": true } }, "facets": { "type": "object", "properties": {}, "additionalProperties": true }, "numeric": { "type": "object", "properties": {}, "additionalProperties": true } }, "additionalProperties": true, "description": "Complete observed event metadata: yearly counts, categorical facets, and numeric summaries." }, "filter": { "type": "object", "properties": { "entity_org": { "type": "object", "properties": { "eq": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true, "description": "Copy-pasteable exact World Search filter." }, "as_of": { "type": "object", "properties": { "archive_cutoff": { "type": "string" } }, "additionalProperties": true, "description": "Index build and archive cutoff used for the profile." } }, "additionalProperties": true }, "example": { "schema": "nosible_world_entity_profile_v1", "profile": { "kind": "entity", "type": "ORG", "name": "Nvidia", "normalized": "nvidia", "total_events": 18742, "first_date": "2010-01-07", "last_date": "2026-09-16", "events_url": "/world/v1/entities/events?type=ORG&name=Nvidia" }, "metadata": { "events_by_year": [ { "year": "2026", "count": 4799 } ], "facets": {}, "numeric": {} }, "filter": { "entity_org": { "eq": "Nvidia" } }, "as_of": { "archive_cutoff": "2026-09-16" } } } } }, "400": { "description": "invalid_request: Both type and name are required, and type must be an indexed NER type.", "x-nosible-error-codes": [ "invalid_request" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "api_key_required: No API key was sent. Send it as Authorization: Bearer or the api-key header.\n\ninvalid_api_key: The API key is invalid or has been revoked.", "x-nosible-error-codes": [ "api_key_required", "invalid_api_key" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "access_denied: The requested archive date is outside the caller's World tier.", "x-nosible-error-codes": [ "access_denied" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "not_found: The requested date, entity, ticker, or event does not exist in the accessible index.\n\nunknown_entity: The requested entity is not present in the index.", "x-nosible-error-codes": [ "not_found", "unknown_entity" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "cursor_expired: The cursor was minted against a replaced index build. Restart pagination from the first page.", "x-nosible-error-codes": [ "cursor_expired" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "validation_error: A body field has the wrong type or form, such as a limit sent as a string; the message names it.", "x-nosible-error-codes": [ "validation_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "rate_limited: The request exceeded the endpoint or account rate limit. Respect Retry-After when supplied.", "x-nosible-error-codes": [ "rate_limited" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "501": { "description": "backend_not_configured: The World backend is not configured for this deployment.", "x-nosible-error-codes": [ "backend_not_configured" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "502": { "description": "backend_error: The World backend could not be reached or did not return a valid response; retry shortly.", "x-nosible-error-codes": [ "backend_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "api_key_auth_unavailable: API key authentication is temporarily unavailable; retry shortly.\n\napi_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.", "x-nosible-error-codes": [ "api_key_auth_unavailable", "api_key_metering_unavailable" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "504": { "description": "backend_timeout: The World backend did not answer within 300 seconds; narrow the request (for example with a date window) or retry.", "x-nosible-error-codes": [ "backend_timeout" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/tickers": { "get": { "operationId": "world_ticker_catalog", "summary": "Ticker directory", "description": "Enumerate indexed ticker names in mentions order, with the same observed metadata as entities plus CompanyV4 reference metadata.\n\nUse the Ticker Directory like Entity Directory: page through raw indexed ticker names in mentions-desc order. Each item has the same observed fields and metadata as an entity item, plus CompanyV4 reference data.", "tags": [ "HELPERS" ], "externalDocs": { "description": "Interactive reference", "url": "https://docs.nosible.com/endpoints/world-ticker-catalog" }, "x-nosible-reference-pages": [ "world-ticker-catalog" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "1-based page number; each page contains up to 50 tickers.", "schema": { "type": "integer", "description": "1-based page number; each page contains up to 50 tickers.", "example": 1 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema": { "type": "string", "description": "Stable ticker directory contract identifier." }, "order": { "type": "string", "description": "Popularity order; mentions_desc puts the most-mentioned tickers first." }, "page": { "type": "integer", "description": "1-based page number." }, "has_more": { "type": "boolean", "description": "Whether another page exists." }, "tickers": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Observed ticker records with entity-equivalent fields plus reference." }, "as_of": { "type": "object", "properties": { "archive_cutoff": { "type": "string" } }, "additionalProperties": true, "description": "Index build and archive cutoff used for the page." } }, "additionalProperties": true }, "example": { "schema": "nosible_world_ticker_catalog_v1", "order": "mentions_desc", "page": 1, "has_more": true, "tickers": [ { "kind": "ticker", "type": "TICKER", "name": "NVDA", "normalized": "nvda", "total_events": 15905, "first_date": "2010-01-07", "last_date": "2026-09-16", "events_url": "/world/v1/tickers/NVDA/events", "metadata": { "events_by_year": [ { "year": "2026", "count": 4186 } ], "facets": {}, "numeric": {} }, "filter": { "ticker": { "eq": "NVDA" } }, "reference": { "company_name": "NVIDIA Corporation" } } ], "as_of": { "archive_cutoff": "2026-09-16" } } } } }, "400": { "description": "invalid_request: The date, filter, cursor, identifier, or request combination is invalid.", "x-nosible-error-codes": [ "invalid_request" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "api_key_required: No API key was sent. Send it as Authorization: Bearer or the api-key header.\n\ninvalid_api_key: The API key is invalid or has been revoked.", "x-nosible-error-codes": [ "api_key_required", "invalid_api_key" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "access_denied: The requested archive date is outside the caller's World tier.", "x-nosible-error-codes": [ "access_denied" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "not_found: The requested date, entity, ticker, or event does not exist in the accessible index.", "x-nosible-error-codes": [ "not_found" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "cursor_expired: The cursor was minted against a replaced index build. Restart pagination from the first page.", "x-nosible-error-codes": [ "cursor_expired" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "validation_error: A body field has the wrong type or form, such as a limit sent as a string; the message names it.", "x-nosible-error-codes": [ "validation_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "rate_limited: The request exceeded the endpoint or account rate limit. Respect Retry-After when supplied.", "x-nosible-error-codes": [ "rate_limited" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "501": { "description": "backend_not_configured: The World backend is not configured for this deployment.", "x-nosible-error-codes": [ "backend_not_configured" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "502": { "description": "backend_error: The World backend could not be reached or did not return a valid response; retry shortly.", "x-nosible-error-codes": [ "backend_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "api_key_auth_unavailable: API key authentication is temporarily unavailable; retry shortly.\n\napi_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.\n\nresolve_index_unavailable: The ticker directory index is not loaded; retry after the next index publish.", "x-nosible-error-codes": [ "api_key_auth_unavailable", "api_key_metering_unavailable", "resolve_index_unavailable" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "504": { "description": "backend_timeout: The World backend did not answer within 300 seconds; narrow the request (for example with a date window) or retry.", "x-nosible-error-codes": [ "backend_timeout" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/tickers/profile": { "get": { "operationId": "world_ticker_profile", "summary": "Ticker profile", "description": "Retrieve one indexed ticker with the same observed metadata as the Ticker Directory and CompanyV4 reference metadata.\n\nUse Ticker Profile for one known symbol or alternate identifier. It returns the same observed metadata as Ticker Directory plus CompanyV4 reference metadata.", "tags": [ "HELPERS" ], "externalDocs": { "description": "Interactive reference", "url": "https://docs.nosible.com/endpoints/world-ticker-profile" }, "x-nosible-reference-pages": [ "world-ticker-profile" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "symbol", "in": "query", "required": true, "description": "Ticker symbol or alternate identifier to look up.", "schema": { "type": "string", "description": "Ticker symbol or alternate identifier to look up.", "example": "NVDA" } }, { "name": "id_type", "in": "query", "required": false, "description": "Identifier type: symbol, isin, figi, lei, or qid. Defaults to symbol.", "schema": { "type": "string", "description": "Identifier type: symbol, isin, figi, lei, or qid. Defaults to symbol.", "example": "symbol" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema": { "type": "string", "description": "Stable ticker profile contract identifier." }, "profile": { "type": "object", "properties": { "kind": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "normalized": { "type": "string" }, "total_events": { "type": "number" }, "first_date": { "type": "string" }, "last_date": { "type": "string" }, "events_url": { "type": "string" } }, "additionalProperties": true, "description": "Raw indexed ticker identity, date range, event count, and events URL." }, "metadata": { "type": "object", "properties": { "events_by_year": { "type": "array", "items": { "type": "object", "properties": { "year": { "type": "string" }, "count": { "type": "number" } }, "additionalProperties": true } }, "facets": { "type": "object", "properties": {}, "additionalProperties": true }, "numeric": { "type": "object", "properties": {}, "additionalProperties": true } }, "additionalProperties": true, "description": "Complete observed event metadata: yearly counts, categorical facets, and numeric summaries." }, "filter": { "type": "object", "properties": { "ticker": { "type": "object", "properties": { "eq": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true, "description": "Copy-pasteable exact ticker filter." }, "reference": { "type": "object", "properties": { "company_name": { "type": "string" } }, "additionalProperties": true, "description": "CompanyV4 names, websites, identifiers, market data, geography, classification, status, and provenance when available." }, "as_of": { "type": "object", "properties": { "archive_cutoff": { "type": "string" } }, "additionalProperties": true, "description": "Index build and archive cutoff used for the profile." } }, "additionalProperties": true }, "example": { "schema": "nosible_world_ticker_profile_v1", "profile": { "kind": "ticker", "type": "TICKER", "name": "NVDA", "normalized": "nvda", "total_events": 15905, "first_date": "2010-01-07", "last_date": "2026-09-16", "events_url": "/world/v1/tickers/NVDA/events" }, "metadata": { "events_by_year": [ { "year": "2026", "count": 4186 } ], "facets": {}, "numeric": {} }, "filter": { "ticker": { "eq": "NVDA" } }, "reference": { "company_name": "NVIDIA Corporation" }, "as_of": { "archive_cutoff": "2026-09-16" } } } } }, "400": { "description": "invalid_request: The symbol query parameter is required.", "x-nosible-error-codes": [ "invalid_request" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "api_key_required: No API key was sent. Send it as Authorization: Bearer or the api-key header.\n\ninvalid_api_key: The API key is invalid or has been revoked.", "x-nosible-error-codes": [ "api_key_required", "invalid_api_key" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "access_denied: The requested archive date is outside the caller's World tier.", "x-nosible-error-codes": [ "access_denied" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "not_found: The requested date, entity, ticker, or event does not exist in the accessible index.\n\nunknown_ticker: The requested symbol or identifier does not resolve to an indexed security.", "x-nosible-error-codes": [ "not_found", "unknown_ticker" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "cursor_expired: The cursor was minted against a replaced index build. Restart pagination from the first page.", "x-nosible-error-codes": [ "cursor_expired" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "validation_error: A body field has the wrong type or form, such as a limit sent as a string; the message names it.", "x-nosible-error-codes": [ "validation_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "rate_limited: The request exceeded the endpoint or account rate limit. Respect Retry-After when supplied.", "x-nosible-error-codes": [ "rate_limited" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "501": { "description": "backend_not_configured: The World backend is not configured for this deployment.", "x-nosible-error-codes": [ "backend_not_configured" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "502": { "description": "backend_error: The World backend could not be reached or did not return a valid response; retry shortly.", "x-nosible-error-codes": [ "backend_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "api_key_auth_unavailable: API key authentication is temporarily unavailable; retry shortly.\n\napi_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.", "x-nosible-error-codes": [ "api_key_auth_unavailable", "api_key_metering_unavailable" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "504": { "description": "backend_timeout: The World backend did not answer within 300 seconds; narrow the request (for example with a date window) or retry.", "x-nosible-error-codes": [ "backend_timeout" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/ontology": { "get": { "operationId": "world_ontology_catalog", "summary": "Ontology directory", "description": "List all supported ontologies, or fetch one ontology's hierarchy, definitions, coverage statistics, and example events.\n\nCall without parameters to list every supported ontology. Add ontology=emdat for the nested EM-DAT tree, definitions, example events, and live coverage statistics.", "tags": [ "HELPERS" ], "externalDocs": { "description": "Interactive reference", "url": "https://docs.nosible.com/endpoints/world-ontology-catalog" }, "x-nosible-reference-pages": [ "world-ontology-catalog" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "ontology", "in": "query", "required": false, "description": "Optional ontology id or slug. Omit it to list every supported ontology; use emdat for the full EM-DAT reference.", "schema": { "type": "string", "description": "Optional ontology id or slug. Omit it to list every supported ontology; use emdat for the full EM-DAT reference.", "example": "emdat" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema": { "type": "string", "description": "Stable ontology reference contract identifier." }, "ontology": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "levels": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true, "nullable": true, "description": "Selected ontology metadata, present when ontology is supplied." }, "coverage": { "type": "object", "properties": { "labelled_events": { "type": "number" }, "world_events": { "type": "number" }, "share_of_world": { "type": "number" } }, "additionalProperties": true, "description": "Live indexed event counts and shares for the selected ontology." }, "hierarchy": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Nested tree preserving parent-child paths such as Natural → Meteorological → Storm." }, "as_of": { "type": "object", "properties": { "archive_cutoff": { "type": "string" } }, "additionalProperties": true, "description": "Current index build and cutoff used for the statistics." }, "ontologies": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Supported ontology summaries." } }, "additionalProperties": true }, "example": { "schema": "nosible_world_ontology_reference_v1", "ontology": { "id": "emdat", "name": "EM-DAT Disaster Classification", "levels": [ "disaster_group", "disaster_subgroup", "disaster_type" ] }, "coverage": { "labelled_events": 1393908, "world_events": 15311040, "share_of_world": 0.091 }, "hierarchy": [ { "name": "Natural", "children": [ { "name": "Meteorological", "children": [ { "name": "Storm", "path": [ "Natural", "Meteorological", "Storm" ], "event_count": 76605, "definition": "High-intensity atmospheric systems...", "example_events": [] } ] } ] } ], "as_of": { "archive_cutoff": "2026-09-16" } } } } }, "400": { "description": "invalid_request: The date, filter, cursor, identifier, or request combination is invalid.", "x-nosible-error-codes": [ "invalid_request" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "api_key_required: No API key was sent. Send it as Authorization: Bearer or the api-key header.\n\ninvalid_api_key: The API key is invalid or has been revoked.", "x-nosible-error-codes": [ "api_key_required", "invalid_api_key" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "access_denied: The requested archive date is outside the caller's World tier.", "x-nosible-error-codes": [ "access_denied" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "not_found: The requested date, entity, ticker, or event does not exist in the accessible index.\n\nunknown_ontology: The ontology id or slug is not in the supported ontology directory.", "x-nosible-error-codes": [ "not_found", "unknown_ontology" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "cursor_expired: The cursor was minted against a replaced index build. Restart pagination from the first page.", "x-nosible-error-codes": [ "cursor_expired" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "validation_error: A body field has the wrong type or form, such as a limit sent as a string; the message names it.", "x-nosible-error-codes": [ "validation_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "rate_limited: The request exceeded the endpoint or account rate limit. Respect Retry-After when supplied.", "x-nosible-error-codes": [ "rate_limited" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "501": { "description": "backend_not_configured: The World backend is not configured for this deployment.", "x-nosible-error-codes": [ "backend_not_configured" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "502": { "description": "backend_error: The World backend could not be reached or did not return a valid response; retry shortly.", "x-nosible-error-codes": [ "backend_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "api_key_auth_unavailable: API key authentication is temporarily unavailable; retry shortly.\n\napi_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.\n\ninverted_index_unavailable: Current ontology counts cannot be served until the live World index is loaded.", "x-nosible-error-codes": [ "api_key_auth_unavailable", "api_key_metering_unavailable", "inverted_index_unavailable" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "504": { "description": "backend_timeout: The World backend did not answer within 300 seconds; narrow the request (for example with a date window) or retry.", "x-nosible-error-codes": [ "backend_timeout" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/search/schema": { "get": { "operationId": "world_search_schema", "summary": "Search Schema", "description": "Retrieve the versioned filter and field schema accepted by World Search.\n\nFetch this schema before generating dynamic World Search filters. It is the machine-readable inventory of supported fields, operators, aliases, entity types, semantic controls, and ontology values. Cache it by revision and invalidate your cache when revision changes.", "tags": [ "HELPERS" ], "externalDocs": { "description": "Interactive reference", "url": "https://docs.nosible.com/endpoints/world-search-schema" }, "x-nosible-reference-pages": [ "world-search-schema" ], "security": [ { "BearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema": { "type": "string", "description": "Schema contract identifier." }, "revision": { "type": "integer", "description": "Revision of the field and operator catalog." }, "endpoint": { "type": "string", "description": "Canonical backend search endpoint represented by the catalog." }, "search_types": { "type": "array", "items": { "type": "string" }, "description": "Supported retrieval modes." }, "semantic_inputs": { "type": "object", "properties": { "q": { "type": "string" }, "vector": { "type": "string" } }, "additionalProperties": true, "description": "How q, vector, and query_vector are interpreted by semantic retrieval." }, "entity_types": { "type": "array", "items": { "type": "string" }, "description": "Indexed NER entity types used by entity_* and entity_any filter fields." }, "resolve_endpoint": { "type": "string", "description": "Canonical resolver route to use before constructing entity or ticker filters." }, "logical": { "type": "array", "items": { "type": "string" }, "description": "Logical filter operators." }, "semantic_filter_modes": { "type": "array", "items": { "type": "string" }, "description": "Semantic filter strategies." }, "fields": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Complete searchable and facetable field catalog, including aliases, types, and facet support." }, "operators": { "type": "object", "additionalProperties": true, "description": "Operators supported by each field type, including the restricted string_set operator family." }, "geo": { "type": "object", "additionalProperties": true, "description": "Shapes for bbox and geo_radius filters." }, "retrieval": { "type": "object", "additionalProperties": true, "description": "Backend retrieval paths used for archive, live, and filtered semantic queries." } }, "additionalProperties": true }, "example": { "schema": "nosible_world_search_schema_v1", "revision": 2, "endpoint": "POST /world/v1/search", "search_types": [ "metadata", "lexical", "semantic", "hybrid" ], "semantic_inputs": { "q": "server embeds text", "vector": "caller-supplied f32 vector; alias query_vector" }, "entity_types": [ "EVENT", "FAC", "GPE", "LANGUAGE", "LAW", "LOC", "NORP", "ORG", "PERSON", "PRODUCT", "WORK_OF_ART" ], "resolve_endpoint": "GET /world/v1/resolve", "logical": [ "and", "or", "not" ], "semantic_filter_modes": [ "auto", "usearch", "exact" ], "fields": [ { "name": "country", "type": "string", "aliases": [], "facet": true } ] } } } }, "400": { "description": "invalid_request: The date, filter, cursor, identifier, or request combination is invalid.", "x-nosible-error-codes": [ "invalid_request" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "api_key_required: No API key was sent. Send it as Authorization: Bearer or the api-key header.\n\ninvalid_api_key: The API key is invalid or has been revoked.", "x-nosible-error-codes": [ "api_key_required", "invalid_api_key" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "access_denied: The requested archive date is outside the caller's World tier.", "x-nosible-error-codes": [ "access_denied" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "not_found: The requested date, entity, ticker, or event does not exist in the accessible index.", "x-nosible-error-codes": [ "not_found" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "410": { "description": "cursor_expired: The cursor was minted against a replaced index build. Restart pagination from the first page.", "x-nosible-error-codes": [ "cursor_expired" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "validation_error: A body field has the wrong type or form, such as a limit sent as a string; the message names it.", "x-nosible-error-codes": [ "validation_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "rate_limited: The request exceeded the endpoint or account rate limit. Respect Retry-After when supplied.", "x-nosible-error-codes": [ "rate_limited" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "501": { "description": "backend_not_configured: The World backend is not configured for this deployment.", "x-nosible-error-codes": [ "backend_not_configured" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "502": { "description": "backend_error: The World backend could not be reached or did not return a valid response; retry shortly.", "x-nosible-error-codes": [ "backend_error" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "api_key_auth_unavailable: API key authentication is temporarily unavailable; retry shortly.\n\napi_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.", "x-nosible-error-codes": [ "api_key_auth_unavailable", "api_key_metering_unavailable" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "504": { "description": "backend_timeout: The World backend did not answer within 300 seconds; narrow the request (for example with a date window) or retry.", "x-nosible-error-codes": [ "backend_timeout" ], "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key" } }, "schemas": { "WorldEvent": { "type": "object", "properties": { "event_id": { "type": "string", "description": "Opaque stable identifier for the event cluster." }, "event": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "World archive date associated with the event cluster." }, "title": { "type": "string", "description": "Human-readable event headline." }, "description": { "type": "string", "description": "Concise event narrative synthesized from the evidence cluster." } }, "additionalProperties": true }, "signals": { "type": "object", "properties": { "sentiment": { "type": "string" }, "materiality": { "type": "string" }, "time_horizon": { "type": "string" } }, "additionalProperties": true, "description": "Normalized signals for sentiment, materiality, and time horizon." }, "coverage": { "type": "object", "properties": { "total_coverage": { "type": "number" }, "total_netlocs": { "type": "number" } }, "additionalProperties": true, "description": "Counts describing how broadly the event is covered across documents and unique source domains." }, "entities": { "type": "object", "properties": { "ORG": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true, "description": "Named entities detected in the event, grouped by NER type. Each type maps surface forms to mention counts." }, "version": { "type": "string", "description": "Canonical event-record version." }, "has_tickers": { "type": "boolean", "description": "Whether the event has one or more matched securities." }, "ontology": { "type": "object", "additionalProperties": true, "description": "Complete populated taxonomy slots, including GICS, IAB, IPTC, and NOSIBLE classifications where available." }, "tickers": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Matched security records, including issuer names and alternate identifiers. Empty when has_tickers is false." }, "provenance": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Citation-ready supporting evidence with source URL, title, snippets, and event score." }, "timestamps": { "type": "object", "additionalProperties": true, "description": "First/last/most-seen timestamps and optional hourly observation counts. Empty when no source carried a timestamp." }, "similar": { "type": "object", "additionalProperties": true, "description": "Persisted story-predecessor map of event IDs to cosine similarity. This is distinct from the on-demand /similar route." }, "oai_vector": { "type": "string", "description": "Comma-separated event embedding when the full projection includes it. Treat as model output, not a human-readable field." }, "extra": { "type": "object", "additionalProperties": true, "description": "Additional model signals, including per-class sentiment and forward-looking probabilities." }, "coordinate": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Resolved event location, including latitude, longitude, source, and locality when available." } }, "additionalProperties": true } } } }