Versioning and Lifecycle

Current status

  • Public base path: /api/v1/
  • Current release posture: v1-beta
  • Contract source of truth: openapi/reportkey-api-v1.yaml
  • Docs source of truth: the current pages under /guides and /reference

Versioning model

Reportkey uses path-based versioning.

  • The current public contract lives under /api/v1/.
  • New changes should extend the current contract additively where possible.
  • Breaking changes should not silently mutate the meaning of an already documented v1 route.
  • If a future change cannot stay backward-compatible, it should ship as a new path version such as /api/v2/.

What clients should expect during beta

The current API is published as v1-beta, which means the surface is usable and documented, but may still expand over time.

Clients should:

  • treat unknown optional fields as ignorable;
  • avoid depending on undocumented field ordering;
  • follow the OpenAPI contract instead of relying on undocumented behavior.

Clients should not expect:

  • silent removal of already documented routes during the current beta;
  • undocumented private fields to become part of the supported contract;
  • webhook or push-style change notifications in v1.

Deprecation policy

Reportkey does not currently publish a separate HTTP Sunset header workflow for v1 beta.

Current deprecation handling is documentation-first:

  1. mark the replacement path or field in the OpenAPI contract when relevant;
  2. update the narrative docs under /guides;
  3. add a dated note to the change log section on this page;
  4. keep existing clients on the documented path until the replacement is clear.

If a change would break existing v1 clients, the preferred path is a new API version instead of a hidden in-place contract mutation.

Change-announcement workflow

Every public contract change should be announced in the repo-hosted docs at the same time as the rollout or earlier.

The minimum workflow is:

  1. update openapi/reportkey-api-v1.yaml;
  2. update the affected /guides guide pages;
  3. add or refresh a dated entry in the change log below;
  4. if the change affects existing clients, document the replacement and rollout expectations clearly.

The public lifecycle docs are published on the production API host:

  • https://api.reportkey.net/guides

Change log

2026-04-09

  • published the first Reportkey Public API beta contract under /api/v1/;
  • documented bearer auth, scopes, async job flows, idempotency, and usage limits;
  • published guides and interactive reference pages on api.reportkey.net;
  • added the experimental standalone MCP bridge over the public API.

Current removals and deprecations

  • No public v1 endpoints are currently scheduled for removal.
  • No public v1 routes are currently marked as deprecated in the shipped docs.