Capture a URL into the Khiip substrate.

Dispatches to the appropriate extractor (X, Reddit, web article, Wikipedia, YouTube, PDF). Stores raw source bytes at Source-tier plus a typed payload in the vault. Submits to Wayback Machine unless disabled. Idempotent by default (dedup by URL hash).

Args: url: The URL to capture. force_new: If True, skip dedup-by-url and force creation of a new capture (overrides the existing capture's superseded_by pointer). Defaults to False.

Returns: Capture record (id, source, vault_path, payload, archive_urls, etc.) on success; structured error dict on failure.

Semantic recall over captured payloads by natural-language query.

Ranks captures by cosine similarity over typed-payload embed-text composition (per ADR-0009 §C7). Returns top-k captures with their scores.

Args: query: Natural-language recall query. limit: Maximum number of results to return (1-100; default 10).

Returns: Recall response with query, embedder_model, embedder_dimension, and results (list of {capture, score}).

List captures, newest first.

Args: source: Optional filter by source name (x, reddit, web, wikipedia, youtube, pdf). When None, returns all sources. limit: Page size (1-500; default 50). offset: Pagination offset.

Returns: On success: {"captures": [Capture, ...], "count": int}. On failure: structured error dict.

Fetch a single capture by id, in the requested format.

Args: capture_id: The capture ULID. format: One of json (default; payload as JSON), markdown (vault markdown), vault-frontmatter (YAML frontmatter only), or legacy-markdown (pre-typed-payload format).

Returns: On success: payload in the requested format wrapped in a {"format": ..., "body": ...} envelope. On failure: structured error dict.

Refetch one dimension of an existing capture.

Dimensions, per ADR-0010 commitment 6 + ADR-0009 §C2 replay (S42):

• extraction (default): NETWORK re-fetch → new capture, old marked superseded (can observe a changed/deleted post).

• re-extract: OFFLINE — re-derive the typed payload from the preserved source bytes with the current extractor (recovers under-extracted fields; survives source deletion). In place; same capture id.

• re-render: OFFLINE — re-render the markdown body from the existing typed payload (apply an improved renderer / skin). In place.

• media: re-walk MediaFetcherRegistry on existing payload; updates Media[].download_status in place; same capture id.

• wayback: re-submit canonical URL to Wayback Save Page Now; updates archive_urls['wayback'] in place; same capture id.

Args: capture_id: The capture ULID to refetch. dimension: Which dimension to refetch (extraction | re-extract | re-render | media | wayback). Defaults to extraction.

Returns: Updated capture record on success; structured error dict on failure.

Combined daemon health + metadata.

Aggregates GET /health (extractor + wayback liveness) and GET /api/v1/meta (version, configured extractors, embedder model + dimension). Useful as a first call when an agent connects, to confirm the daemon is reachable and to learn what sources + capabilities are available.

Returns: On success: {"health": {...}, "meta": {...}, "mcp_server_version": "0.1.1"}. On daemon-unreachable: structured error dict.