For developers
Versions and upgrades
Check the API contract, refresh outdated tools and safely adopt supported notes.
XOR reports its API contract version in its responses. This is separate from the MCP transport protocol, the plugin installed in your app and each database’s notes schema. Different version numbers are not, by themselves, a mismatch.
Discover the running version
| Surface | Where to look |
|---|---|
| MCP initialization | serverInfo.version; capabilities.experimental["com.systemofreason/compatibility"] gives the compatibility details. |
| MCP tool results | _meta["com.systemofreason/compatibility"], including tool errors. The existing JSON text result is unchanged. |
HTTP responses from /v1 and /mcp |
X-XOR-API-Version, X-XOR-API-Major, and X-XOR-Upgrade-URL, including authentication errors and raw file responses. |
GET /v1 with an access key |
compatibility, alongside the existing tools list. |
GET /v1/openapi.json with an access key |
info.version and x-xor-compatibility. |
The compatibility object includes api.version, api.major, api.supportedMajors, notes.supportedSchemaVersion, and URLs for discovery, OpenAPI and this guide. The notes number is what the server supports, not the version of any particular database. Use sql_read with op: "notes_status" on the discovered database to check its fields.version, fields.supportedVersion, fields.compatible and fields.managed.
XOR cannot see the plugin or skills installed in your app. installationCompatibility: "unknown" is deliberate: it does not mean an install has been checked or needs an update. MCP’s clientInfo.version is the host app’s version, not necessarily the XOR plugin’s. Some apps hide result metadata from the model; the server instructions also name the API version and this guide.
Detect and resolve a mismatch
Clients and skills should record their required API major and minimum API version. Compare those with the running server, not with the plugin’s own version number. Compare semantic-version components numerically, not as strings.
- Different API major, or a server older than the required minimum: stop the affected writes. Check the release notes below, refresh discovery, and update the client or server as appropriate. Do not keep retrying a request from an unsupported contract.
- Missing or renamed tools after a release: reconnect or refresh the existing MCP connection and request
tools/listagain. Update an installed plugin through the app’s plugin manager, or update the installed skills using the setup guide. Do not add a second connection. A call to a tool name that is gone answersnot_found, naming the tools that replaced it. - Skills that assume a notes location or columns: replace generated SQL with the managed notes operations. Discover existing resources using unfiltered
my_stuff, thennotes_status; don’t create a second database just because the skill assumesmemory/default. - Notes version 0, compatible layout: with permission,
sql_writewithop: "notes_setup", the same project/database,expected_layoutfromnotes_statusandtarget_versionfromsupportedVersionadopts the table. Checknotes_statusafterward. Adoption keeps the location, IDs, contents and history; it does not update installed skills. - Notes version newer than this server, an unsupported schema, or schema drift: stop managed writes and review the reported reason. Never downgrade, rename columns or rewrite customer tables to make an error disappear. A newer notes schema needs server code that supports it; a custom schema needs a separately reviewed migration.
An old server that reports 1.0.0 but has no compatibility object predates this discovery contract. It may still have managed notes; inspect tools/list and notes_status rather than assuming the feature is absent. Missing version metadata is unknown compatibility, not permission to migrate data.
Version policy
- Major: incompatible contract changes. Publish the replacement contract and migration path before retiring the old one;
/v1remains API major 1. - Minor: backward-compatible features or metadata. Existing clients may ignore new fields; clients needing a new feature declare its minimum version.
- Patch: compatible corrections. A different patch version alone does not require a client upgrade.
- Notes schema: an independent, per-database integer. Migrations are append-only, explicit and repeat-safe. API releases do not automatically migrate customer data.
The contract version is not a build ID and does not change for every deployment. Changes to the public contract update its version and this release history together. Versions inform clients; this release does not negotiate client requirements or automatically update plugins.
Release history
19 November 2026 — clearer names for automations
use_read and use_write are now automations_read and automations_write. Their titles, inputs and annotation hints are unchanged. Calls to the old names still run the same tools, but those names are not in the tool list, so a directory scan does not see them. Reconnect or refresh tools to pick up the new names. Other tool bodies keep their shapes.
API 1.3.0 — finding pages, and comments on them
pages_read gets op search (q, limit, optional project, and no page): the person’s pages whose name, title, purpose or text has every word, from their account’s own index. A page gets comments: pages_read op comments, pages_write ops comment and comment_done, and set takes comments (on or off) and inbox_gets (comments, versions: what the page’s inbox gets besides its forms). get and my_stuff add commentsOpen, commentsNewestAt and publishedAt. An inbox event the page itself sent carries from_page; one from the inbox’s public address never does, and no x-xor-* header a sender gives is kept. Everything is added: existing tool bodies keep their shapes.
API 1.2.0 — pages’ own tools
Pages get two tools of their own, pages_read (get, versions, file, data_list, data_get) and pages_write (publish, edits, set, restore_version, upload_link, test_form, data_set, data_update, data_delete), named by page. use_read and use_write are for schedules, inboxes and agents again; a page, or a page’s op, sent to them answers invalid_inputs naming the tool that takes it. use_read op knowhow is listed whether or not pages are on. The tool names from before October 31, 2026 no longer run on /v1: they answer not_found, naming the tools that replaced them, as they always did over MCP. account no longer answers a closing field; its description says no tool closes the account. Other tool bodies keep their shapes.
API 1.1.0 — compatibility discovery
Adds consistent REST/MCP version metadata, notes-schema support information and this upgrade guide. Existing /v1 tool bodies, raw bytes and MCP JSON text results keep their shapes. No new notes migration is introduced. Managed notes schema 1 supports the recognized legacy project and canonical topic layouts in place.
Before API 1.1.0
The MCP server and OpenAPI advertised a static 1.0.0, not a reliable feature inventory. The October 31 tool split and the later managed-notes release both used that value. Use live tool discovery for those installations.