Diagrams.so
Diagrams.so

API Deprecation and Versioning Policy

Effective date: September 15, 2026

This policy describes how we version the Diagrams.so public API and how we retire functionality. It applies to the REST API at api.diagrams.so and, by extension, to the official MCP server and SDKs, which are clients of the same API.

How this relates to the Terms of Service: the binding commitment lives in the Terms, which promise commercially reasonable notice of at least 90 days before a generally available API version or documented capability is shut down, with carve-outs for legal, security, and beta cases. The longer windows below are our operating policy on top of that floor. We intend to honor them, and where this page and the Terms conflict, the Terms control.

1. Versioning scheme

The current API is v2, rooted at https://api.diagrams.so/api/v2. The major version is in the URL path. A given major version presents one stable surface that changes only in backward-compatible ways.

2. What counts as backward-compatible

We may ship the following within a major version at any time:

  • new endpoints, or new HTTP methods on existing endpoints;
  • new optional request parameters or request-body fields;
  • new fields in response objects, at any nesting level;
  • new values in existing enums, and new event or object types;
  • changes to the order of response fields, or to the length and format of opaque identifiers and error messages;
  • new or changed HTTP response headers, such as rate-limit headers;
  • relaxed validation (accepting input we previously rejected);
  • changes to undocumented behavior, and any change to beta-labeled endpoints.

Build clients accordingly: ignore unknown response fields, tolerate unknown enum values, and do not parse error-message strings or depend on field order. The official SDKs follow these rules.

3. What counts as breaking

Removing or renaming an endpoint, field, or documented enum value; making an optional parameter required; changing a field's type or meaning; tightening validation so previously valid requests fail; changing documented error codes or authentication semantics; or materially reducing documented rate limits for an existing tier. We do not ship breaking changes within a major version. When we need one, it goes into the next major version, subject only to the exceptions in Section 6.

4. Deprecation and retirement timeline

When we deprecate something:

  1. We mark it. The docs and changelog flag it as deprecated, with the recommended replacement and a migration guide.
  2. We signal it in-band. Affected responses carry a Deprecation header, and a Sunset header once a retirement date is set.
  3. We email affected users. We notify the owners of API keys that have recently called the deprecated element, at the account email on file. Keep your account email current; it is the delivery channel for these notices.
  4. We wait. A deprecated endpoint, parameter, or field keeps working for at least 6 months after being marked. An entire major version keeps working for at least 12 months after its retirement is announced.

These windows are our operating policy; the contractual commitment is the 90-day notice in the Terms. In practice we expect to meet or exceed them for anything in general availability.

5. Beta surfaces

Endpoints, parameters, tools, or SDK features labeled beta, alpha, preview, or experimental may change or be removed at any time without notice, and are excluded from Sections 3 and 4 and from the Terms' notice commitment. Labels apply per endpoint or feature as marked in the docs. The MCP server's tool set may grow or change between releases; pin a version if you need stability.

6. Exceptions

We may change or disable functionality on shorter or no notice where reasonably necessary to comply with law or a legal order, to address a security vulnerability or abuse, or to satisfy an upstream provider requirement we cannot negotiate around. We give as much notice as circumstances allow and document the change in the changelog afterward.

7. SDK and MCP versioning

The SDKs and MCP server follow semantic versioning independently of the API. A new SDK or MCP major version may change its own interfaces without indicating any API change. We support the current major version of each; older majors receive security fixes at our discretion. Retiring an SDK major follows the same spirit as Section 4: a deprecation notice in the package README and changelog, then a wind-down window.

Questions: support@diagrams.so.

All policies