API Changelog and Versioning Policy

Versioning policy

The Papyrus API is versioned in the URL: /api/v1/.... Versions are bumped only for breaking changes. Backward-compatible additions ship continuously inside the same version.

What's a breaking change

Removing a field from a response
Renaming a field
Changing a field's type or semantics
Removing an endpoint
Adding a required request parameter
Tightening validation
Changing pagination behaviour materially

What's a non-breaking change

Adding a new endpoint
Adding a new optional request parameter
Adding a new field to a response
Adding new event types
Adding new error codes (you should handle unknown codes gracefully)
Performance improvements

How long old versions stay

When v2 ships, v1 is supported for at least 18 months before sunset. We publish the sunset date when v2 ships.

Subscribing to changes

Three channels:

The API Changelog (this page) is updated on every change
The release notes include API changes per release
The webhook api.deprecation_notice event fires when an endpoint or field your tenant uses is being deprecated

Changelog (rolling)

2026-05-01 (v2.4)

Added: POST /api/v1/copilot/conversations for Copilot API access (Business+ tenants)
Added: currentApprovers field on workflow instance responses
Changed: search response now includes aiSignalsUsed array for transparency
Changed: webhook delivery retry curve relaxed (was: 6 attempts over 12h, now: 8 attempts over 48h)

2026-04-03 (v2.3)

Added: /api/v1/knowledge-graph/* endpoints
Deprecated: /api/v1/entities (sunset 2026-10-01) — use /api/v1/knowledge-graph/entities

2026-03-04 (v2.2)

Added: /api/v1/forms/* endpoints for eForm submissions
Changed: file uploads accept Idempotency-Key header

2026-02-12 (v2.1)

Added: Platform and DeviceToken parameters on push subscription endpoint
Changed: notification delivery payload includes pushChannel field

2026-01-15 (v2.0)

Major version bump
Added: /api/v1/auth/passkeys/* endpoints
Deprecated: /api/v1/login form-encoded variant (sunset 2027-01-01)
Changed: tenant resolution priority documented (subdomain > custom domain > X-Tenant-Id header > JWT claim)

Older entries

For changes before v2.0, see the archived changelog at /resources/developers/api-changelog/archive.

Migration help

When a breaking change comes, we publish:

A migration guide (the “how to update your code” article)
A code-diff comparing the old and new patterns
A migration helper script where applicable
Office hours sessions for high-volume API consumers

Beta endpoints

Endpoints under /api/v1/beta/* may change at any time without notice. They're for early access; don't depend on them in production. They graduate to stable paths (or are removed) within 6 months.

Stability tiers

Tier	Path	Stability
GA	`/api/v1/*`	18-month deprecation notice
Beta	`/api/v1/beta/*`	Stable for 30 days at a time
Internal	`/internal/*`	Not for customer use; no compatibility commitment