Versioning and deprecation

Which changes can happen without notice, how an endpoint that will be retired is announced, and which headers tell you.

Building on an API is a bet that what works today still works in six months. This page states exactly what can change without notice, what never changes without advance warning, and how you find out.

The rule in one sentence

/api/v1 only grows. Everything that responds today will keep responding the same way: if something has to break, it lives at /api/v2 and both coexist for at least six months.

Changes you can expect without notice

These are additive: they don't break anyone who is already integrated, and they happen often.

• New endpoints.
• New fields in a response.
• New optional parameters.
• New values in an enum field (a new status, a new channel type).
• New error codes within an existing type.

Two practical consequences for your integration:

1. Don't assume you know every field in a response. Ignore the ones you don't use instead of failing. The contract's schemas are marked as open for exactly this reason.
2. Don't write an exhaustive switch over an enum without a default branch. A new status shouldn't take down your process.

Changes that never happen without a deprecation cycle

• Removing an endpoint.
• Removing or renaming a field in a response.
• Renaming a route or an operationId.
• Making an optional parameter required.
• Changing the meaning of a value that already existed.

Any of these goes through the full cycle below.

The deprecation cycle

When an endpoint is going to be retired, four things happen before it stops responding:

1. It's marked in the contract. The operation carries deprecated: true in openapi.public.json, the retirement date in x-sunset, and what to use instead in x-alternative. If you generate your client from the contract, most generators mark the method as deprecated and your editor strikes it through.

1. Every response tells you. While it's still alive the endpoint responds normally — it doesn't fail, its body doesn't change — but it adds these headers:

bash curl -i https://api.met.meteor.com.co/api/v1/... \ -H "Authorization: Bearer met_live_your_key" # HTTP/1.1 200 OK # Deprecation: true # Sunset: Wed, 01 Jul 2026 00:00:00 GMT # Link: <https://developers.meteor.com.co/guias/versionado.html>; rel="deprecation"; type="text/html"; title="Usa POST /runs"

If you have observability over your outbound calls, it's worth alerting when a Deprecation shows up — it's the cheapest way to not find out late.

1. A changelog entry explains why and what to migrate to.

1. At least six months pass between the announcement and the retirement.

How to know which version you generated against

The contract declares its version in info.version, and that version is the same one heading the most recent changelog entry.

curl -s https://developers.meteor.com.co/public/openapi.public.json | jq .info.version

If you save that number the day you generate your client, comparing against the changelog tells you exactly what happened in between.

What this cycle does not cover

• Error type values are a closed list of five and they don't grow: authentication_error, invalid_request_error, rate_limit_error, agent_error, api_error. The code values inside each one do grow. Program against the type when you need a control branch, and use the code for the message. It's all in Errors, idempotency and pagination.
• Your plan's limits are not an API contract. The rate limit and the quota can change with your plan; read them from the headers on each response instead of assuming them. See Limits and quotas.