Changelog
Notable Graphon API changes and deprecations, newest first.
October 30, 2026
Datasets, and target replaces bucketId
A dataset is a read-only set of documents that Graphon curates and every workspace can query. List datasets (GET /v1/workspaces/{workspaceId}/datasets) and Get a dataset (GET /v1/workspaces/{workspaceId}/datasets/{datasetId}, by id or slug) return the catalog, with the access of your workspace. Search objects, Read spans, Answer a question, and Start research take one required target in place of bucketId: a bucket id (bkt…) or a dataset id (dst…). A body that sends bucketId returns 400 invalid_request. A query run returns target in place of bucketId. A paid dataset that your workspace has no access to returns 403 dataset_access_required. The MCP query tools take target in place of bucket, and the new list_datasets and get_dataset tools read the catalog. graphon search, ask, chat, read-spans, and research start take a bucket name or a dataset id as their first argument, and graphon datasets list and graphon datasets get read the catalog. Update the CLI, because an older one sends bucketId and gets 400.
October 29, 2026
Pages count from 1, and Read spans reads up to 50 spans
Pages count from 1 in every span: 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. Research runs and Playground sessions stored before this release count pages from 1 too. Search objects takes resultType in place of resultUnit, with the same values object and passage. graphon search takes --result-type in place of --unit. Read spans replaces Read a span: POST /v1/workspaces/{workspaceId}/read-spans, the read_spans MCP tool, and graphon read-spans. It reads 1 to 50 spans in one call and returns one result for each span, in order. include names the parts: text, raw (the span cut from the object in its own format), and object (the whole object version). The default is text, where Read a span returned raw. delivery inline (the default) returns binary parts as base64 data until the call reaches its inline limit, and links after that. delivery url returns links only. A span that cannot be read has an 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. The read_spans MCP tool returns an image as image content, audio as audio content, and other files as embedded resources. graphon read-spans takes --include and --delivery in place of --representation, and --spans reads many spans from a file.
October 26, 2026
Search modes are hybrid and keyword, and Answer stores nothing
Search takes mode hybrid (the default) or keyword. hybrid matches exact words and meaning together. keyword matches exact words only, such as an ID, a code, or an error message. A search that sends fast or standard returns 400 invalid_request. graphon search takes --mode hybrid or --mode keyword: update the CLI, because an older one sends fast or standard and gets 400. Answer a question takes no waitSeconds, and a request that sends it returns 400 invalid_request. It waits for the answer in the request, returns 200, and stores nothing, as Search does. The response has no id, no expiresAt, and no sourcePage, and a body that sends sourceLimit returns 400 invalid_request: sources picks all, cited, or no sources. graphon ask no longer takes --source-limit: update the CLI, because graphon ask of an older one sends sourceLimit and gets 400. A source whose object version was deleted keeps its place, with versionId and span null. Get research pages its sources with sourceCursor, the sourcesNextCursor of the last read, instead of sourceOffset. A run returns sourcesNextCursor instead of sourcePage, and a read that sends sourceOffset returns 400 invalid_request. graphon research get takes --source-cursor instead of --source-offset. When the answer fails, the call returns an error response, not a failed run. Answer a question starts no run, and a run has no mode field. An answer stored before this release stays readable through Get research until it expires: one day after it ended, or seven days when it was still working at this release.
October 25, 2026
Read a span takes a representation
Read a span takes representation: raw (the default) or text. The span says where, and representation says what form. raw returns the original content: a PDF of the pages of a PDF or an office file, the text of a text file or a mail, the image, or a clip. text returns the text of a document, or the speech of a video or a recording as transcript lines with times. A chars span of a PDF or an office file now returns a PDF of its pages by default: send representation text for its text. A pages span can return text, and a seconds span can return a transcript. The response span uses the unit of the content, and next is the body of the next read: the rest of the span with the same representation. An image has no text form and returns 400 invalid_representation. graphon read-span takes --representation.
October 23, 2026
Text matches in PDFs and office files carry their pages
A text match in a PDF or an office file is a chars span with pages inside it: the pages that its chars cover, from 0, without end itself. A section or a figure is still a pages span. Search results, answer and run sources, and Read a span return pages on these spans. Send a span back to Read a span with its pages or without them. Pages that do not match the chars return 400 invalid_span.
October 23, 2026
Spans replace locations and snippets
A search result holds spans, and an answer or run source holds a span, in place of locations with a snippet. A span names an object version and a place in it: pages, chars, or seconds from start to end, without end itself, or the whole file. A span holds no text. The new Read a span call (POST /v1/workspaces/{workspaceId}/read-span, the read_span MCP tool, and graphon read-span) returns its content: the text of a text file or a mail, or a link to a PDF of only those pages, to the image, or to a clip of the span. graphon search has no --snippet option. Runs stored before this release were deleted, and Playground sessions keep their composer without their turns.
October 22, 2026
Research takes no mode
Start research takes no mode field. A research request that sends mode returns 400 invalid_request. Every research run reads the bucket in depth, and Get research shows it with mode ultra. graphon research start has no --mode option, and the start_research MCP tool takes no mode. A question that asks for every match goes to research, not to Answer a question.
October 21, 2026
Pages count from 0
The page in a search result or an answer source counts from 0, so page 0 is the first page. The API reference said pages count from 1, which was wrong. An answer source on the first page now keeps its page. Before, it had no page. A text file reports the position of the matched text chunk as its page.
October 20, 2026
One query run for answers and research
Answer a question now starts a stored query run, so a dropped call never loses an answer. It waits waitSeconds for the run, 55 by default, and answers 202 with the run and a Location header when the wait runs out, where it always answered 200 before. The run id comes back either way, and Get research reads the same answer until its expiresAt: one day for an answer, and seven days for research, instead of one hour for both. Answer, Search, and Start research take keys and keyPrefix to scope a question to some of a bucket's objects. Sources that name the same place in one object version are returned once, a snippet is at most 1,000 characters, and sources page with sourceLimit and sourceOffset. A research run that was still working at this release does not finish: start it again.
October 5, 2026
Graphon MCP server and OAuth sign-in
The Graphon MCP server is live at /mcp on the API host. Connect from Claude Code, claude.ai, ChatGPT, Codex, Cursor, or VS Code. Sign in with OAuth and pick a role on the consent page, or send an API key. The tools cover workspaces, members, API keys, buckets, and objects. Settings → Security has a new Connected apps section that lists each app you connected, and you can disconnect an app there.
October 4, 2026
Storage reference from the storage contract
The storage reference now covers every storage operation and is generated from the contract that the storage host serves, published at /storage-openapi.json. List buckets with a name filter returns a list. List objects takes limit and returns nextCursor. A PutObject presign takes ifNoneMatch "*" to create only. The new S3 API page lists every supported S3 operation.
September 30, 2026
One API key for the API, storage, and S3 tools
An API key now works on the Graphon API, the Storage API, and in S3 tools. A key belongs to you or to the workspace. graphon s3-credentials prints S3 credentials from a key.
September 14, 2026
Published the live workspace API
The API reference now documents the implemented workspace, member, invitation, and API-key routes. The OpenAPI document at /openapi.json matches the API host.