# Ipnops — service reference

> The interface behind Ipnops, for a reader who is going to call it directly. Ipnops puts AI to work across the tools a business already uses; these are the routes underneath the answering, research and watching it does. Every route returns typed, cited structure a model consumes directly: verified claims, evidence quotes, calibrated confidence — over a live-web index built for machines to read.

Base URL: `https://api.ipnops.ai`. Responses are JSON. Requests with a body are `application/json`.

## MCP server (the primary interface)

A Streamable-HTTP, stateless MCP server at `POST https://api.ipnops.ai/mcp`. One connector adds six typed tools to an MCP-native runtime:

- `ipnops_search` — hybrid retrieval over the live-web index
- `ipnops_answer` — one grounded answer as typed data
- `ipnops_extract` — fetch and extract a URL into clean structured text
- `ipnops_research` — start an async deep-research run
- `ipnops_research_status` — poll a research run
- `ipnops_monitor` — manage standing queries

Each tool ships an `outputSchema`; results arrive as `structuredContent`, not text to re-parse.

Connector config:

```json
{ "ipnops": { "transport": "http", "url": "https://api.ipnops.ai/mcp" } }
```

## POST /search

Hybrid retrieve over the live-web index: a lexical arm and a dense semantic arm, fused and reranked. Returns typed highlights, each self-citing its source passage.

Fields:
- `query` (string, required) — the search query (1–1000 chars)
- `topK` (number, optional) — highlights to return (1–50)

Response shape:

```json
{
  "highlights": [
    { "text": "…passage…", "score": 0.91, "source": { "url": "…" } }
  ],
  "arms": { "lexical": true, "dense": true, "reranked": true }
}
```

## POST /answer

Consolidates highlights into one grounded answer. The response is the agent-native shape: marker-per-claim citations, a `claims` array with per-claim verdicts and evidence quotes, one calibrated `confidence` scalar, and a `sufficiency` verdict.

Fields:
- `query` (string, required) — the question (1–1000 chars)
- `topK` (number, optional) — highlights to synthesize over (1–20)
- `forceEscalate` (boolean, optional) — skip the floor rung, use the flagship reasoner

Response shape:

```json
{
  "answer": "… [1] … [2]",
  "citations": [{ "marker": 1, "url": "…", "text": "…" }],
  "claims": [
    { "text": "…", "verdict": "supported", "quotes": ["…"], "grounded": true }
  ],
  "confidence": 0.84,
  "sufficiency": "supported",
  "conflicts": [],
  "grounding": "own-index",
  "tier": "floor"
}
```

- `grounding` is one of `own-index`, `web`, `places`, or `none` — the reach ladder falls through in that order and never fabricates when it misses.
- `sufficiency` is `supported`, `conflicting` (sources disagree — see `conflicts`), or `insufficient` (treat the answer as an abstain).

## POST /research

Deep research as a durable async run. Returns a `run_id` immediately (HTTP 202); the engine then iterates — answer, find the claims it couldn't ground, crawl the gap, re-answer — checkpointing every step. The run survives restarts; pages crawled along the way stay in the index.

Fields:
- `query` (string, required) — the research question (1–1000 chars)
- `webhookUrl` (string url, optional) — POSTed the terminal run state when the run closes
- `maxIterations` (number, optional) — answer→crawl→re-answer cycles (1–3, default 3)

Observing a run:
- `GET /research/:id` — poll current state
- `GET /research/:id/events` — SSE stream; resumes from `Last-Event-ID`; events: started → iteration → gap → crawl → completed
- `POST /research/:id/cancel` — cooperative cancel

The terminal `result` is the same AnswerResult shape as `/answer`, plus `iterations` and `pagesIndexed`.

## POST /monitor

A standing query with a webhook. Each sweep re-answers the query and diffs the grounded claim set against the last snapshot — a deterministic normalized-text comparison, zero extra model calls. The webhook fires only when the facts change: rephrasing is silence, a new number is a signal.

Fields:
- `query` (string, required) — the watched question (1–1000 chars)
- `webhookUrl` (string url, optional) — POSTed the claim diff + new answer on change

Routes:
- `POST /monitor` — register → 201 `{ monitor_id }`
- `GET /monitor` — list
- `GET /monitor/:id` — one monitor + last snapshot
- `DELETE /monitor/:id`
- `POST /monitor/run` — the cron target: sweep + diff

Webhook payload on change:

```json
{
  "monitor_id": "mon_9b2e…",
  "diff": { "addedClaims": ["…"], "removedClaims": ["…"], "confidenceDelta": -0.05 },
  "answer": "… [1]",
  "citations": ["…"],
  "confidence": 0.81
}
```

## POST /index/seed

Grow the index. Pass exactly one of `seed` (crawl one domain) or `query` (fan a free-text query across the discovery ladder and crawl what it finds).

Fields:
- `seed` (string url) — crawl one explicit domain, mutually exclusive with `query`
- `query` (string) — fan out a free-text query and crawl discovered URLs
- `maxPages` (number, optional) — page cap per crawl (1–200)
- `maxSeeds` (number, optional) — discovered URLs to crawl for a query seed (1–50)
- `purge` (boolean, optional) — drop the index before crawling (clean reseed)

## Health & admin

- `GET /healthz` — liveness probe; returns `{ "status": "ok" }`
- `GET /readyz` — readiness; reports sidecar + reasoner liveness

## Enterprise / sovereign data

Ipnops is a managed service. For enterprises and sovereign data owners, the same engine ships as an enterprise deployment inside your own environment: index, hybrid retrieval, reranking, and the verification gate run where the data lives, and synthesis can point at your own model endpoint. Contact: enterprise@ipnops.ai.