API v1 Lifecycle

Status

API v1 is production-supported. It is not a deprecated surface today.

Primary consumers:

• External SDKs.
• MCP and automation integrations.
• Long-lived agent tooling that cannot track web-app-only v2 changes quickly.

The web app may use newer internal routes, but v1 compatibility must be treated as an external contract.

/api/desktop/* is a first-party web/internal desktop bridge surface, not an external API v1 resource surface. Desktop bridge endpoints stay outside /api/v1 unless a future product decision promotes a stable SDK/MCP contract. Current success response shapes are:

• POST /api/desktop/pair/start: resource { code, expiresAt }.
• POST /api/desktop/pair/claim: resource { deviceId, deviceToken }.
• GET /api/desktop/devices: named collection { items: [...] }.
• PATCH /api/desktop/devices/{device_id}/capabilities: ACK { ok: true }.
• POST /api/desktop/devices/{device_id}/roots: ACK { ok: true }.
• DELETE /api/desktop/devices/{device_id}: ACK { ok: true }.

Compatibility Rules

Backward-compatible changes:

• Adding optional request fields.
• Adding response fields.
• Adding new endpoints.
• Adding new enum values only when old clients ignore unknown values.

Breaking changes:

• Removing or renaming request or response fields.
• Changing required authentication scope.
• Changing pagination, ordering, or filtering semantics.
• Replacing stable error codes or HTTP statuses.
• Tightening validation in a way that rejects previously valid client payloads.

Breaking changes require a new API version unless a documented security incident requires immediate mitigation.

Deprecation Process

1. Write a migration note with old behavior, new behavior, and replacement API.
2. Add server warnings or response metadata when feasible.
3. Keep compatibility for at least one public SDK release cycle.
4. Update SDK/MCP examples before disabling the old path.
5. Remove only after usage telemetry shows negligible active traffic or after an approved security exception.

Changelog Requirements

Every v1 behavior change should include:

• A changelog entry.
• A compatibility label: additive, behavior change, or breaking.
• Test evidence for the public contract.

Test Requirements

External-contract routes need tests for:

• Authentication and authorization.
• Required fields and validation errors.
• Pagination and ordering.
• Stable response field names.
• Backward compatibility for additive fields.

Commit messages should use feat(v1-api) for additive behavior, fix(v1-api) for bug fixes, and should avoid labeling externally visible behavior as a pure refactor.

Coverage

• Notes and notebooks: /api/v1/notes, /api/v1/notebooks.
• Calendar: /api/v1/calendar/events and /api/v1/calendar/events/{eventId}. The list endpoint requires from and to, rejects ranges over 366 days, and expands recurring events by default. Pass expand=false to return recurring parent events with their rrule. Creating recurring events accepts the same rrule field as the internal calendar route, and scoped recurring edits use updateScope / deleteScope values this, thisAndFuture, and all. Calendar v1 follows the existing internal calendar behavior for CalDAV-origin events: events with icalUid are visible to the owner and are writable by the owner; readOnly is currently false.

Office identity and route coverage

The stable Office resource prefixes are:

Product	API v1 prefix
Tasks / Kanban	/api/v1/kanban/*
Notes / Notebooks	/api/v1/notes/*, /api/v1/notebooks/*
Calendar	/api/v1/calendar/*, /api/v1/calendars/*
Docs	/api/v1/docs/*
Sheets / Workbooks	/api/v1/workbooks/*
Slides	/api/v1/slides/*
Mindmaps	/api/v1/mindmaps/*
Image Projects	/api/v1/image-projects/*
Forms	/api/v1/forms/*
Workflows	/api/v1/workflows/*

Unless the canonical Office matrix records an exception, these prefixes use CallerIdentity:

• A browser user session acts as that user.
• An ari_cli_* CLI API key acts as its owning user and retains the existing CLI response contract.
• An ari_* Agent token acts for its recorded owner, but resource operations also require the current direct or Space-derived product grant/role.
• App-key identity remains reserved until its persistence contract exists.

Credentials from more than one identity class fail closed. Web-only Office prefixes under /api/** still require a browser session; an API key or Agent token cannot use the v1 identity expansion to enter those handlers. Public delivery routes continue to use their anonymous/share-token policy. Mutations persist the data owner and the actual user or Agent actor separately.

The exact Web, v1, public-delivery, Action, and intentional-exclusion matrix is defined in Office Web, API v1, and Action surface compatibility. Action transport, scopes, confirmation, dry-run, idempotency, and errors are defined in Office Action contract.

OpenAPI, SDK, and MCP contract source

This repository does not ship a separate generated OpenAPI document or SDK package. The public contract is maintained by the route implementation and contract tests, the generated Rust backend route inventory, this lifecycle document, the API changelog, and apps/rust-server/src/routes/mcp_tools_readme.md. Agent Action schemas are generated at runtime by /api/v1/actions/manifest and /api/v1/actions/agent-manifest; the manifest’s content-addressed version and strong ETag are the SDK/MCP cache boundary.