Allure Connect API versioning

Allure Connect uses explicit URI versions for public API contracts. The current public customer API is V1. The Create V2 publishing contract is a separate, signed product-to-product surface and does not replace an existing customer's V1 integration.

Current contracts

The V1 OpenAPI 3.1 document is available at GET /api/docs/openapi, with an interactive reference at /api/docs.

V2 is publicly documented but is not a generally available customer API. New V2 acceptance requires the receiver flag to be explicitly enabled (its production default is disabled) and an exact server-side { tenantId, allureWorkspaceId } allowlist match. Missing, malformed, empty, or non-matching configuration fails closed. The canonical and historical Furness/FidesAcademy tenant identities remain hard-denied even if a configuration attempts to name them. Production keeps the V2 receiver off and the allowlist empty for this release.

Compatibility policy

Changes within V1 are additive or corrective:

• existing endpoint paths and required request fields remain supported;
• optional request fields or new response fields may be added;
• security and correctness defects may be fixed;
• existing packages, launches, sessions, reports, dispatches, and webhooks are not silently migrated to another contract.

A breaking public API change would require a new public contract, a reviewed migration guide, and an announced support timeline. No V1 deprecation or removal date has been announced.

What Create V2 means

Create V2 binds a publish to an exact source version, request and manifest hashes, destination identity, and idempotency key. Connect stores a durable receipt so Create can safely reconcile retries and lost responses.

V2 is not a blanket replacement for /api/v1. Existing API keys are not converted automatically, and customers do not change V1 endpoint URLs to use the Create V2 contract.

After the controlled production ramp succeeds, V2 may become the default for newly created Allure Create workspaces. Existing workspaces remain on their current path unless an owner approves a workspace-specific change.

A package-producing combined destination acceptance run is complete only after the Create adapter reports status: "complete" and Connect returns a completed, valid receipt with non-empty package, package-version, and artifact identities. An unknown or reconciling receipt remains eligible for idempotent lookup, but must not be treated as a successful handoff to a downstream destination. Hosted-only conversions can complete without a downloadable artifact; they are not accepted as the package-producing combined handoff above.

V1 endpoint families

The current public API includes:

• package upload, processing, inventory, and deletion;
• learner launch and session reporting;
• dispatch creation, listing, and revocation;
• xAPI statement storage, query, and analytics;
• usage and pricing summaries;
• webhook configuration and delivery.

Use the OpenAPI document for the exact current methods and schemas.

Rollout and rollback

Create V2 activation is allowlisted and destination-specific. The Connect receiver is enabled before its Create caller, then observed on a non-customer workspace. Disabling the write flags stops new V2 publishes while preserving packages, receipts, lookup, reconciliation, and existing V1 delivery. An exact hosted stage durably bound before rollback may finish activation and start its single meter; the flag flip prevents new bindings rather than canceling accepted work. The hard denial for both protected Furness/FidesAcademy identities overrides that lifecycle.

Furness/FidesAcademy remains on V1 and is excluded from staging, canaries, and automatic migration. Any future customer canary requires a separately approved workspace, package, operation, observation window, and rollback plan.

For a fuller compatibility explanation, read Allure Create publishing: V1 and V2 coexistence.