Skip to main content
The API version is part of every path: https://api.sigmora.org/v1/.... Code you write against v1 keeps working. Anything that would break an existing integration ships as a new version instead.

​
What stays stable in v1

  • Paths, methods and operationIds. An operation keeps its path, method and operationId, so clients generated from the OpenAPI document keep their method names.
  • Required fields. A request that is valid today stays valid. New request fields are optional.
  • Response fields you rely on. Fields are not removed or renamed, and their types do not change.
  • Error codes. The list of code values only grows. A code is never renamed, removed or moved to a different HTTP status. See Errors.
  • Closed sets you branch on. Job status values and error code values keep their meaning.

​
What can change within v1

These are additive and should not break a well-behaved client:
  • New operations, and new optional request fields, query parameters and headers.
  • New fields in responses. Ignore fields you do not recognize.
  • New values in open-ended or display fields — for example job phase, which is for showing progress, not for branching.
  • New error codes. Handle an unknown code by its HTTP status.
  • New capabilities in GET /v1/capabilities, and price changes. Prices are live; read them rather than hard-coding them. See Pricing & credits.
  • Improved wording in human-readable error messages.

​
Deprecations

When a better way to do something arrives, the old way keeps working:
  • The deprecated field or parameter is still accepted and still returned.
  • The OpenAPI document marks it deprecated: true, and its description names the replacement.
  • The changelog records the change.
Cursors are opaque and short-lived, and can change format. On 2026-10-10 GET /v1/projects on api.sigmora.org began answering from the same project store as sigmora.org; a nextCursor issued before that is refused with invalid_request — list again from the first page. For example, GET /v1/assets still accepts after and returns nextAfter alongside the newer cursor and nextCursor; POST /v1/projects still accepts the older kind alongside mediaType; and artifacts.video remains a copy of artifacts.download on render jobs. See Pagination for the full list of deprecated pagination parameters.

​
Build for forward compatibility

  • Generate types from the OpenAPI document, but keep a reviewed copy in your repository and diff it before you update.
  • Allow unknown fields when you parse responses — do not use strict schemas that reject extra keys.
  • Branch on status and code, never on phase or error text.
  • Treat ids and cursors as opaque strings.
  • Follow the changelog for new capabilities and deprecations.
Pages in the API reference are named for each operation’s section and title. When a section or title changes, the old address redirects permanently to the new one, so bookmarks and links keep working.