Versioning

How it works

The path carries the major version, as in /v1/api/properties. A second major version would mean a wholesale redesign, would run alongside v1 rather than replacing it, and is not something we intend to do casually.

Day-to-day evolution happens through a dated revision instead. Pin it with a header and your integration keeps the behaviour it was written against:

Skautik-Version: 2026-08-01

Omit the header and your organisation's default revision applies, which is the one current when your first key was created. It is not silently moved forward, so an integration cannot break because we shipped something. Every response echoes the revision that served it.

What we may change without a new revision

These are additive, and a client that follows one rule tolerates all of them: ignore fields you do not recognise. A parser that rejects unknown properties will break on our next release, and that is avoidable.

A new endpoint.
A new optional request parameter.
A new field on an existing response.
A new value in an enum you only read.
A new webhook event type.
Relaxing a validation rule that used to reject something.

What requires a new revision

Anything that could break a correct client gets a new dated revision. Your pinned revision continues to behave as documented.

Removing or renaming an endpoint, parameter, or response field.
Changing the type or units of an existing field.
Making an optional parameter required, or tightening validation.
Changing the default value of a parameter.
Changing the meaning of an existing enum value.
Removing a webhook event type.

Deprecation

When something is on its way out it keeps working and starts announcing itself. Deprecated endpoints return:

Deprecation: true
Sunset: Wed, 01 Jul 2026 00:00:00 GMT
Link: <https://skautik.com/docs/developers/api/properties>; rel="deprecation"

At least 12 months between a deprecation notice and removal, for anything in a released revision.
We email the technical contact on the organisation when a deprecation begins, and again as the sunset approaches, rather than relying on you reading a changelog.
Alert on the Deprecation header in your own monitoring. It is the earliest possible warning and costs nothing to watch.

Writing a durable client

Pin the revision explicitly rather than relying on your account default.
Ignore unknown fields and unknown enum values instead of failing on them.
Treat identifiers as opaque strings; never parse a prefix for meaning.
Do not depend on field order, on the absence of a field, or on a count the API does not promise.
Branch on error codes, not on error prose.

How it works

Day-to-day evolution happens through a dated revision instead. Pin it with a header and your integration keeps the behaviour it was written against:

Skautik-Version: 2026-08-01

What we may change without a new revision

A new endpoint.

A new optional request parameter.

A new field on an existing response.

A new value in an enum you only read.

A new webhook event type.

Relaxing a validation rule that used to reject something.

What requires a new revision

Anything that could break a correct client gets a new dated revision. Your pinned revision continues to behave as documented.

Removing or renaming an endpoint, parameter, or response field.

Changing the type or units of an existing field.

Making an optional parameter required, or tightening validation.

Changing the default value of a parameter.

Changing the meaning of an existing enum value.

Removing a webhook event type.

Deprecation

When something is on its way out it keeps working and starts announcing itself. Deprecated endpoints return:

Deprecation: true
Sunset: Wed, 01 Jul 2026 00:00:00 GMT
Link: <https://skautik.com/docs/developers/api/properties>; rel="deprecation"

At least 12 months between a deprecation notice and removal, for anything in a released revision.

We email the technical contact on the organisation when a deprecation begins, and again as the sunset approaches, rather than relying on you reading a changelog.

Alert on the Deprecation header in your own monitoring. It is the earliest possible warning and costs nothing to watch.

Writing a durable client

Pin the revision explicitly rather than relying on your account default.

Ignore unknown fields and unknown enum values instead of failing on them.

Treat identifiers as opaque strings; never parse a prefix for meaning.

Do not depend on field order, on the absence of a field, or on a count the API does not promise.

Branch on error codes, not on error prose.