---
title: "agent-swarm.dev Website Utility API Versioning Policy"
canonical: https://www.agent-swarm.dev/api-versioning.md
---

# agent-swarm.dev Website Utility API versioning and deprecation policy

This policy applies only to the unauthenticated website utilities documented in the [agent-swarm.dev OpenAPI description](https://www.agent-swarm.dev/openapi.json): `GET /api`, `GET /api/geo` and `GET /api/og`. It does not describe the separately deployed, self-hosted Agent Swarm runtime.

## Current version

The current website utility API version is `2026-08-21`.

- Clients may send `API-Version: 2026-08-21` on either documented operation.
- Clients that omit `API-Version` receive the current version.
- Every successful response and structured error includes `API-Version: 2026-08-21`.
- An unsupported version returns HTTP 400 with an RFC 9457 `application/problem+json` body, the code `unsupported-api-version`, and a resolution hint.

## Compatibility policy

The version identifier is a calendar date in `YYYY-MM-DD` form. Backward-compatible documentation, description, and optional-field changes may ship without a new version. A change that removes a field, changes a field type, changes status-code semantics, or makes an optional input required receives a new date-based version.

## Deprecation policy

No website utility API version is currently deprecated. Before Desplega Labs retires a supported version, it will:

1. Publish the replacement version in `openapi.json` and this policy.
2. Mark the old version with the HTTP `Deprecation` response header.
3. Publish its retirement date with the HTTP `Sunset` response header.
4. Include a `Link` response header with `rel="deprecation"` pointing to migration instructions.
5. Keep the deprecated version available for at least 90 days after the deprecation notice unless an urgent security or legal issue requires faster removal.

`Sunset` uses the HTTP-date format defined by RFC 8594. Clients should migrate before that date. After sunset, requests for the retired version receive a structured problem response with a supported-version resolution hint.

## Change discovery

Agents and developers can monitor:

- [OpenAPI 3.1](https://www.agent-swarm.dev/openapi.json) for the active request and response contract.
- [llms.txt](https://www.agent-swarm.dev/llms.txt) for agent-facing discovery links.
- [GitHub releases](https://github.com/desplega-ai/agent-swarm/releases) for broader Agent Swarm product changes.

Questions about this policy can be sent to [contact@desplega.sh](mailto:contact@desplega.sh).