Search Schema

Retrieve the versioned filter and field schema accepted by World Search.

GET/api/v2.0-preview/search/schema

Authorizations

Bearer

Authorizationstringrequiredheader

Required Bearer API key. Programmatic access to the World API needs a key; browsing nosible.world in a browser does not.

Example: Bearer nos_sk_...

How to use this endpoint

guidance

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

Response body

application/json

These are the fields you can build against. Nested names use dot notation; optional sections are called out in their descriptions.

schemastring

Response schema name.

revisioninteger

Revision of the catalogue; cache by it.

endpointstring

The search route the catalogue describes, as the backend names it.

search_typesstring[]

Supported retrieval modes.

semantic_inputsobject

How q, vector, vectors, vector_texts, score_vectors and score_vector_texts are used.

date_grouped_semanticobject

How to request date-grouped semantic search, with its limits.

operatorsobject

Filter operators per field type.

entity_typesstring[]

NER types of the entity_* filter fields.

resolve_endpointstring

The resolver route, as the backend names it.

logicalstring[]

Logical filter operators.

geoobject

Shapes of the bbox and geo_radius filters.

retrievalobject

Retrieval paths for archive, live and filtered semantic search.

semantic_filter_modesstring[]

Semantic filter strategies.

fieldsobject[]

Every filterable field.

fields[].namestring

Field name, as used in filters, sort and facets.

fields[].typestring

Field type: string, number, boolean, date or string_set; operators lists what each accepts.

fields[].aliasesstring[]

Other names accepted for the field.

fields[].facetboolean

Whether facets can count the field.

Responses and errors

HTTP

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

400invalid_request — The date, filter, cursor, identifier, or request combination is invalid.

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

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

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

404not_found — The requested date, entity, ticker, or event does not exist in the accessible index.

410cursor_expired — The cursor was minted against a replaced index build. Restart pagination from the first page.

429rate_limited — The request exceeded the endpoint or account rate limit. Respect Retry-After when supplied.

501backend_not_configured — The World backend is not configured for this deployment.

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

502backend_error — The BFF could not obtain a valid response from the World backend.

504backend_timeout — The World backend or an upstream data source timed out.

{ "schema": "nosible_world_search_schema_v1", "revision": 4, "endpoint": "POST /world/v1/search", "search_types": [ "metadata", "lexical", "semantic", "hybrid" ], "semantic_inputs": { "q": "server embeds text with the configured embedding provider", "vector": "caller-supplied f32 query vector; alias query_vector; length must match events_api.hnsw.ndim", "vectors": "caller-supplied query vectors for date-grouped semantic retrieval", "vector_texts": "plain-language factor anchors embedded server-side for date-grouped retrieval", "score_vectors": "extra vectors scored exactly on grouped candidates without widening retrieval", "score_vector_texts": "plain-language score-only statements embedded server-side for date-grouped retrieval" }, "date_grouped_semantic": { "enable": { "group_by": "date", "include": [ "factor" ] }, "definition_inputs": "provide vectors or vector_texts (but not both); score_vectors and score_vector_texts are score-only equivalents", "response_projections": { "nosible_world_factor_search_v1": { "include": [ "factor" ] }, "nosible_world_factor_columns_v1": { "include": [ "factor", "factor_columns_v1" ], "revision": 1, "score_range": [ -1, 1 ], "score_vector_width": "request.score_vectors.length", "score_vector_order": "request order" } }, "vector_aggregate": [ "max", "mean", "softmax" ], "per_date_limit": "candidate count retrieved per query vector and date; default 1000", "min_score": "inclusive aggregate cosine floor applied after exact reranking", "max_dates_per_request": 120, "max_vectors_per_field": 64, "max_candidate_retrievals": 2000000, "max_score_dot_products": 50000000, "max_concurrent_requests": 5, "max_queued_requests": 20, "max_response_events": 100000, "max_response_units": 1000000, "max_request_bytes": 16777216, "response": "lean numeric projection, exact eligible totals, and explicit truncation diagnostics per date" }, "operators": { "string": [ "eq", "neq", "in", "not_in", "exists", "missing", "contains", "prefix" ], "number": [ "eq", "neq", "in", "not_in", "exists", "missing", "gt", "gte", "lt", "lte", "between" ], "boolean": [ "eq", "neq", "exists", "missing" ], "date": [ "eq", "neq", "in", "not_in", "gt", "gte", "lt", "lte", "between" ], "string_set": [ "eq", "in", "all", "not_in", "contains", "prefix" ] }, "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" ], "geo": { "bbox": { "shape": "[west_lng, south_lat, east_lng, north_lat]" }, "geo_radius": { "shape": { "lat": 0, "lng": 0, "km": 100 } } }, "retrieval": { "archive_semantic": "global packed-binary coarse retrieval when present, otherwise global HNSW over the stable archive", "live_semantic": "rolling per-date HNSW slices after the archive cutoff when date.include_live is true", "filtered_semantic": "semantic_filter_mode=auto/usearch uses uSearch predicate filtering during graph traversal; semantic_filter_mode=exact scores every metadata-qualified row" }, "semantic_filter_modes": [ "auto", "usearch", "exact" ], "fields": [ { "name": "event_id", "type": "string", "aliases": [], "facet": false }, { "name": "date", "type": "date", "aliases": [], "facet": true }, { "name": "title", "type": "string", "aliases": [], "facet": false } ] }

Search Schema

Authorizations

Related in NOSIBLE World

How to use this endpoint

Response body

Responses and errors