API Contracts

Rainer Krug

This article defines stable contracts for package workflows and machine-readable integrations.

Folder Contracts

Request/Parquet Workflow

• <project>/<endpoint>/json
• <project>/<endpoint>/parquet

Content/Abstract Workflow

• <project>/<endpoint>/content/query=<query>
• <project>/<endpoint>/markdown/query=<query>
• <project>/<endpoint>/abstract/query=<query>

Data Contracts

Base Parquet Corpus

Column	Type	Required	Notes
id	character	yes	Stable record key in endpoint output
query	character	yes	Query partition key
Title	character/nullable	endpoint-dependent	Present where source includes title
endpoint payload columns	mixed	endpoint-dependent	Schema depends on endpoint

Abstract Parquet

Column	Type	Required	Notes
id	character	yes	Join key
query	character	yes	Join key
abstract	character/nullable	yes	Lowercase column name
status	character	yes	Summarization status
error	character/nullable	no	Row-level error message

read_corpus(..., abstracts = TRUE)

Contract:

• Performs left join from base corpus to abstract parquet by id + query.
• If abstract data is missing, abstract is returned as NA.

Execution Contracts

• kagi_fetch() is the preferred high-level project workflow.
• kagi_request() + kagi_request_parquet() is the low-level path.
• kagi_request_parquet() performs JSON-to-parquet conversion only.

Error-Handling Contracts

• kagi_request(..., error_mode = "stop") Fail-fast mode.
• kagi_request(..., error_mode = "write_dummy") Continue mode with endpoint-compatible dummy payloads and warnings.

Stability Notes

• Constructor naming query_<endpoint> is stable in the current API generation.
• id + query join key and lowercase abstract are required integration invariants for corpus linking.