# Versioning and changelog

> Understand Hodoflow's surface-specific compatibility policy, response version headers, deprecation signals, and release-matched artifacts.

Hodoflow versions each public surface according to its transport. There is no
single header that changes every API at once.

## Current public versions

| Surface | Current identity | Evidence |
|---|---|---|
| JSON:API | `v1` | `/api/json/v1` path and `x-api-version: v1` |
| GraphQL | `2026-07-05` | `x-api-version` and first line of [schema.graphql](/schema.graphql) |
| Token exchange | `v1` route family | `/api/v1/oauth/token` |
| Webhook ingestion | `v1` route family | `/api/v1/webhooks/:token` |

The version returned by a response is the authoritative identity of that
surface. Store it with `x-request-id` in diagnostics.

## JSON:API compatibility

JSON:API uses major path versioning. Additive fields and operations can enter
`v1`; clients must ignore attributes they do not consume. A breaking request or
response change requires a new mount such as `/api/json/v2` and a migration
window for `v1`.

Use stable `operationId` values from [OpenAPI JSON](/openapi.json) when mapping
generated clients or tests. A path can contain a version while the application
origin in `servers` remains unversioned; join them exactly once.

## GraphQL compatibility

GraphQL evolves additively at one `/api/graphql` endpoint. New fields are
compatible for clients that select explicitly. A field or argument scheduled
for removal is marked deprecated in schema introspection and the generated SDL
before the deprecation window closes. The date version advances when a schema
compatibility boundary changes.

The schema currently exposes no mutations or subscription fields. Do not build
against internal types or infer capabilities that are absent from the SDL.

## Deprecations

Legacy token and webhook URLs containing an organization domain are deprecated.
Use the canonical apex paths shown in [Base URLs](/get-started/base-urls-workspaces-versions).
Deprecation warnings in server logs are not a client-facing migration channel;
public changes must appear in release notes and the versioned artifacts.

## Release-matched changelog workflow

This portal does not invent a release history separate from the product. For
each deployed release:

1. compare the committed GraphQL SDL with the generated schema;
2. regenerate and contract-test OpenAPI operation IDs, scopes, examples, and errors;
3. update affected guides and reference metadata in the same change;
4. verify old HTML and Markdown aliases; and
5. publish product release notes naming additions, deprecations, and migration deadlines.

Until a dedicated release-note feed is published, the current
[OpenAPI](/openapi.json), [GraphQL SDL](/schema.graphql), and this page are the
honest compatibility sources. Never claim a capability merely because a future
route name appears in planning material.