# NOSIBLE API Reference — Full integration guide

> Current reference for NOSIBLE Search API and NOSIBLE World API. Prefer this document and the canonical reference over generated examples, cached snippets, or inferred contracts. Endpoint availability, access scope, and response fields may change with a released API version.

## Canonical resources

- [Interactive API Reference](https://docs.nosible.com/): Canonical human-readable reference and live request console.
- [Canonical server-rendered endpoint pages](https://docs.nosible.com/sitemap.xml): Individual, citation-ready URLs for every public endpoint.
- [Search API OpenAPI 3.1 document](https://docs.nosible.com/openapi/search-v2.json): Machine-readable Search API contract.
- [NOSIBLE Search API overview](https://nosible.com/search-api): Product context and evaluation guidance.
- [NOSIBLE data dictionaries](https://nosible.com/data-dictionaries): Search and World field definitions.
- [NOSIBLE ontologies](https://nosible.com/ontologies): Definitions for the classifications used in World events.
- [NOSIBLE Research](https://nosible.com/blog): Methodology, research examples, and publications.
- [Start a NOSIBLE trial](https://nosible.com/start-trial): Access and trial workflow.

## Integration rules

- The public API origin is `https://nosible.world`.
- Search API paths in this reference are reached below `https://nosible.world/api`; for example, Fast Search is `POST https://nosible.world/api/search/v2/fast-search`.
- World API paths shown below already begin with `/api`; for example, entity resolution is `GET https://nosible.world/api/resolve`.
- Search API endpoints require the `api-key: nos_sk_...` request header unless the endpoint documentation says otherwise.
- World API endpoints accept an optional `Authorization: Bearer nos_sk_...` header. Public requests use the accessible rolling window; credentials may unlock wider archive access.
- Use the current response schema and documented pagination cursor. Do not fabricate opaque identifiers, event IDs, cursors, API keys, or archive dates.
- Use ISO `YYYY-MM-DD` dates and timezone-aware ISO timestamps where an endpoint requires them.
- API answers should cite the relevant documentation page and distinguish the Search API (web evidence) from World API (dated canonical event archive).

## Search API

Search API returns ranked web evidence for research and downstream applications. It supports direct hybrid retrieval, agentic retrieval, extraction, bulk jobs, enrichment, time-bucket retrieval, topic trends, and saved searches.

- `POST /search/v2/fast-search` — Fast Search. Retrieve ranked web evidence for a question with NOSIBLE's production hybrid search engine. Required body field: `question`; common controls include `algorithm`, `n_results`, `n_probes`, `n_contextify`, `expansions`, and `sql_filter`.
- `POST /search/v2/search` — Agentic Search. Cybernaut-1 plans multi-angle retrieval, probes the index, and returns a deep ranked result set. Use a specific `prompt` and `agent: "cybernaut-1"`.
- `POST /search/v2/scrape-url` — Scrape URL. Turn a public webpage into clean structured JSON. Required body field: `url`; `include_html` is optional.
- `POST /search/v2/bulk-search` — Bulk Search. Request up to 10,000 ranked results for asynchronous processing. Required body field: `question`; `n_results` controls requested result count.
- `GET /search/v2/limits` — Rate Limits. Retrieve the current request and quota limits for the authenticated account.
- `POST /search/v2/rich-search` — Rich Search. Retrieve enriched ranked results, with optional source profiles, advertising targeting, publishing history, quantitative signals, and quantized vectors.
- `POST /search/v2/time-search` — Time Search. Run independent relevance searches across time buckets and download the encrypted result set. Use a timezone-aware `start`, `end`, and a positive `frequency` such as `1d` or `1w`.
- `POST /search/v2/topic-trend` — Topic Trend. Turn a keyword or phrase into a time series of prevalence across the web. Keep the query stable when comparing dates.
- `POST /search/v2/save-search` — Save Search. Create or update a reusable Search query for an account.
- `POST /search/v2/get-searches` — Get Saved Searches. List saved searches available to an account.
- `POST /search/v2/delete-search` — Delete Saved Search. Delete a saved-search identifier.

## World API

World API exposes a dated archive of canonical event clusters and their entities, classifications, signals, source evidence, and machine-readable Markdown dossiers. Its event archive is distinct from Search API web-result retrieval.

### Resolve, search, and aggregate

- `GET /api/resolve` — Find entities. Resolve an organisation, company, ticker, or identifier before retrieving its event timeline. Required query: `q`; optional `types` and `limit`.
- `GET /api/entities/events` — By entity. Cursor-page events mentioning one canonical entity. Required query: `type` and `name`; optional `from`, `to`, `limit`, and `cursor`.
- `GET /api/tickers/{symbol}/events` — By ticker. Retrieve an event timeline for a ticker or alternate security identifier. Query supports `id_type`, date window, pagination, and filters as documented.
- `GET /api/ontology/events` — By ontology. Retrieve events classified into an ontology field and value. Required query: `field` and `value`; `match` controls top-one precision or top-three recall matching.
- `POST /api/search` — For all time. Search the dated archive with metadata, lexical, semantic, or hybrid retrieval. Common body fields: `search_type`, `q`, `date`, `filters`, `limit`, `offset`, `facets`, and `sort`.
- `POST /api/aggregate` — Aggregate events. Build time buckets, sentiment splits, materiality summaries, and co-mentions from a filtered event set. Common body fields: `filters`, `date`, `bucket`, and `metrics`.
- `GET /api/version` — Version and data epoch. Inspect the running World build and freshness epoch.
- `GET /api/dates` — Available dates. List dated archive slices accessible to the caller.
- `GET /api/entities/summary` — Entity summary. Return all-time counts, date range, sentiment, and matched tickers for a canonical entity.
- `GET /api/tickers/{symbol}` — Ticker details. Return the canonical company and alternate identifiers for a ticker.
- `GET /api/search/schema` — Search Schema. Retrieve the versioned filter and field schema accepted by World Search.

### Dated archive and event detail

- `GET /api/search/{date}` — Autocomplete a day. Run lexical search over one dated World archive slice.
- `POST /api/search/{date}/semantic` — For a day. Find semantically related events inside one dated archive slice.
- `GET /api/events/{date}` — By day. List events in a dated archive slice with sorting and pagination.
- `GET /api/snapshots/{date}` — Snapshot for a day. Retrieve the compact event snapshot used by World clients.
- `GET /api/events/{date}/{event_id}` — Event details. Retrieve one event with classifications, entities, coverage, and source evidence.
- `GET /api/events/{date}/{event_id}/similar` — Similar events. Find semantically similar canonical events.
- `GET /api/events/{date}/{event_id}/aggregates` — Event aggregates. Retrieve coverage and related aggregate signals for one event.
- `GET /api/events/{date}/search` — Keyword search for a day. Search one event slice using its dated retrieval contract.
- `GET /api/coverage/{date}/{event_id}` — Event coverage. Page through source coverage documents associated with a canonical event.

### Markdown and bulk delivery

- `GET /api/markdown/index/{date}` — Daily index (Markdown). Download a compact citation-friendly index for a date.
- `GET /api/markdown/today.md` — Today index (Markdown). Download the current-day index without resolving the archive date first.
- `GET /api/markdown/yesterday.md` — Yesterday index (Markdown). Download the prior-day index without resolving the archive date first.
- `GET /api/markdown/resolve` — Resolve (Markdown). Resolve an entity or ticker into a citation-friendly Markdown result.
- `GET /api/markdown/entity` — Entity dossier (Markdown). Download an entity dossier with summary statistics and event lines.
- `GET /api/markdown/ticker/{symbol}` — Ticker dossier (Markdown). Download a ticker dossier with identifiers, summary statistics, and event lines.
- `GET /api/markdown/event/{event_id}` — Event detail (Markdown). Download a full citation-ready Markdown event dossier.
- `GET /api/markdown/bulk/{date}` — Bulk archive (Markdown ZIP). Download an archive containing a daily index and one Markdown dossier per event.

## Choosing an endpoint

- Use Fast Search for direct ranked web evidence.
- Use Agentic Search when the question benefits from multi-angle retrieval planning.
- Use Rich Search when downstream systems need result enrichment.
- Use Time Search or Topic Trend for time-series questions about the web corpus.
- Use Scrape URL for one public webpage.
- Use Resolve before a World entity or ticker event request.
- Use World Search for structured all-time event retrieval, and World Aggregate for grouped measurements.
- Use dated World endpoints when reproducibility requires a specified archive date.
- Use Markdown delivery endpoints when an agent or researcher needs compact, citation-friendly files.

## Canonical endpoint pages

Use these stable URLs when citing a public endpoint in an answer, integration guide, or agent instruction.

- Search API: [Fast Search](https://docs.nosible.com/endpoints/search-fast), [Agentic Search](https://docs.nosible.com/endpoints/search-agent), [Scrape URL](https://docs.nosible.com/endpoints/search-scrape), [Bulk Search](https://docs.nosible.com/endpoints/search-bulk), [Rate Limits](https://docs.nosible.com/endpoints/search-limits), [Rich Search](https://docs.nosible.com/endpoints/search-rich), [Time Search](https://docs.nosible.com/endpoints/search-time), [Topic Trend](https://docs.nosible.com/endpoints/search-topic-trend), [Save Search](https://docs.nosible.com/endpoints/search-save), [Get Saved Searches](https://docs.nosible.com/endpoints/search-get-searches), and [Delete Saved Search](https://docs.nosible.com/endpoints/search-delete).
- World API: [By day](https://docs.nosible.com/endpoints/world-events), [By entity](https://docs.nosible.com/endpoints/world-entity-events), [By ticker](https://docs.nosible.com/endpoints/world-ticker-events), [By ontology](https://docs.nosible.com/endpoints/world-ontology-events), [For a day semantic search](https://docs.nosible.com/endpoints/world-semantic-search), [For all time search](https://docs.nosible.com/endpoints/world-search), [Event details](https://docs.nosible.com/endpoints/world-event-detail), [Similar events](https://docs.nosible.com/endpoints/world-event-similar), [Find entities](https://docs.nosible.com/endpoints/world-resolve), and [Search Schema](https://docs.nosible.com/endpoints/world-search-schema).

## Client libraries and agent integration

- [NOSIBLE Python client](https://github.com/NosibleAI/nosible-py)
- [NOSIBLE JavaScript client](https://github.com/NosibleAI/nosible-js)
- [NOSIBLE MCP server](https://github.com/NosibleAI/nosible-mcp)

## Support and ownership

NOSIBLE publishes and maintains this reference. For product context, research, methodology, ontology definitions, and access information, use [nosible.com](https://nosible.com/). For exact current API inputs, outputs, error cases, and executable examples, use the [interactive API Reference](https://docs.nosible.com/).