Docs
Swagger

Scout · Concepts

API versioning

Scout public HTTP paths are under /v1. This page states how we treat compatibility for paying integrations.

Current contract

  • Stable base: https://api.scout.macrocontent.dev/v1/…
  • Machine-readable schema: /openapi.json
  • Human explorer: Swagger UI

What we consider breaking

  • Removing or renaming a documented response field that customers rely on
  • Changing the meaning of a field without a new name (e.g. flipping boolean semantics)
  • Removing an endpoint or requiring new auth for previously open routes

Additive changes (new optional request fields, new response fields, new endpoints) are not breaking. Ignore unknown JSON keys in clients when you can.

How we ship changes

  1. Prefer additive changes on /v1.
  2. Deprecate before remove — document the replacement in handbook + OpenAPI; keep the old field/endpoint until a stated sunset.
  3. Major path bump (/v2) only if a clean break is unavoidable — /v1 remains available for an overlap window announced in the docs changelog / OpenAPI description.
Errors stay stable
The shared error shape (error, code, retryable) is part of the contract. New code values may appear; treat unknown codes as non-retryable unless HTTP status says otherwise. See Errors.