Skip to main content

API Versioning and Deprecation

The Willow Admin API (https://app.withwillow.ai/api/...) is versioned so that scripts and AI agents can integrate against it without being broken by surprise. This page describes the current version, what can change without a new version, and how Willow announces and removes deprecated operations.

Current version​

The current and only version of the Admin API is version 1.

  • The paths documented in the API Reference, such as /api/mcp-servers, are version 1.
  • Every endpoint accepts an optional Willow-API-Version request header. The only accepted value today is 1. Omitting the header means version 1.
curl https://app.withwillow.ai/api/mcp-servers \
  -H "Authorization: Bearer wxt_xxxxx" \
  -H "Willow-API-Version: 1"

Sending the header is optional. Clients that pin it today will keep getting version 1 after a later version ships.

Non-breaking changes​

These changes can ship within version 1 at any time, without notice. Write clients that tolerate them:

  • new endpoints
  • new optional request fields or query parameters
  • new fields in response bodies
  • new values in enum-like fields, such as a new status or type
  • new optional request or response headers
  • changes to human-readable error messages (the HTTP status code stays the same)

Breaking changes​

A breaking change is anything that can make a working version 1 client fail, for example removing an endpoint or field, renaming a field, making an optional field required, or changing a field's type or meaning.

Breaking changes ship only under a new API version, selected with the Willow-API-Version header. Version 1 keeps working until it is deprecated and its sunset date passes.

How deprecations are announced​

When an operation, or a whole API version, is deprecated:

  1. It is marked deprecated: true in the Admin API OpenAPI spec.
  2. Its responses include a Deprecation header (RFC 9745) with the date it was deprecated, and a Sunset header (RFC 8594) with the date after which it may be removed.
  3. It is listed under Current deprecations on this page, with its replacement and sunset date.

The sunset date is at least 6 months after the deprecation is announced. Nothing is removed before its sunset date.

To catch deprecations early, log or alert on any response that carries a Deprecation header.

Current deprecations​

None. No Admin API operation is currently deprecated.

Scope​

This policy covers the Admin API. The SCIM API follows the SCIM 2.0 standard (/scim/v2). The User API and the MCP gateway are not covered by this page.

On this page