Changelog
Notable Graphon Engine API changes, newest first.
Unreleased
Pages count from 1, and Read spans
Pages count from 1 in every FileSpan: the start and end of a pages span, and the pages of a chars span. Page 7 is {start: 7, end: 8}, and end is still the first unit after the span. chars, which count Unicode code points, and seconds still count from 0. A pages span that starts at 0 is 400 invalid_span. Search takes result_type in place of result_unit. Every search row has one shape: file_id, path, content_type, rank, score, and spans, and a passage row holds one span in spans. Answer and research sources is a list in ref order, in place of a map keyed by marker. Each source has ref, such as SRC:0001, and cited in place of is_cited. POST .../collections/{collection}:read-spans replaces :read-span. It reads 1 to 50 spans and returns one result for each span, in order. include names the parts: text (the default), raw, and file (the whole stored file). raw and file need the read action. The default is text, where :read-span returned raw. delivery inline (the default) returns binary parts as base64 data until the call reaches its inline limit, and signed URLs after that. delivery url returns signed URLs only. A span that cannot be read has error on its own result: not_found, invalid_span, or content_unavailable. The other spans still read. The text of an image is left out of the result, so invalid_representation is gone.
Unreleased
Config webhooks removed
Engine removes config webhooks (events.webhooks) and the X-Graphon-Events-Signature, -Timestamp, and -Delivery headers. Registered webhooks deliver every event. A cluster configuration that still sets events.webhooks, also to an empty list, fails GET /ready with details.failed ["events"], and the Engine log line names POST /webhooks. Before you upgrade, register each receiver with POST /webhooks, verify the Standard Webhooks headers, and remove events.webhooks from the configuration.
October 28, 2026
Deprecated query fields removed
The fields that the previous release kept for old clients are gone, and a request that sends one is 400 invalid_request. Search takes mode keyword or hybrid: the modes fast, standard and semantic, and the sort field, are gone. Answer takes effort (medium or high): its mode and web_search fields are gone. Research has no mode: send no mode, and use web_search on the research body. The Answer and Research responses have no mode, research.updated events have no data.mode, and GET /info has no query: read answer.efforts and search.modes instead. A research retry that still sends mode is 400, not a replay of the first run.
October 16, 2026
Registered webhooks, and config webhooks deprecated
Register a webhook with POST /webhooks, scoped like a key: the cluster, a namespace, or collections. Each webhook signs with Standard Webhooks headers, keeps a 30-day delivery log, and can replay. Config webhooks (events.webhooks) and the X-Graphon-Events-Signature, -Timestamp, and -Delivery headers are deprecated. They work as before in this release, and a later Engine release removes them. To move, register each receiver with POST /webhooks, verify the Standard Webhooks headers, and then remove its events.webhooks entry.