Kagi Search API Migration: Test Related Searches and Preserved Links

What Kagi documented

Kagi’s July 30, 2026 changelog says document extraction retains original links for deeper crawling workflows and API responses include related searches, with more metadata than the earlier API where applicable. The same entry says per-key cost tracking begins from deployment and has no historical data, and describes extraction reliability and personalization validation changes.

The durable engineering question is not whether two fields exist. It is whether your collector, normalizer, cache, evidence export and UI can accept the current response without losing unknown types, provenance or link relationships.

Confirm the version boundary first

Kagi’s Search API documentation shows the current v1 search endpoint and describes v0 as legacy. It also says API results inherit account settings such as personalization and snippet length. Record the endpoint, query parameters, account or key identity, relevant settings, client version and timestamp in every fixture. “Same query” is not a reproducible condition when account settings differ.

Do not infer an exact JSON schema from a changelog sentence. Capture an authorized response from your own key, compare it with the current Kagi API reference, and pin that observed contract in a redacted fixture.

Keep three layers of evidence

A screenshot is useful for the rendered layer but cannot replace the raw response. Conversely, raw JSON does not prove the production interface surfaced a related search or preserved a link for the reviewer.

Build a frozen query fixture

1. Select queries representing factual, navigational, commercial, current, empty-result and extraction-heavy intents.
2. Record exact query text, locale, endpoint, parameters, account settings and collection time.
3. Save the complete response after removing keys, tokens and personal data.
4. Replay that response against both old and candidate parsers.
5. Compare result counts, types, URLs, snippets, related queries, preserved links and warnings.
6. Render the candidate output and review it with the people who use the evidence.

The fixture should include zero values and absent fields. A parser tested only on rich responses will often confuse “not returned,” an empty array and a collector failure.

Model related searches as their own type

A related search is not an ordinary ranked result. Store its text, position, parent query, raw type identifier and any documented metadata separately. Do not assign it the rank of the result next to it or count it as a cited source.

For editorial research, related searches can expand a query plan, but they remain suggestions generated by the search product. They do not establish demand, importance, correctness or coverage. Require a human or documented rule to promote one into the next search round.

Preserve link identity and context

When extraction keeps links from the source document, retain more than the destination URL. Store the original href, resolved URL, anchor text, enclosing passage or selector where permitted, source-document URL, extraction timestamp and resolution status. Keep fragments and query parameters in the raw layer even if a normalized URL is created for grouping.

A redirect-resolved URL is useful for deduplication but can erase evidence about affiliate parameters, document fragments or the path displayed in the source. Preserve raw and normalized forms side by side.

Do not crawl every preserved link automatically

Link preservation makes deeper crawling possible; it does not make every destination safe or authorized. Apply scheme allowlists, private-network protections, redirect limits, content-size limits, robots and access rules appropriate to your system. Record whether a link was observed, selected, fetched, blocked or failed.

Do not send credentials or Kagi authorization headers to extracted destinations. A search response and a subsequent crawl are separate network operations with separate permissions and logs.

Make the parser strict about essentials and tolerant about additions

Validate required transport properties and the fields your product truly depends on. Preserve or log unknown result types instead of crashing the entire response. Treat unexpected nulls, scalar/object changes and malformed URLs as explicit parser outcomes.

Freeze account settings and cost attribution

Kagi says Search API results inherit account settings. A parser migration test should therefore freeze or record personalization and snippet-length configuration. Our Kagi personalization reproducibility guide provides the complementary observation schema.

If you use per-key cost reporting, respect the changelog boundary: Kagi says tracking is available from deployment and has no historical data. Do not backfill a zero and call it historical spend. Record “unavailable before deployment” and reconcile request logs only for the period in which both sources exist.

Run an old-parser/new-parser acceptance test

1. Replay the same redacted raw responses into both parser versions.
2. Compare counts by result type, not only total objects.
3. Diff original, normalized and resolved URLs.
4. Verify related searches appear in a separate collection and retain parent-query identity.
5. Verify preserved links remain attached to the correct extracted document and passage.
6. Render representative records and inspect keyboard, wrapping and long-URL behavior.
7. Inject unknown types, missing arrays, null values, malformed URLs and oversized documents.
8. Canary the collector with a rollback path and monitor parse errors and cost.

Use the evidence-object audit to examine whether normalized objects remain traceable to the underlying source. A response that parses is not necessarily an evidence object a reviewer can verify.

Choose release criteria before the diff

Require zero loss of previously supported result types, explicit handling of new types, preservation of raw responses, stable parent-child joins for related queries, resolvable link provenance, acceptable render behavior, and no unexplained request or cost increase. Document permitted differences—for example, a new related-search collection—before examining the output.

Keep a rollback-compatible storage version. If the candidate parser writes destructive normalized records into the only data store, rollback will not restore what it discarded.

Migration checklist

• Pin v1 endpoint, client and observed schema date.
• Freeze queries, parameters and account settings.
• Retain redacted raw responses before normalization.
• Separate related suggestions from ranked results.
• Keep original, resolved and normalized link forms.
• Block unsafe downstream fetches and credential forwarding.
• Handle unknown types without discarding the response.
• Test empty, malformed, oversized and retry cases.
• Canary with parse, latency and cost monitoring.

What this migration does not prove

A successful parser test does not prove Kagi’s results are more relevant, complete or factual. Related searches do not prove query demand. Preserved links do not prove the linked pages support a claim. Evaluate retrieval quality and claim support in a separate, repeated test.

Search Engine Answer has not run a Kagi API migration test with a production key for this article. The fixture describes what to capture; it is not a benchmark result.

Sources, method and limits

Sources: Kagi’s July 30, 2026 changelog, Search API help page and current API reference, retrieved August 31, 2026.

Method: We translated the documented feature and version changes into a layered evidence model, migration fixture, parser-failure matrix and acceptance test.

Limits: Exact response fields can vary by endpoint, result type, account setting and future release. The official interactive reference and an authorized response from your environment are the contract to test. Never place an API token in a fixture or support ticket.