Versioning

The Pickware GraphQL API uses date-based version slugs. The version is part of the endpoint path, so the current schema is reached at POST /api/graphql/2026-06-unstable. The -unstable suffix marks it as an early preview that may still receive breaking changes before the first stable schema is released.

POST /api/graphql/unstable serves the floating unstable schema, which follows the newest development state and changes without notice. Use it only to try upcoming changes, never in production.

Each schema version has its own generated reference. New versions are published as separate references so integrations already in production can keep using the version they were built against.

Compatibility expectations

Schemas with the -unstable suffix may change in incompatible ways while they are served: fields can be renamed or removed, input shapes can change, and mutations may be redesigned. Compare your operations with the version's reference before you rely on an -unstable schema in production.

Once a schema is published without the -unstable suffix, integrations can rely on documented fields, inputs, and mutations within that version. Additive changes such as new fields or enum values may still appear in stable versions, so design clients to tolerate them: ignore unknown fields and handle unrecognized enum values gracefully rather than treating them as errors.

When a future change needs a different contract, it is introduced in a new schema version and documented as a separate reference.

Lifecycle and deprecation

Stable versions are named after the month they are released in, on a quarterly schedule: January, April, July, and October. How long a version is served depends on its kind:

Version	Example	Served until
Stable	2027-01	12 months after its release month.
Dated preview	2026-06-unstable	3 months after the next stable version is released.
Floating	unstable	Always served; it is never retired, and changes without notice.

During the last three months before a version is retired, responses to requests against it carry two headers:

• Sunset: the date on which the version stops being served, as an HTTP date.
• X-Pickware-Api-Deprecation-Date: the date on which the version was deprecated, as YYYY-MM-DD.

Watch for these headers to notice in time that an integration has to move to a newer version. Once a version is retired, requests against it are rejected with the HTTP status 400 Bad Request and the error code PICKWARE_GRAPHQL__UNSUPPORTED_API_VERSION. The response lists the versions that are still served in meta.supportedVersions:

{
  "errors": [
    {
      "status": "400",
      "code": "PICKWARE_GRAPHQL__UNSUPPORTED_API_VERSION",
      "title": "Unsupported Pickware GraphQL API version",
      "detail": "GraphQL API version \"2026-03-unstable\" is not supported. Supported versions: 2026-06-unstable.",
      "meta": {
        "requestedVersion": "2026-03-unstable",
        "supportedVersions": ["2026-06-unstable"]
      }
    }
  ]
}

Using the reference

Use the generated 2026-06-unstable API reference as the source of truth for:

• Query and mutation names.
• Field names and nullability.
• Input fields and default values.
• Required scopes for reading and writing.
• Available filter inputs.