HTTP API¶

This reference is generated at build time from FastAPI's OpenAPI document. Its endpoint inventory, parameters, request and response types, validation constraints, status codes, and component schemas come directly from route metadata, docstrings, and type hints.

Bearer authentication is required unless an operation is marked public. Write-scoped routes are also marked 🔒. See Authentication for token configuration and scope semantics. The server binds to 127.0.0.1:8000 by default.

The ingest workflow also has a task-oriented contract in the Upstream ingest API; that guide adds retry, idempotency, and integration advice around the generated wire reference below.

Endpoint map¶

POST   /v1/pages                            Ingest a page  🔒
POST   /v1/pages/batch                      Ingest up to 100 pages  🔒
POST   /v1/pages/status/batch               Fetch status for up to 500 pages
GET    /v1/pages/{page_id}                  Fetch a page
GET    /v1/pages/{page_id}/chunks           List a page's indexed chunks
GET    /v1/pages/{page_id}/status           Page indexing status
GET    /v1/jobs                             List jobs
POST   /v1/jobs/retry                       Retry dead jobs in bulk  🔒
POST   /v1/jobs/{job_id}/retry              Retry a dead job  🔒
POST   /v1/search                           Search the reading history
POST   /v1/search/batch                     Search many queries in one call
GET    /v1/pages/{page_id}/similar          Pages similar to a page
POST   /v1/feedback                         Record relevance feedback
POST   /v1/forget                           Purge and blacklist a URL or domain  🔒
GET    /v1/blacklist                        List blacklist rules
DELETE /v1/blacklist/{blacklist_id}         Remove a blacklist rule  🔒
GET    /v1/clusters                         List reading-topic clusters
GET    /v1/clusters/runs                    List clustering runs
GET    /v1/clusters/projection              Read a run's two-dimensional page projection
GET    /v1/clusters/{cluster_id}            A cluster's label, keywords, and member pages
POST   /v1/clusters/recompute               Trigger a cluster run  🔒
GET    /v1/entities/{ref}                   Look up an entity
GET    /v1/pages/{page_id}/entities         Entities mentioned on a page
POST   /v1/entities/merges/{merge_id}/undo  Undo an entity merge (LIFO only)  🔒
GET    /v1/models/{model_id}/backfill       Read model backfill progress
POST   /v1/models/{model_id}/backfill       Estimate or start a backfill  🔒
GET    /v1/models                           List embedding models
POST   /v1/models                           Register an embedding model  🔒
POST   /v1/models/{model_id}/activate       Make this the active search model  🔒
DELETE /v1/models/{model_id}                Retire a model and drop its vector space  🔒
POST   /v1/compare                          Compare embedding models on one query
GET    /v1/watches                          List watches
POST   /v1/watches                          Create a watch  🔒
GET    /v1/watches/{watch_id}               Get a watch
PATCH  /v1/watches/{watch_id}               Update a watch  🔒
DELETE /v1/watches/{watch_id}               Delete a watch  🔒
POST   /v1/watches/{watch_id}/run           Poll a watch now  🔒
GET    /v1/events                           Stream job status changes (SSE)
GET    /v1/admin/metrics/timeseries         Read metric history
GET    /v1/admin/metrics/summary            Typed operational canaries
GET    /v1/admin/query-log                  List query-log runs
GET    /v1/admin/query-log/{query_id}       Read one query-log run
POST   /v1/admin/eval/score                 Score logged runs
POST   /v1/admin/eval/replay                Enqueue a live eval replay  🔒
GET    /v1/admin/eval/replay/{job_id}       Poll a live eval replay
GET    /v1/admin/config                     Read effective configuration
GET    /v1/admin/mcp                        Inspect mounted MCP tools
GET    /v1/whoami                           Identify caller
GET    /metrics                             Read Prometheus metrics
GET    /healthz                             Check process liveness
GET    /readyz                              Check service readiness

Endpoint details¶

Pages¶

POST /v1/pages — Ingest a page 🔒¶

Add a page the user read to the index. body_extracted and body_html are mutually exclusive; when neither is given the URL is fetched asynchronously. Known canonical URLs record a revisit instead. Operation ID: add_page · Required scope: write

Request body¶

Required.

Responses¶

POST /v1/pages/batch — Ingest up to 100 pages 🔒¶

Validate and ingest each page independently. Results preserve input order; malformed or blacklisted items do not prevent other items. Operation ID: add_pages_batch · Required scope: write

Request body¶

Required.

Responses¶

POST /v1/pages/status/batch — Fetch status for up to 500 pages¶

Return one status per distinct requested page id. Unknown ids are reported with found=false instead of failing the batch. Operation ID: page_status_batch · Required scope: read

Request body¶

Required.

Responses¶

GET /v1/pages/{page_id} — Fetch a page¶

Return the full stored body text and metadata of one page from the user's reading history. Operation ID: get_page · Required scope: read

Parameters¶

Responses¶

GET /v1/pages/{page_id}/chunks — List a page's indexed chunks¶

Return chunk text and body offsets in ordinal order. Operation ID: get_page_chunks · Required scope: read

Parameters¶

Responses¶

GET /v1/pages/{page_id}/status — Page indexing status¶

Return the indexing lifecycle status of a page. Operation ID: page_status · Required scope: read

Parameters¶

Responses¶

Jobs¶

GET /v1/jobs — List jobs¶

List jobs newest first, optionally filtered by status and kind.

status_filter is a deprecated compatibility alias for status; a request that supplies both is rejected. Operation ID: list_jobs · Required scope: read

Parameters¶

Responses¶

POST /v1/jobs/retry — Retry dead jobs in bulk 🔒¶

Retry dead jobs either by explicit job_ids (up to 500, deduped, results in input order) or by selector (all dead jobs, optionally filtered by kind, up to limit). Non-dead jobs are reported as skipped and unknown ids as not_found; the call is idempotent — a second selector call finds nothing left to retry. Always returns 200. Operation ID: retry_jobs_batch · Required scope: write

Request body¶

Required.

Responses¶

POST /v1/jobs/{job_id}/retry — Retry a dead job 🔒¶

Reset a dead job to pending and re-enqueue it; other states return 409.

Retrying an index job also resets its page from dead back to queued, so page status tracks the re-enqueued work. Operation ID: retry_job · Required scope: write

Parameters¶

Responses¶

Search¶

POST /v1/search — Search the reading history¶

Hybrid semantic + keyword search over pages the user has read. Returns grounded passages from the user's own reading history. Contains no information the user has not read. Returns an empty result when nothing matches. An entity filter that resolves to no known entity returns 404 so a bad reference is distinguishable from a genuine zero. Operation ID: search · Required scope: read

Request body¶

Required.

Responses¶

POST /v1/search/batch — Search many queries in one call¶

Run up to 20 queries sequentially with shared parameters (sequential on purpose: it respects embedding provider rate limits, like model comparison does). Each item gets its own query_id and query-log row, so feedback and evaluation join per query. Per-item failures are reported inline as outcome='error' items; the call itself stays 200. Operation ID: search_batch · Required scope: read

Request body¶

Required.

Responses¶

GET /v1/pages/{page_id}/similar — Pages similar to a page¶

Rank other pages from the user's reading history by similarity to this one. Returns grounded results from the user's own reading history only. Operation ID: similar_to · Required scope: read

Parameters¶

Responses¶

POST /v1/feedback — Record relevance feedback¶

Append feedback; unknown query_ids are accepted (eval join drops them). Operation ID: record_feedback · Required scope: read

Request body¶

Required.

Responses¶

Forget¶

POST /v1/forget — Purge and blacklist a URL or domain 🔒¶

Permanently remove matching pages from the index and blacklist the pattern so future ingests are rejected. This deletes user data; removal of the blacklist rule later does not restore content. Operation ID: forget · Required scope: write

Request body¶

Required.

Responses¶

GET /v1/blacklist — List blacklist rules¶

All rules, newest first. Operation ID: list_blacklist · Required scope: read

Responses¶

DELETE /v1/blacklist/{blacklist_id} — Remove a blacklist rule 🔒¶

Future ingests are allowed again; purged content stays purged. Operation ID: unblacklist · Required scope: write

Parameters¶

Responses¶

Clusters¶

GET /v1/clusters — List reading-topic clusters¶

Topic clusters discovered over the user's reading history. Returns grounded results derived only from pages the user has read. Operation ID: list_clusters · Required scope: read

Parameters¶

Responses¶

GET /v1/clusters/runs — List clustering runs¶

Return persisted clustering history newest first. Operation ID: list_cluster_runs · Required scope: read

Parameters¶

Responses¶

GET /v1/clusters/projection — Read a run's two-dimensional page projection¶

Return page coordinates for a persisted clustering run. Operation ID: cluster_projection · Required scope: read

Parameters¶

Responses¶

GET /v1/clusters/{cluster_id} — A cluster's label, keywords, and member pages¶

Member pages of one topic cluster from the user's reading history. Tombstoned clusters remain resolvable by id. Operation ID: cluster_pages · Required scope: read

Parameters¶

Responses¶

POST /v1/clusters/recompute — Trigger a cluster run 🔒¶

Enqueue a manual run; 409 when one is already in flight. Operation ID: recompute_clusters · Required scope: write

Responses¶

Entities¶

GET /v1/entities/{ref} — Look up an entity¶

Resolve an entity by id, canonical form, or alias (references survive merges). Returns aliases and the user's pages mentioning it — grounded in the reading history only. Operation ID: entities · Required scope: read

Parameters¶

Responses¶

GET /v1/pages/{page_id}/entities — Entities mentioned on a page¶

Entities linked to one page. Operation ID: page_entities · Required scope: read

Parameters¶

Responses¶

POST /v1/entities/merges/{merge_id}/undo — Undo an entity merge (LIFO only) 🔒¶

Restore a merged entity from its snapshot. Operation ID: undo_entity_merge · Required scope: write

Parameters¶

Responses¶

Models¶

GET /v1/models/{model_id}/backfill — Read model backfill progress¶

Return durable progress for a model's corpus backfill. Operation ID: get_model_backfill · Required scope: read

Parameters¶

Responses¶

POST /v1/models/{model_id}/backfill — Estimate or start a backfill 🔒¶

confirm=false returns an exact dry-run estimate (chunk token counts are stored); confirm=true starts the durable, resumable backfill. Operation ID: backfill_model · Required scope: write

Parameters¶

Request body¶

Required.

Responses¶

GET /v1/models — List embedding models¶

All registered models. Operation ID: list_models_api · Required scope: read

Responses¶

POST /v1/models — Register an embedding model 🔒¶

Register (not active, no vectors yet). Rejected below the chunk budget. Operation ID: register_model · Required scope: write

Request body¶

Required.

Responses¶

POST /v1/models/{model_id}/activate — Make this the active search model 🔒¶

Atomic flip; only ready models can be activated. Operation ID: activate_model · Required scope: write

Parameters¶

Responses¶

DELETE /v1/models/{model_id} — Retire a model and drop its vector space 🔒¶

409 when active; drops the vector space and page vectors. Operation ID: retire_model · Required scope: write

Parameters¶

Responses¶

Compare¶

POST /v1/compare — Compare embedding models on one query¶

Runs the full retrieval pipeline once per model; the sparse arm and reranker are identical across arms, so the delta isolates the embedder. Returns per-model rankings over the user's reading history plus agreement statistics (Jaccard@k, RBO, Kendall's tau). Operation ID: compare · Required scope: read

Request body¶

Required.

Responses¶

Watches¶

GET /v1/watches — List watches¶

All watches with their schedules and last-poll health (status, error, item count). Operation ID: list_watches · Required scope: read

Responses¶

POST /v1/watches — Create a watch 🔒¶

Register a URL to poll on a schedule (default every 24 hours). Each poll discovers the source's current item URLs and ingests the new ones, so they become searchable. Kind 'rss' polls an RSS/Atom feed; kind 'youtube' polls a YouTube playlist or channel and ingests each video's transcript (single videos go to add_page instead); kind 'podcast' polls a podcast RSS feed and ingests each episode's audio enclosure as a local Whisper transcript (requires a transcription extra). Already-indexed and blacklisted items are skipped automatically. The first poll runs within a minute of creation. Operation ID: create_watch · Required scope: write

Request body¶

Required.

Responses¶

GET /v1/watches/{watch_id} — Get a watch¶

One watch with its schedule and last-poll health. Operation ID: get_watch · Required scope: read

Parameters¶

Responses¶

PATCH /v1/watches/{watch_id} — Update a watch 🔒¶

Partially update a watch: pause/resume with 'enabled', change the poll interval, title, or per-kind config. Omitted fields are left unchanged; the URL is immutable (delete and recreate instead). Changing the interval reschedules the next poll from the last run. Operation ID: update_watch · Required scope: write

Parameters¶

Request body¶

Required.

Responses¶

DELETE /v1/watches/{watch_id} — Delete a watch 🔒¶

Stop polling this source. Pages already ingested by the watch stay indexed; use forget to remove content. Operation ID: delete_watch · Required scope: write

Parameters¶

Responses¶

POST /v1/watches/{watch_id}/run — Poll a watch now 🔒¶

Enqueue an immediate poll instead of waiting for the schedule; the next scheduled poll moves to one interval from now. Returns the poll job id; track it via the jobs API. Operation ID: run_watch · Required scope: write

Parameters¶

Responses¶

Events¶

GET /v1/events — Stream job status changes (SSE)¶

A text/event-stream of job ledger transitions. Opens with a snapshot event carrying the current job list (same shape as GET /v1/jobs), then one job event per status change (pending, running, done, failed, dead), with : keep-alive comments between events. Returns 503 when the subscriber limit is reached. Authenticate with the normal bearer header (fetch-based SSE); query-string tokens are not supported. Operation ID: stream_events · Required scope: read

Responses¶

Admin¶

GET /v1/admin/metrics/timeseries — Read metric history¶

Read historical rollups plus current gauge values for one metric. Operation ID: admin_metrics_timeseries · Required scope: read

Parameters¶

Responses¶

GET /v1/admin/metrics/summary — Typed operational canaries¶

One JSON snapshot of operational health: job-ledger counts, vector tombstone backlog, dropped observability rows, provider error counters, search latency quantiles, and circuit breaker states. Counter-derived fields are process-lifetime totals that reset on restart; since bounds the latency window only. Operation ID: admin_metrics_summary · Required scope: read

Parameters¶

Responses¶

GET /v1/admin/query-log — List query-log runs¶

List retrieval traces newest first, optionally filtered by time and kind.

Each trace includes candidate, dense, sparse, and final hit sets, per-stage timing, and the latest relevance feedback. The default limit is 100 and the maximum is 1,000. Operation ID: admin_query_log · Required scope: read

Parameters¶

Responses¶

GET /v1/admin/query-log/{query_id} — Read one query-log run¶

Return one full retrieval trace with rankings, timing, and feedback. Operation ID: admin_query_log_detail · Required scope: read

Parameters¶

Responses¶

POST /v1/admin/eval/score — Score logged runs¶

Score logged rankings synchronously without calling external providers. Operation ID: admin_eval_score · Required scope: read

Request body¶

Required.

Responses¶

POST /v1/admin/eval/replay — Enqueue a live eval replay 🔒¶

Enqueue a durable two-arm replay that may call paid model providers.

The response is a 202 with a job ID and result URL. Polling the result needs only read scope; the report or failure survives process restarts. Operation ID: admin_eval_replay · Required scope: write

Request body¶

Required.

Responses¶

GET /v1/admin/eval/replay/{job_id} — Poll a live eval replay¶

Read durable replay status, its completed report, or terminal failure. Operation ID: admin_eval_replay_result · Required scope: read

Parameters¶

Responses¶

GET /v1/admin/config — Read effective configuration¶

Return effective settings with secrets redacted recursively.

Every setting is marked boot_only because runtime mutation is not supported. Operation ID: admin_config · Required scope: read

Responses¶

GET /v1/admin/mcp — Inspect mounted MCP tools¶

Return actual mounted tool metadata and mutating-tool visibility. Operation ID: admin_mcp · Required scope: read

Responses¶

Auth¶

GET /v1/whoami — Identify caller¶

Return the authenticated token name and its effective scopes. Operation ID: whoami · Required scope: read

Responses¶

Health¶

GET /metrics — Read Prometheus metrics¶

Return the Prometheus text exposition for authenticated scrapers. Operation ID: metrics · Required scope: read

Responses¶

GET /healthz — Check process liveness¶

Return success when the API process is running. No authentication. Operation ID: healthz · Required scope: public

Responses¶

GET /readyz — Check service readiness¶

Check that the metadata store is reachable and an embedding model is active. Returns 503 until both conditions hold. No authentication. Operation ID: readyz · Required scope: public

Responses¶

Schemas¶

AdminConfigResponse¶

BackfillEstimateResponse¶

Dry-run estimate (confirm=false).

BackfillRequest¶

POST /v1/models/{id}/backfill body.

BackfillStartedResponse¶

202-style acknowledgement (confirm=true).

BlacklistEntry¶

One blacklist rule.

BlacklistKind¶

Whether a blacklist rule matches a URL exactly or a domain suffix.

Type: "url" | "domain"

BlacklistResponse¶

GET /v1/blacklist response.

BlacklistedResponse¶

403: URL matches a blacklist rule.

BreakerStateSummary¶

ChunkResult¶

One matched chunk, whole text.

ClusterDetailResponse¶

GET /v1/clusters/{id} response.

ClusterListResponse¶

GET /v1/clusters response.

ClusterMemberPage¶

A page inside a cluster.

ClusterProjectionPointResponse¶

A page point in a clustering run's display projection.

ClusterProjectionResponse¶

GET /v1/clusters/projection.

ClusterRef¶

Cluster membership shown on a result (populated from M4).

ClusterRunResponse¶

One persisted clustering run.

ClusterRunsResponse¶

GET /v1/clusters/runs.

ClusterSummary¶

One cluster.

CompareAgreement¶

Agreement stats for one model pair.

CompareModelRun¶

One model's ranking.

CompareRequest¶

POST /v1/compare body.

CompareResponse¶

POST /v1/compare response.

ComparedPage¶

One ranked page in a compare arm.

CreateWatchRequest¶

POST /v1/watches body.

EntityDetailResponse¶

GET /v1/entities/{ref} response.

EntitySummary¶

One canonical entity.

EvalReplayAcceptedResponse¶

EvalReplayRequest¶

EvalReplayResultResponse¶

EvalScoreRequest¶

FeatureStatus¶

Status of an asynchronous enrichment feature for a page.

FeedbackRequest¶

POST /v1/feedback body.

ForgetRequest¶

POST /v1/forget body: exactly one of url/domain.

ForgetResponse¶

POST /v1/forget response.

HTTPValidationError¶

IngestAcceptedResponse¶

202: new page queued.

IngestBatchAcceptedResult¶

A newly queued item in an ingest batch.

IngestBatchBlacklistedResult¶

A blacklisted item in an ingest batch.

IngestBatchRejectedResult¶

An independently invalid item in an ingest batch.

IngestBatchRequest¶

POST /v1/pages/batch envelope.

Items remain unvalidated here so one malformed page does not reject the otherwise valid envelope. The route validates each item independently.

IngestBatchResponse¶

POST /v1/pages/batch response in input order.

IngestBatchRevisitResult¶

A revisit item in an ingest batch.

IngestPageRequest¶

POST /v1/pages body.

IngestRevisitResponse¶

200: canonical URL already known.

JobKind¶

Kinds of durable jobs the queue executes.

Type: "index_page" | "fetch_and_index" | "extract_entities" | "backfill_model" | "cluster" | "label_clusters" | "canonicalize_entities" | "purge_vectors" | "eval_replay" | "poll_watch"

JobListResponse¶

GET /v1/jobs.

JobResponse¶

Job ledger row (admin surface).

JobRetryBatchMissingResult¶

An unknown job id.

JobRetryBatchRequest¶

POST /v1/jobs/retry body: explicit ids or a dead-job selector.

JobRetryBatchResponse¶

POST /v1/jobs/retry response in input/selection order.

JobRetryBatchRetriedResult¶

A job that was reset to pending and re-enqueued.

JobRetryBatchSkippedResult¶

A job skipped because it is not dead.

JobStatus¶

Ledger status of a durable job.

Type: "pending" | "running" | "done" | "failed" | "dead"

JobsSummary¶

JsonValue¶

Type: object

LoggedHitResponse¶

LoggedPageResponse¶

McpAdminResponse¶

McpToolResponse¶

Mediation¶

What mediates 'similar': vectors, cluster co-membership, or entities.

Type: "vector" | "cluster" | "entity"

MetricPointResponse¶

MetricSeriesResponse¶

MetricsSummaryResponse¶

MetricsTimeseriesResponse¶

ModelBackfillResponse¶

GET /v1/models/{id}/backfill.

ModelInfo¶

One registered embedding model.

ModelListResponse¶

GET /v1/models response.

ModelReport¶

Mean metrics over one model's scored runs.

PageChunkResponse¶

One stored chunk with its position in the page body.

PageChunksResponse¶

GET /v1/pages/{id}/chunks.

PageEntitiesResponse¶

GET /v1/pages/{id}/entities response.

PageResponse¶

GET /v1/pages/{id}.

PageResult¶

One ranked page.

PageStatus¶

Lifecycle of a page through the indexing pipeline.

Type: "queued" | "indexing" | "indexed" | "failed" | "dead"

PageStatusBatchFoundResult¶

Status for a page known to the server.

PageStatusBatchMissingResult¶

Status result for an unknown or expired page id.

PageStatusBatchRequest¶

POST /v1/pages/status/batch envelope.

PageStatusBatchResponse¶

POST /v1/pages/status/batch response.

PageStatusFeatures¶

Nested enrichment feature state.

PageStatusResponse¶

GET /v1/pages/{id}/status.

QueryLogListResponse¶

QueryLogRunResponse¶

QueryScore¶

Metrics for one logged run.

RecomputeResponse¶

POST /v1/clusters/recompute response.

RegisterModelRequest¶

POST /v1/models body.

RollupStrategy¶

How chunk scores pool into a page score.

No magic-number bonuses in v1: rerankers are calibrated, and arbitrary boosts would destroy their ranking. A bonus variant may be added later only if eval proves lift.

Type: "max" | "mean_top_m" | "sum_rrf"

ScoreReport¶

Everything eval score emits.

SearchBatchErrorResult¶

One batch query that failed with a per-item (non-fatal) error.

SearchBatchOkResult¶

One successful batch query with its full search response.

SearchBatchRequest¶

POST /v1/search/batch body: shared params + up to 20 query strings.

SearchBatchResponse¶

POST /v1/search/batch response in input order.

SearchFiltersBody¶

First-class search filters.

SearchLatencySummary¶

SearchRequest¶

POST /v1/search body.

SearchResponse¶

POST /v1/search response.

SimilarResponse¶

GET /v1/pages/{id}/similar response.

SimilarResult¶

One similar page.

Suggestion¶

A related page appended to the response.

TombstoneBacklogSummary¶

UndoMergeResponse¶

POST /v1/entities/merges/{id}/undo response.

UpdateWatchRequest¶

PATCH /v1/watches/{watch_id} body; omitted fields stay unchanged.

url is immutable: it is the watch's dedup identity — delete and recreate to point a watch elsewhere.

ValidationError¶

WatchKind¶

Kinds of pull sources a watch can poll.

Type: "rss" | "youtube" | "podcast"

WatchListResponse¶

GET /v1/watches response.

WatchResponse¶

One watch with its schedule and last-poll health.

WatchRunAcceptedResponse¶

POST /v1/watches/{watch_id}/run response (202).

WatchStatus¶

Outcome of a watch's most recent poll.

Type: "pending" | "ok" | "error"

WhoAmIResponse¶

Authenticated token identity and effective scopes.

Related¶

• Upstream ingest API — ingest semantics, revisit behavior, and integration guidance.
• Python API → Services — the application objects behind these routes.
• Observability — metrics, tracing, and query-log operations.