> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sigmora.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning

> What stays stable in v1, what can change, and how deprecations work.

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 `operationId`s.** 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](/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](/pricing).
* 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](/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](/pagination) for the full
list of deprecated pagination parameters.

## Build for forward compatibility

* Generate types from the [OpenAPI document](https://api.sigmora.org/v1/openapi.json),
  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](/changelog) for new capabilities and deprecations.

## Documentation links

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.