Skip to content
Stainless Stainless Stainless
FeedbackDashboard
Reference
SDK and config editions

SDK and config editions

Editions allow us to safely make updates and improvements to SDKs and the Stainless config that aren’t backwards-compatible, like changing default behavior or renaming a property. Every time we make a breaking change, we release a new version in the form of an “edition” which you can explicitly opt-in to when you’re ready.

There are two types of editions:

  • Top-level editions are for general and cross-language changes and have a date-based identifier (e.g., 2025-10-08)
  • Language-specific editions only impact a specific programming language and have an identifier that includes the language and date (e.g., typescript.2025-10-10) Each edition includes all of the improvements made up to and including the date in its identifier.

The editions we use for your projects are definied in your Stainless config. The top-level edition is specified in the top-level edition property, and language-specific editions are specified inside specific language targets:

# Top-level edition
edition: 2025-10-08


# ...


targets:
  typescript:
    # Language-specific edition
    edition: typescript.2025-10-10
    # ...

When no edition property is present, the oldest available edition will be used. This applies to both the top-level edition property and the edition properties inside language targets. Also note that the top-level edition doesn’t cascade down into language targets. If you have a top-level edition set but a language target doesn’t have an edition property, for example, that language will use the oldest edition, not the one set at the top-level.

The top-level and language-specific editions in your config don’t need to match, and language-specific editions also don’t have to match each other. This gives you the flexibility to incrementally adopt new editions one language at a time without introducting breaking changes across multiple targets at once. Note that we may release language-specific editions without a corresponding top-level edition, making it impossible to have the same top-level and language-specific versions.

Below are all available editions and what was changed.

Config

Section titled “Config”

2026-01-30

Section titled “2026-01-30”

Enables per-endpoint security by default. For example, if your OpenAPI spec looks like this:

security:
  - BearerAuth: []
  - ApiKeyAuth: []


securitySchemes:
  BearerAuth:
    type: http
    scheme: bearer
  ApiKeyAuth:
    type: apiKey
    name: api-key
    in: header


paths:
  /cards:
    post:
      security:
        - BearerAuth: []
      # ... responses omitted

And your stainless config:

settings:
  client_opts:
    bearer_token:
      type: string
      nullable: true
      auth:
        security_scheme: BearerAuth
    api_key:
      type: string
      nullable: true
      auth:
        security_scheme: ApiKeyAuth


resources:
  cards:
    methods:
      create: post /cards

When instantiating the SDK with both options:

from acme import Acme


client = Acme(
  api_key="my-api-key",
  bearer_token="my-bearer-token",
)


client.cards.create()

Previously, the SDK sent both the api-key and Authorization headers, which could cause authentication errors depending on how your API handles multiple authentication schemes.

Now the SDK will only send the Authorization header, as that is the only scheme configured for that endpoint in security.

To revert to the previous behavior of sending all configured options, set per_endpoint_security to false:

settings:
  per_endpoint_security: false

2025-10-10

Section titled “2025-10-10”

Placeholder edition with no functional changes. This will be the default edition for new projects.

2025-10-08

Section titled “2025-10-08”

The first top-level edition for our original base functionality. This will be the default edition used if the top-level edition property is not present.

Target specific editions

Section titled “Target specific editions”