Stainless config schema

The Stainless Config (stainless.yml) defines how Stainless generates assets from your OpenAPI specification. It lives in your repo and is version-controlled like any other code. The Stainless config is separate from your spec because it and captures specific settings, structure, and information that do not belong in the API definition itself.

The config controls things such as:

• How endpoints are named and how methods are grouped or nested (e.g., chat.completions.create())
• Which SDKs and tools to generate and how they are published (npm, PyPI, Maven, etc.)
• The core hierarchy of generated clients
• Customization beyond your OpenAPI spec, like naming, organization, and behavior changes

Use the content below to gain a detailed understanding of the Stainless configuration file, its supported keys, their types, and their values.

Other references which complement this one:

• Stainless OpenAPI extensions
• Stainless OpenAPI transforms
• Stainless workspace schema

Example OpenAPI spec

# We support 3.X formats. Read about the difference between 3.0 and 3.1
# at https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0
openapi: 3.1.0

# Information in this section is used in the initial guess of the Stainless config, but not read afterwards.
# For example, contact.email is used in the initial guess of the Stainless config for determining
# `organization.contact`, which is linked to in each of the SDKs' README.md.
info:
  title: Acme Developer API
  description: >
    The Acme Developer API is designed to provide a predictable programmatic
    interface for accessing your Acme account through an API and transaction
    webhooks.
  version: 1.0.0
  termsOfService: "https://acme.com/legal#terms"
  contact:
    email: support@acme.com

# The servers here is used in the initial guess of the Stainless config for determining `environments` which
# allows users to change between various base URLs easily.
servers:
  - url: https://api.acme.com/v1
    description: Acme production API server
  - url: https://sandbox.acme.com/v1
    description: Sandbox environment that provides key functionality mirroring production

# Tags are not used by Stainless, but are recommended for other OpenAPI tools and book-keeping.
tags:
  - name: Account
  - name: Friends
  - name: Status

# Paths define the endpoints and methods, their request/response types, and more.
paths:
  /accounts:
    get:
      tags:
        - Account
      summary: List account
      description: List account
      parameters:
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/PaginationResponse"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/Account"
    post:
      tags:
        - Account
      summary: Create account
      description: Create account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Account"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Account"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "429":
          $ref: "#/components/responses/TooManyRequests"

  /accounts/{account_id}:
    get:
      tags:
        - Account
      summary: Get account
      description: Get account
      parameters:
        - $ref: "#/components/parameters/AccountID"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountConfiguration"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "429":
          $ref: "#/components/responses/TooManyRequests"
    put:
      tags:
        - Account
      summary: Update account
      description: |
        Update account configuration.
      parameters:
        - $ref: "#/components/parameters/AccountID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Account"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Account"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /accounts/{account_id}/link:
    post:
      tags:
        - Account
      summary: Link account to external account
      description: Link account to external account, such as a Google or Facebook Account
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AccountLink"
            examples:
              GoogleAccount:
                account_type: "google"
                google_account_id: "123456789"
              FacebookAccount:
                account_type: "facebook"
                google_account_id: "123456789"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountLink"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /accounts/{account_id}/friends:
    get:
      tags:
        - Friends
      summary: Get friends for this an account
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/PaginationResponse"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/FriendResponse"

        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /accounts/{account_id}/friends/{friend_id}:
    put:
      tags:
        - Friends
      summary: Add a friend to this account
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/FriendID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateFriendRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FriendResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "429":
          $ref: "#/components/responses/TooManyRequests"
    delete:
      tags:
        - Friends
      summary: Remove a friend from this account
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/FriendID"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FriendResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "429":
          $ref: "#/components/responses/TooManyRequests"

  /status:
    get:
      tags:
        - Status
      summary: API status check
      operationId: getStatus
      security: [] # disable security
      responses:
        "200":
          description: Endpoint for users to check whether they can reach the api.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

components:
  parameters:
    IdempotencyKey:
      in: header
      name: Idempotency-Key
      description: A idempotency key to make retrying operations safe.
      schema:
        type: string
      examples:
        IdempotencyKeyExample:
          value: my-random-key-848x8e8r1
          summary: A sample idempotency key
    Cursor:
      in: query
      name: cursor
      nullable: true
      description:
        The cursor for pagination, which can be populated by the `next_cursor`
        value of the initial request.
      schema:
        type: string
    Limit:
      in: query
      name: limit
      nullable: true
      description:
        The number of elements to fetch in the page. Defaults to 20 if not
        provided.
      schema:
        type: integer
    AccountID:
      in: path
      name: account_id
      required: true
      description: Globally unique identifier for account.
      schema:
        type: string
        format: uuid
      examples:
        AccountIDExample:
          value: d86a0a4d-7459-471a-83b4-431136320828
          summary: A sample account id
    FriendID:
      in: path
      name: friend_id
      required: true
      description: Globally unique identifier for friend.
      schema:
        type: string
        format: uuid
      examples:
        FriendIDExample:
          value: d86a0a4d-7459-471a-83b4-431136320828
          summary: A sample friend id

  schemas:
    PaginationResponse:
      type: object
      properties:
        has_more:
          type: boolean
        next_cursor:
          type: string
          nullable: true
      required:
        - has_more
        - next_cursor
    Address:
      type: object
      properties:
        address1:
          type: string
          description: Valid address.
          example: 155 Water St
        address2:
          type: string
          description: Unit or apartment number (if applicable).
        city:
          type: string
          description: Name of city.
          example: New York City
        country:
          type: string
          description: >
            Valid country code, entered in uppercase ISO 3166-1 alpha-3
            three-character format.
          example: USA
        postal_code:
          type: string
          description: >
            Valid postal code. Only USA ZIP codes are currently supported,
            entered as a five-digit ZIP or nine-digit ZIP+4.
          example: "11217"
        state:
          type: string
          description: >
            Valid state code. Only USA state codes are currently supported,
            entered in uppercase ISO 3166-2 two-character format.
          example: NY
      required:
        - address1
        - city
        - country
        - postal_code
        - state
    Account:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
        plan:
          type: string
          enum:
            - FREE
            - PREMIUM
          description: The plan that the user is on.
        state:
          type: string
          enum:
            - ACTIVE
            - PAUSED
          description: Account states.
        address:
          $ref: "#/components/schemas/Address"
      required:
        - name
    AccountConfiguration:
      type: object
    AccountLink:
      oneOf:
        - type: object
          title: "Google"
          properties:
            type:
              const: "google"
            google_account_id:
              type: "string"
          required:
            - type
            - google_account_id
        - type: object
          title: "Facebook"
          properties:
            type:
              const: "facebook"
            facebook_account_id:
              type: "string"
          required:
            - type
            - facebook_account_id
      discriminator:
        propertyName: type
    Error:
      type: object
      properties:
        message:
          type: string
        data: {}
    CreateFriendRequest:
      type: object
      properties:
        message:
          type: string
          writeOnly: true
    FriendResponse:
      type: object
      properties:
        mutuals:
          type: integer
          readOnly: true
        friend_since:
          type: string
          format: date-time
          readOnly: true
      required:
        - mutuals
        - friend_since

  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    ApiKeyAuth:
      type: apiKey
      in: header
      name: "X-Acme-Api-Key"

  responses:
    BadRequest:
      description:
        A parameter in the query given in the request does not match the valid
        queries for the endpoint.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Conflict:
      description:
        The request could not be completed due to a conflict with the current
        state of the target resource.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    InternalServerError:
      description: There was a processing error on the server-side.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFound:
      description: The specified resource was not found.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    TooManyRequests:
      description: |
        Client has exceeded the number of allowed requests in a given time period.

        |   |   |
        |---|---|
        | Rate limited, too many requests per second | User has exceeded their per second rate limit |
        | Rate limited, reached daily limit | User has exceeded their daily rate limit |
        | Rate limited, too many keys tried | One IP has queried too many different API keys |
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Forbidden:
      description: Client is not authorized to call the endpoint
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Unauthorized:
      description: User has not been authenticated. Invalid or missing API key.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    UnprocessableEntity:
      description: Unprocessable entity.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

# This defines which securitySchemes can be used in conjunction with each other.
# See components.securitySchemes for their definition.
security:
  - BasicAuth: []
  - ApiKeyAuth: []
  - {} # Indicates that no-auth is a valid option.

Example Stainless config

# yaml-language-server: $schema=https://app.stainless.com/config.schema.json

# 'organization' defines metadata such as the name of your organization, the
# docs site, contact information, which all get rendered on the SDK README.md.
organization:
  name: acme
  docs: https://docs.acme.com
  contact: support@acme.com

settings:
  license: Apache-2.0

edition: 2025-10-08

# 'resources' define the high level mapping of endpoints to the structure in
# each SDK. For example, the configuration below will correspond to being
# able to call
#
#   - client.status() which makes a request to GET /status
#
#   - client.accounts.friends.list() which makes a request to GET /accounts/{account_id}/friends
#
# As well as being able to access types with
#
#   import Acme from 'acme-typescript'
#
#   const result: Acme.Account = …
#
# https://www.stainless.com/docs/guides/configure#resources
resources:
  $client:
    methods:
      status: get /status
  accounts:
    models:
      account: "#/components/schemas/Account"
      account_configuration: "#/components/schemas/AccountConfiguration"
      account_link: "#/components/schemas/AccountLink"
    methods:
      list: get /accounts
      create: post /accounts
      retrieve: get /accounts/{account_id}
      update: put /accounts/{account_id}
      link:
        endpoint: post /accounts/{account_id}/link
        skip:
          - ruby
    subresources:
      friends:
        models:
          friend: "#/components/schemas/FriendResponse"
        methods:
          list: get /accounts/{account_id}/friends
          update: put /accounts/{account_id}/friends/{friend_id}
          delete: delete /accounts/{account_id}/friends/{friend_id}

# 'pagination' configures how your pagination style works, what request params
# and response fields map to which pagination roles, and how we match your
# endpoints against the pagination style.
#
# https://www.stainless.com/docs/configure/pagination
pagination:
  - name: cursor_page
    type: cursor
    request:
      cursor:
        type: string
      limit:
        type: integer
    response:
      data:
        type: array
        items: {}
      next_cursor:
        type: string
        nullable: true

# 'client_settings' primarily configures the general behavior of the api client,
# such as retries, timeouts, headers, and idempotency keys.
#
# 'client_settings.opts' defines extra arguments to add to your client,
# most prominently options that pertain to authentication, but could also be wired
# up to read from the environment and send a value as a header.
#
# https://www.stainless.com/docs/configure/client#client-opts
client_settings:
  idempotency:
    header: "Idempotency-Key"

  opts:
    username:
      type: string
      nullable: true
      auth:
        security_scheme: BasicAuth
        role: username
      read_env: ACME_USERNAME
    password:
      type: string
      nullable: true
      auth:
        security_scheme: BasicAuth
        role: password
      read_env: ACME_PASSWORD
    acme_api_key:
      type: string
      nullable: true
      auth:
        security_scheme: ApiKeyAuth
      read_env: ACME_API_KEY

# 'environments' map names of an environment to the corresponding base url.
environments:
  production: https://api.acme.com/v1
  sandbox: https://sandbox.acme.com/v1

# 'query_settings' define how more complex query parameters (such as objects and arrays)
# are rendered.
query_settings:
  nested_format: brackets
  array_format: repeat

# 'readme' defines what endpoints and arguments we should use to generate the snippets
# in the README of each language.
readme:
  example_requests:
    # The default example request is used for all snippets unless they are specifically overrode.
    default:
      type: request
      endpoint: post /accounts
      params: {}
    # You can explicitly override each example from the default case, such as 'headline'
    # which is the first snippet your user sees in the README. The 'default' example request
    # will still be used for all other example snippets.
    headline:
      type: request
      endpoint: post /accounts
      params: {}
    pagination:
      type: request
      endpoint: get /accounts
      params: {}
targets:
  typescript:
    edition: typescript.2025-10-10
    package_name: acme-typescript
    production_repo: stainless-sdks/acme-typescript-public
    publish:
      npm: true
  python:
    edition: python.2025-10-08
    package_name: acme
    project_name: acme-python
    production_repo: stainless-sdks/acme-python-public
    publish:
      pypi: true
  go:
    edition: go.2025-10-08
    package_name: acme-go
    production_repo: stainless-sdks/acme-go-public
  ruby:
    edition: ruby.2025-10-08
    gem_name: acme
    production_repo: stainless-sdks/acme-ruby-public
    publish:
      rubygems: false

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. For more information, including details about the improvements we’ve made in each edition, have a look at our editions reference.

Config

Key	Description
edition?	“2026-02-23” | “2026-01-30” | “2025-10-10” | “2025-10-08” | string
organization	Organization
targets?	{ node?: Node, typescript?: TypeScript, python?: Python, java?: Java, kotlin?: Kotlin, go?: Go, ruby?: Ruby, terraform?: Terraform, cli?: CLI, php?: PHP, csharp?: C#, openapi?: OpenAPI, sql?: { // Title for this package, typically used to display // the README header in the format <Title> API <br/> // Library (for example, “Your company language // library”)’ readme_title?: string, // The production repo that this target is linked // to. For example, AcmeOrg/acme-sql. // // You can optionally add a branch target, such as // AcmeOrg/acme-sql#master. By default, the target // branch is main. production_repo?: string | null, // URL of a screencast to showcase on the project // README. Must be an .mp4, .webm, or .mov file less // than 10MB. screencast?: string, // Skip generation for this target skip?: boolean, // An array of file paths, relative to the root of // the SDK repository, that will not be deleted // during codegen. Generally we recommend you use // custom code // instead, but keep_files can be useful for other // files you manually add that need to persist // through codegen. // // For example: // // ~~~yaml // keep_files: // - .github/workflows/ci_tests.yml // ~~~ keep_files?: Array<string>, edition?: “sql.2025-12-08” | string, // The name of the SQL extension. extension_name: string, publish: { pgxn: boolean, github?: { // Additional files to upload to GitHub Releases // after publishing. release_assets: Array<string | { // Name for this release asset in GitHub Releases. name?: string, // Path to the release asset file, relative to the // repository root. path: string, }>, }, // Release-please configuration. Controls the // generated release-please workflow and config // files. release?: { // Branch that release-please targets for release // PRs and changelog generation. branch?: string, // Whether to mark GitHub Releases as pre-releases. prerelease?: boolean, }, }, options?: { }, }, } Customization for each language’s repo name, package manager name, etc.
environments	Record<string, string> Map of the name of the environment which appears in the SDK to the corresponding url to use. The first environment in the map will be used as the default environment. environments: production: https://example.com/api sandbox: https://sandbox.example.com/api
resources	{ [x: string]: Resource, // Used to declare any models that should be shared // across resources. Defining methods in this // resource is not supported. $shared?: Resource, // Used to define methods and resources at the // client level, e.g. for an API status endpoint $client?: Resource, } Resources define the organization for your API and the endpoints that are available under which resources.
readme	Readme
settings	Settings
query_settings	QuerySettings
multipart_settings?	{ // Configures how arrays are serialized in // multipart/form-data request bodies. Accepted // values are brackets, comma, repeat, and // indices. // // When not set, each language SDK uses its existing // default: // - TypeScript, Python: brackets // - Ruby, PHP: repeat // - Go v1: indices (dot-separated) // - Java, Kotlin, C#, Go v2: inherits from // query_settings.array_format // // Example array: &#123; items: ["foo", "bar"] &#125; // // - brackets syntax -> items[]=foo&items[]=bar // - comma syntax -> items=foo,bar // - repeat syntax -> items=foo&items=bar // - indices syntax -> items[0]=foo&items[1]=bar array_format?: “comma” | “repeat” | “indices” | “brackets”, } Multipart form data serialization options.
security?	Array<SecurityConfig> Overrides the top-level security key in the OpenAPI spec. See our authentication documentation for more details.
security_schemes?	Record<string, SecurityScheme> Overrides the components.securitySchemes in the OpenAPI spec.
client_settings?	ClientSettings
pagination?	{ description?: string, type: “cursor” | “cursor_id” | “cursor_url” | “fake_page” | “offset” | “page_number”, request: Record<string, unknown>, response: Record<string, unknown>, param_location?: “query” | “body”, // If set to true, the auto pagination helpers will // continue to fetch pages even if there are no // items returned, and will only stop when it is // impossible to fetch another page continue_on_empty_items?: boolean, } | Array<PaginationScheme> Defines pagination schemes for pagination helpers and auto-pagination in the SDKs. See our pagination guide for more details and examples.
unspecified_endpoints?	Array<string> List of endpoints to explicitly ignore, such as [“post /internal_endpoint”, “get /redundant_endpoint”]
codeflow?	CodeflowConfig
custom_casings?	Record<string, InitialismConfig | CasingConfig | { singular: CasingConfig, plural: CasingConfig, }> Defines how phrases are rendered in different SDKs. Can be either an ‘initialism’ which tells the generator to treat the word as an abbreviation like ‘API’ or ‘CPU’, or a more powerful CasingConfig which can specify how that word is represented in the different casing formats. In rare cases where customization of pluralization is required, you can also specify singular/plural versions of the word.
openapi?	OpenAPIConfig
streaming?	StreamingConfig See our streaming configuration guide for more details.
constants?	{ // Constant values that should be exported from the // root package in an SDK. Currently only supported // for Python and TypeScript SDKs. package: Record<string, unknown>, }
diagnostics?	DiagnosticsConfig

Organization - organization

How the organization is represented in the SDKs, such as name and github_org.

Key	Description
name	string Name of your organization or company, in lowercase. Used in documentation. The generated client name defaults to this. To customize the capitalization, use custom_casings.
docs?	string Link to your API documentation.
contact?	string Contact email for bug reports, questions, and support requests.
security_contact?	string Security email address for reporting vulnerabilities. Will be mentioned in the generated SECURITY.md. Defaults to the contact email.
security_policy_url?	string Link to a page covering your security policy. Will be mentioned in the generated SECURITY.md.
security_policy_terms?	string Terms for your security policy. Will be added to the generated SECURITY.md. Stainless always generates a default security policy covering SDKs security issues. This field is for additional terms you want to add and will be included in a section ’[Your org name] Terms and Policies’.
github_org?	string Name of the GitHub organization that the production SDKs live in.
upload_spec?	boolean Whether or not to enable uploading the input openapi spec and publicly exposing it in the SDK. This allows running tests in the SDKs against a mock server, and if disabled will disable tests from automatically running in CI.

Targets - targets

TypeScript - targets.typescript

Key	Description
readme_title?	string Title for this package, typically used to display the README header in the format <Title> API Library (for example, “Your company language library”)‘
production_repo?	string | null The production repo that this target is linked to. For example, AcmeOrg/acme-typescript. You can optionally add a branch target, such as AcmeOrg/acme-typescript#master. By default, the target branch is main.
screencast?	string URL of a screencast to showcase on the project README. Must be an .mp4, .webm, or .mov file less than 10MB.
skip?	boolean Skip generation for this target
keep_files?	Array<string> An array of file paths, relative to the root of the SDK repository, that will not be deleted during codegen. Generally we recommend you use custom code instead, but keep_files can be useful for other files you manually add that need to persist through codegen. For example: keep_files: - .github/workflows/ci_tests.yml
edition?	“typescript.2025-10-10” | “typescript.2025-10-08” | string
package_name	string The name of the package in the import such as import … from “<package_name>” and the name in package.json.
publish	{ npm: boolean | { // By default, publishing to npm uses Access Tokens. // You can instead opt to use Github Actions OIDC // tokens. auth_method?: “access-token” | “oidc”, // GitHub environment to run the publish workflow in. release_environment?: string, }, jsr?: boolean | { // GitHub environment to run the publish workflow in. release_environment?: string, // The name of the package in the jsr repository. package_name: string, // By default, publishing to jsr uses GitHub Actions // OIDC tokens. This should be set to true if you // want to publish using an access tokens instead. use_access_token?: boolean, }, github?: { // Additional files to upload to GitHub Releases // after publishing. release_assets: Array<string | { // Name for this release asset in GitHub Releases. name?: string, // Path to the release asset file, relative to the // repository root. path: string, }>, }, // Release-please configuration. Controls the // generated release-please workflow and config // files. release?: { // Branch that release-please targets for release // PRs and changelog generation. branch?: string, // Whether to mark GitHub Releases as pre-releases. prerelease?: boolean, }, }
options?	{ // Enable MCP server generation. // // If enabled, will create a sub-directory in the // SDK under packages/mcp-server. // For more information: // https://modelcontextprotocol.io/introduction mcp_server?: boolean | MCP, browser?: { // If set to dangerous_allow then the SDK will // only be usable in the browser when passing an // explicit flag. state?: “allow” | “disallow” | “dangerous_allow”, // The error message to throw. message?: string, // Headers to use when making requests from a web // browser. headers?: Record<string, string>, }, // If you’re migrating from a node target to // typescript you can specify 2 version strings // that will be used in the migration guides and // scripts. // // The versions will be used verbatim, such as in // “Run migrations from your-sdk v{previous_version} // to v{migrated_version}”. // // If your SDK is post-1.0, we recommend to only // include the major version, such as // previous_version: "2", migrated_version: "3". node_migration?: { previous_version: string, migrated_version: string, }, // Allows your users to include a subset of the // SDK’s resources, resulting in smaller bundles. enable_treeshaking?: boolean, // The package manager used to install dependencies // and manage project builds. package_manager?: “pnpm” | “yarn”, }

MCP - targets.typescript.options.mcp_server

Key	Description
package_name?	string The name of the mcp package. Defaults to <typescript-package>-mcp
enable_code_tool?	boolean Generate a tool for the MCP server to take action with your SDK. This allows agents to perform tasks using your SDK by writing TypeScript code, which is executed securely in a sandbox.
enable_docs_tool?	boolean Generate a tool for the MCP server to look up documentation for your Stainless SDK. This requires you to expose the SDK docs search API for your project.
generate_cloudflare_worker?	boolean Generates a cloudflare worker that you can deploy as a Remote MCP Server in your own Cloudflare account. This is useful if you want to easily set up an MCP server that handles OAuth for use in web clients like claude.ai. See https://www.stainless.com/docs/guides/generate-an-mcp-server#deploy-a-remote-mcp-server for more information.
instructions?	string Instructions for the MCP client on to use the MCP server. This is sent as a part of MCP server initialization, and enters the client’s context. Defaults to no instructions being sent. See https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle#initialization for more information.
oauth_resource_metadata?	{ // List of OAuth authorization server URLs to // advertise to MCP clients authorization_servers: Array<string>, // List of scopes to advertise to MCP clients scopes_supported?: Array<string>, } OAuth protected resource metadata to expose when running with Streamable HTTP transport.
publish?	{ // Docker image publishing configuration. Set to // false to disable, string for image name, or // object for full config. docker?: false | string | { // GitHub environment to run the publish workflow in. release_environment?: string, // The Docker image name, e.g. “myorg/my-api-mcp” image_name: string, // The Docker registry to publish to registry?: string, }, github?: { // Additional files to upload to GitHub Releases // after publishing. release_assets: Array<string | { // Name for this release asset in GitHub Releases. name?: string, // Path to the release asset file, relative to the // repository root. path: string, }>, }, // Release-please configuration. Controls the // generated release-please workflow and config // files. release?: { // Branch that release-please targets for release // PRs and changelog generation. branch?: string, // Whether to mark GitHub Releases as pre-releases. prerelease?: boolean, }, }

Node - targets.node (deprecated)

The node target is deprecated in favor of the typescript target. See the changelog entry and the migration guide for more information.

Key	Description
readme_title?	string Title for this package, typically used to display the README header in the format <Title> API Library (for example, “Your company language library”)‘
production_repo?	string | null The production repo that this target is linked to. For example, AcmeOrg/acme-typescript. You can optionally add a branch target, such as AcmeOrg/acme-typescript#master. By default, the target branch is main.
screencast?	string URL of a screencast to showcase on the project README. Must be an .mp4, .webm, or .mov file less than 10MB.
skip?	boolean Skip generation for this target
keep_files?	Array<string> An array of file paths, relative to the root of the SDK repository, that will not be deleted during codegen. Generally we recommend you use custom code instead, but keep_files can be useful for other files you manually add that need to persist through codegen. For example: keep_files: - .github/workflows/ci_tests.yml
edition?	“node.2025-10-08” | string
package_name	string The name of the package in the import such as import … from “<package_name>” and the name in package.json.
publish	{ npm: boolean, jsr?: boolean | { // GitHub environment to run the publish workflow in. release_environment?: string, // The name of the package in the jsr repository. package_name: string, // By default, publishing to jsr uses GitHub Actions // OIDC tokens. This should be set to true if you // want to publish using an access tokens instead. use_access_token?: boolean, }, github?: { // Additional files to upload to GitHub Releases // after publishing. release_assets: Array<string | { // Name for this release asset in GitHub Releases. name?: string, // Path to the release asset file, relative to the // repository root. path: string, }>, }, // Release-please configuration. Controls the // generated release-please workflow and config // files. release?: { // Branch that release-please targets for release // PRs and changelog generation. branch?: string, // Whether to mark GitHub Releases as pre-releases. prerelease?: boolean, }, }
options?	{ // Enable MCP server generation. // // If enabled, will create a sub-directory in the // SDK under packages/mcp-server. // For more information: // https://modelcontextprotocol.io/introduction mcp_server?: boolean | MCP, browser?: { // If set to dangerous_allow then the SDK will // only be usable in the browser when passing an // explicit flag. state?: “allow” | “disallow” | “dangerous_allow”, // The error message to throw. message?: string, // Headers to use when making requests from a web // browser. headers?: Record<string, string>, }, }

Python - targets.python

Key	Description
readme_title?	string Title for this package, typically used to display the README header in the format <Title> API Library (for example, “Your company language library”)‘
production_repo?	string | null The production repo that this target is linked to. For example, AcmeOrg/acme-typescript. You can optionally add a branch target, such as AcmeOrg/acme-typescript#master. By default, the target branch is main.
screencast?	string URL of a screencast to showcase on the project README. Must be an .mp4, .webm, or .mov file less than 10MB.
skip?	boolean Skip generation for this target
keep_files?	Array<string> An array of file paths, relative to the root of the SDK repository, that will not be deleted during codegen. Generally we recommend you use custom code instead, but keep_files can be useful for other files you manually add that need to persist through codegen. For example: keep_files: - .github/workflows/ci_tests.yml
edition?	“python.2025-11-20” | “python.2025-10-08” | string
package_name	string The name of the import, e.g. from <package_name> import …
project_name?	string The Python project name, e.g. pip install <project_name>
publish	{ pypi: boolean | { // GitHub environment to run the publish workflow in. release_environment?: string, // Configure the authentication strategy for // publishing to PyPi. Defaults to api-token, // specify oidc to enable GitHub Actions OIDC // support. auth_method?: “api-token” | “oidc”, // The name of the package in pypi, e.g. pip <br/> // install <package_name> package_name?: string, }, github?: { // Additional files to upload to GitHub Releases // after publishing. release_assets: Array<string | { // Name for this release asset in GitHub Releases. name?: string, // Path to the release asset file, relative to the // repository root. path: string, }>, }, // Release-please configuration. Controls the // generated release-please workflow and config // files. release?: { // Branch that release-please targets for release // PRs and changelog generation. branch?: string, // Whether to mark GitHub Releases as pre-releases. prerelease?: boolean, }, }
options?	{ // In the python.2025-11-20 edition we switched the // default package manger from Rye // (https://rye.astral.sh) to uv // (https://docs.astral.sh/uv/). This property // allows you to control if uv is used regardless of // edition. use_uv?: boolean, // Customise the required python range for users. // Useful if you have custom dependencies with // different version ranges. python_version_range?: string, // Change the name of the dependency group for // websocket support, e.g. pip install // apiclient[websocket] to pip install // apiclient[my_websocket_api]. websockets_extra_name?: string, // Change the name of the dependency group for // standard webhooks support, e.g. pip install <br/> // apiclient[webhooks] to pip install <br/> // apiclient[my_webhooks_name]. standardwebhooks_extra_name?: string, }

Go - targets.go

Key	Description
readme_title?	string Title for this package, typically used to display the README header in the format <Title> API Library (for example, “Your company language library”)‘
production_repo?	string | null The production repo that this target is linked to. For example, AcmeOrg/acme-typescript. You can optionally add a branch target, such as AcmeOrg/acme-typescript#master. By default, the target branch is main.
screencast?	string URL of a screencast to showcase on the project README. Must be an .mp4, .webm, or .mov file less than 10MB.
skip?	boolean Skip generation for this target
keep_files?	Array<string> An array of file paths, relative to the root of the SDK repository, that will not be deleted during codegen. Generally we recommend you use custom code instead, but keep_files can be useful for other files you manually add that need to persist through codegen. For example: keep_files: - .github/workflows/ci_tests.yml
edition?	“go.2026-04-15” | “go.2026-03-10” | “go.2026-2-3” | “go.2025-10-08” | string
package_name	string The name of the root package, containing the top-level client, options, and methods.
options?	{ // Override the Go module path used in imports. For // example, if your module is hosted at // my-custom-host.com/acme/terraform-provider-acme // instead of the default // {repository.host}/{repository.full_name}. The // major version suffix (e.g. /v2) is still // appended automatically. go_module_path_override?: string, // Override the name used for the internal option // package option_package_name?: string, // Overrides the name used for the API client // struct. This name should be pascal cased and a // valid public Go identifier. By default, this is // Client, and the constructor will be called // NewClient. // // Overriding it to e.g. APIClient will change the // struct to be APIClient, and the corresponding // constructor will be called NewAPIClient. client_name?: string, // Explicitly set the Go version to use go_language_version?: string, code_style?: “v2” | “v2_migration” | “v1” | null, // Enable the V2 Go SDK generator with “true” or // “migration”. Caution: the V2 SDK is not // backwards compatible with V1. // // Defaults to ‘false’ if not specified. enable_v2?: boolean, // Generates getter methods to access nested // properties in unions without needing to switch on // the variant. union_property_getters?: boolean, // Doesn’t suffix union types with ‘-Union’, and // removes the ‘Of-’ prefix from union variant // names. This option is not recommended for // large (or soon-to-be large) APIs, as it comes // with visual clarity and forwards compatibility // costs. subtle_union_naming?: boolean, // Doesn’t suffix params types with ‘-Param’. Use // with caution: this means models cannot be used in // both params and response (without additional // configuration). Currently available for Go V2 // only. remove_params_suffix?: boolean, // Setting to false will not automatically apply URI // encoding to path parameters. path_param_encoding?: boolean, // In the Go Standard Library HTML in JSON is // escaped by default, so this defaults to true. escape_html_in_json?: boolean, // Generate pointers for nullable values inside maps // and arrays (e.g. map[string]*string instead of // map[string]string, []*string instead of // []string). // // Go V2 only — Go V3 always applies this behavior. // Defaults to true starting with the // go.2026-04-15 edition. nullable_map_items?: boolean, // Setting to false makes the options field in // the client / service structs private back_compat_options_field_name?: boolean, }
publish?	{ github?: { // Additional files to upload to GitHub Releases // after publishing. release_assets: Array<string | { // Name for this release asset in GitHub Releases. name?: string, // Path to the release asset file, relative to the // repository root. path: string, }>, }, // Release-please configuration. Controls the // generated release-please workflow and config // files. release?: { // Branch that release-please targets for release // PRs and changelog generation. branch?: string, // Whether to mark GitHub Releases as pre-releases. prerelease?: boolean, }, }

Java - targets.java

Key	Description
readme_title?	string Title for this package, typically used to display the README header in the format <Title> API Library (for example, “Your company language library”)‘
production_repo?	string | null The production repo that this target is linked to. For example, AcmeOrg/acme-typescript. You can optionally add a branch target, such as AcmeOrg/acme-typescript#master. By default, the target branch is main.
screencast?	string URL of a screencast to showcase on the project README. Must be an .mp4, .webm, or .mov file less than 10MB.
skip?	boolean Skip generation for this target
keep_files?	Array<string> An array of file paths, relative to the root of the SDK repository, that will not be deleted during codegen. Generally we recommend you use custom code instead, but keep_files can be useful for other files you manually add that need to persist through codegen. For example: keep_files: - .github/workflows/ci_tests.yml
edition?	“java.2025-10-08” | string
reverse_domain	string The reverse domain to generate the SDK under, e.g. if reverse_domain is “com.example.api”, then you would import the client as import com.example.api.client.okhttp.ExampleOkHttpClient
publish	{ maven: boolean | { // The maven groupId to publish this artifact to, // e.g. com.example.api. By default, uses the // value of reverse_domain. group_id?: string, // The maven artifactId to publish this artifact as, // defaults to <organization.name>-java, e.g. // example-java artifact_id?: string, // Customers who do not already have a Sonatype // OSSRH account should use the newer “portal” // option. sonatype_platform?: “portal” | “ossrh”, sonatype_host?: string, }, // Whether to generate and include HTML docs in the // published JAR. docs?: boolean, // Whether to generate and include [ProGuard keep // //www.guardsquare.com/manual/configuration/usage) // in the published JAR. proguard?: boolean, // Whether to generate and include [GraalVM // reachability // rg/latest/reference-manual/native-image/metadata) // in the published JAR. graalvm_metadata?: boolean, // Whether to generate and publish a [Spring Boot // ference/htmlsingle/#using.build-systems.starters) // artifact. spring_boot_starter?: boolean, github?: { // Additional files to upload to GitHub Releases // after publishing. release_assets: Array<string | { // Name for this release asset in GitHub Releases. name?: string, // Path to the release asset file, relative to the // repository root. path: string, }>, }, // Release-please configuration. Controls the // generated release-please workflow and config // files. release?: { // Branch that release-please targets for release // PRs and changelog generation. branch?: string, // Whether to mark GitHub Releases as pre-releases. prerelease?: boolean, }, } See our publishing guide for more information on how to publish your SDK.
options?	{ gradle_properties?: { // Override the JVM min memory in gradle.properties. // Defaults to “2g”. Format should be // [number][unit], e.g. “8g” or “8192m”. jvm_min_memory?: string, // Override the JVM max memory in gradle.properties. // Defaults to “8g”. Format should be // [number][unit], e.g. “8g” or “8192m”. jvm_max_memory?: string, }, }

Kotlin - targets.kotlin

Key	Description
readme_title?	string Title for this package, typically used to display the README header in the format <Title> API Library (for example, “Your company language library”)‘
production_repo?	string | null The production repo that this target is linked to. For example, AcmeOrg/acme-typescript. You can optionally add a branch target, such as AcmeOrg/acme-typescript#master. By default, the target branch is main.
screencast?	string URL of a screencast to showcase on the project README. Must be an .mp4, .webm, or .mov file less than 10MB.
skip?	boolean Skip generation for this target
keep_files?	Array<string> An array of file paths, relative to the root of the SDK repository, that will not be deleted during codegen. Generally we recommend you use custom code instead, but keep_files can be useful for other files you manually add that need to persist through codegen. For example: keep_files: - .github/workflows/ci_tests.yml
edition?	“kotlin.2025-10-08” | string
reverse_domain	string The reverse domain to generate the SDK under, e.g. if reverse_domain is “com.example.api”, then you would import the client as import com.example.api.client.okhttp.ExampleOkHttpClient
publish	{ maven: boolean | { // The maven groupId to publish this artifact to, // e.g. com.example.api. By default, uses the // value of reverse_domain. group_id?: string, // The maven artifactId to publish this artifact as, // defaults to <organization.name>-java, e.g. // example-java artifact_id?: string, // Customers who do not already have a Sonatype // OSSRH account should use the newer “portal” // option. sonatype_platform?: “portal” | “ossrh”, sonatype_host?: string, }, // Whether to generate and include HTML docs in the // published JAR. docs?: boolean, // Whether to generate and include [ProGuard keep // //www.guardsquare.com/manual/configuration/usage) // in the published JAR. proguard?: boolean, // Whether to generate and include [GraalVM // reachability // rg/latest/reference-manual/native-image/metadata) // in the published JAR. graalvm_metadata?: boolean, // Whether to generate and publish a [Spring Boot // ference/htmlsingle/#using.build-systems.starters) // artifact. spring_boot_starter?: boolean, github?: { // Additional files to upload to GitHub Releases // after publishing. release_assets: Array<string | { // Name for this release asset in GitHub Releases. name?: string, // Path to the release asset file, relative to the // repository root. path: string, }>, }, // Release-please configuration. Controls the // generated release-please workflow and config // files. release?: { // Branch that release-please targets for release // PRs and changelog generation. branch?: string, // Whether to mark GitHub Releases as pre-releases. prerelease?: boolean, }, } See our publishing guide for more information on how to publish your SDK.
options?	{ gradle_properties?: { // Override the JVM min memory in gradle.properties. // Defaults to “2g”. Format should be // [number][unit], e.g. “8g” or “8192m”. jvm_min_memory?: string, // Override the JVM max memory in gradle.properties. // Defaults to “8g”. Format should be // [number][unit], e.g. “8g” or “8192m”. jvm_max_memory?: string, }, }

Ruby - targets.ruby

Key	Description
readme_title?	string Title for this package, typically used to display the README header in the format <Title> API Library (for example, “Your company language library”)‘
production_repo?	string | null The production repo that this target is linked to. For example, AcmeOrg/acme-typescript. You can optionally add a branch target, such as AcmeOrg/acme-typescript#master. By default, the target branch is main.
screencast?	string URL of a screencast to showcase on the project README. Must be an .mp4, .webm, or .mov file less than 10MB.
skip?	boolean Skip generation for this target
keep_files?	Array<string> An array of file paths, relative to the root of the SDK repository, that will not be deleted during codegen. Generally we recommend you use custom code instead, but keep_files can be useful for other files you manually add that need to persist through codegen. For example: keep_files: - .github/workflows/ci_tests.yml
edition?	“ruby.2025-10-08” | string
gem_name	string The name of the gem.
package_name?	string | null Overrides the name used for the root module. This name should a valid public Ruby identifier. By default, this is the pascal case gem name. i.e. if the gem name is “super-acme”, the default root module name would be “SuperAcme”.
publish	{ rubygems: boolean, github?: { // Additional files to upload to GitHub Releases // after publishing. release_assets: Array<string | { // Name for this release asset in GitHub Releases. name?: string, // Path to the release asset file, relative to the // repository root. path: string, }>, }, // Release-please configuration. Controls the // generated release-please workflow and config // files. release?: { // Branch that release-please targets for release // PRs and changelog generation. branch?: string, // Whether to mark GitHub Releases as pre-releases. prerelease?: boolean, }, }
options?	{ // Overrides the name used for the API client // struct. This name should be a valid public Ruby // identifier. By default, this is Client. // // Overriding it to e.g. APIClient will change the // class to be APIClient. client_name?: string, }

CLI - targets.cli

Key	Description
readme_title?	string Title for this package, typically used to display the README header in the format <Title> API Library (for example, “Your company language library”)‘
production_repo?	string | null The production repo that this target is linked to. For example, AcmeOrg/acme-typescript. You can optionally add a branch target, such as AcmeOrg/acme-typescript#master. By default, the target branch is main.
screencast?	string URL of a screencast to showcase on the project README. Must be an .mp4, .webm, or .mov file less than 10MB.
skip?	boolean Skip generation for this target
keep_files?	Array<string> An array of file paths, relative to the root of the SDK repository, that will not be deleted during codegen. Generally we recommend you use custom code instead, but keep_files can be useful for other files you manually add that need to persist through codegen. For example: keep_files: - .github/workflows/ci_tests.yml
edition?	“cli.2025-10-08” | string
binary_name?	string The name of the binary, defaults to the repository name.
options?	{ // Override the Go module path used in imports. For // example, if your module is hosted at // my-custom-host.com/acme/terraform-provider-acme // instead of the default // {repository.host}/{repository.full_name}. The // major version suffix (e.g. /v2) is still // appended automatically. go_module_path_override?: string, // Set which package to use for your API’s Go SDK to // use go_sdk_package?: string, // Set which version of your API’s Go SDK to use go_sdk_version?: string, // Explicitly set the Go version to use go_language_version?: string, }
default_format?	“auto” | “explore” | “json” | “jsonl” | “pretty” | “raw” | “yaml” The default output format for CLI methods. This can be overridden on each endpoint in its cli.format option or with the —format flag when running the command.
default_json_get_format?	“auto” | “explore” | “json” | “jsonl” | “pretty” | “raw” | “yaml” The default output format for CLI GET endpoints that return JSON (excludes binary responses). When set, this overrides default_format for those endpoints. This can be overridden on each endpoint in its cli.format option or with the —format flag when running the command.
default_error_format?	“auto” | “explore” | “json” | “jsonl” | “pretty” | “raw” | “yaml” The default output format for CLI error responses. This can be overridden on each endpoint in its cli.error_format option or with the —format-error flag when running the command.
publish?	{ // GitHub environment to run the CLI goreleaser // publish workflow in. Overrides // codeflow.release_environment for this workflow. release_environment?: string, macos?: boolean | { }, // Configuration for publishing to Homebrew homebrew?: { // The homebrew tap repository, e.g. // AcmeOrg/homebrew-acme tap_repo: string, // Homepage URL for the homebrew formula homepage?: string, // Description for the homebrew formula description?: string, }, github?: { // Additional files to upload to GitHub Releases // after publishing. release_assets: Array<string | { // Name for this release asset in GitHub Releases. name?: string, // Path to the release asset file, relative to the // repository root. path: string, }>, }, // Release-please configuration. Controls the // generated release-please workflow and config // files. release?: { // Branch that release-please targets for release // PRs and changelog generation. branch?: string, // Whether to mark GitHub Releases as pre-releases. prerelease?: boolean, }, }

PHP - targets.php

Key	Description
readme_title?	string Title for this package, typically used to display the README header in the format <Title> API Library (for example, “Your company language library”)‘
production_repo?	string | null The production repo that this target is linked to. For example, AcmeOrg/acme-php. You can optionally add a branch target, such as AcmeOrg/acme-php#master. By default, the target branch is main.
screencast?	string URL of a screencast to showcase on the project README. Must be an .mp4, .webm, or .mov file less than 10MB.
skip?	boolean Skip generation for this target
keep_files?	Array<string> An array of file paths, relative to the root of the SDK repository, that will not be deleted during codegen. Generally we recommend you use custom code instead, but keep_files can be useful for other files you manually add that need to persist through codegen. For example: keep_files: - .github/workflows/ci_tests.yml
edition?	“php.2025-10-08” | string
package_name	string The name of the root package, containing the top-level client, options, and methods. For example, package_name: acme would result in use Acme\Client for SDK users. Unlike the composer_package_name, this name is only used within the SDK library code.
composer_package_name?	string The ecosystem name of the package as used by Composer & Packagist. The name should resemble ‘acme/acme-php’.
publish?	{ // Whether to publish the package to releases to // Packagist. Use Packagist to verify the // composer_package_name is available first. packagist: boolean, github?: { // Additional files to upload to GitHub Releases // after publishing. release_assets: Array<string | { // Name for this release asset in GitHub Releases. name?: string, // Path to the release asset file, relative to the // repository root. path: string, }>, }, // Release-please configuration. Controls the // generated release-please workflow and config // files. release?: { // Branch that release-please targets for release // PRs and changelog generation. branch?: string, // Whether to mark GitHub Releases as pre-releases. prerelease?: boolean, }, }
options?	{ }

C# - targets.csharp

Key	Description
readme_title?	string Title for this package, typically used to display the README header in the format <Title> API Library (for example, “Your company language library”)‘
production_repo?	string | null The production repo that this target is linked to. For example, AcmeOrg/acme-csharp. You can optionally add a branch target, such as AcmeOrg/acme-csharp#master. By default, the target branch is main.
screencast?	string URL of a screencast to showcase on the project README. Must be an .mp4, .webm, or .mov file less than 10MB.
skip?	boolean Skip generation for this target
keep_files?	Array<string> An array of file paths, relative to the root of the SDK repository, that will not be deleted during codegen. Generally we recommend you use custom code instead, but keep_files can be useful for other files you manually add that need to persist through codegen. For example: keep_files: - .github/workflows/ci_tests.yml
edition?	“csharp.2025-10-08” | string
package_name	string The name of the root package, containing the top-level client, options, and methods.
publish	{ nuget: boolean, github?: { // Additional files to upload to GitHub Releases // after publishing. release_assets: Array<string | { // Name for this release asset in GitHub Releases. name?: string, // Path to the release asset file, relative to the // repository root. path: string, }>, }, // Release-please configuration. Controls the // generated release-please workflow and config // files. release?: { // Branch that release-please targets for release // PRs and changelog generation. branch?: string, // Whether to mark GitHub Releases as pre-releases. prerelease?: boolean, }, }
strong_name?	{ // The assembly originator key file (snk file), in // base64 format. originator_key: string, // The public key associated with the assembly // originator key file. public_key: string, } Configuring strong naming. For more information, see https://learn.microsoft.com/en-us/dotnet/standard/assembly/strong-named
options?	{ // Set the C# language version (not the .NET // version). Stainless currently supports 10 or // 12. language_version?: “10” | “12”, // Whether to run unit tests against .NET 4.6.2. // Useful for ensuring the SDK is compatible with // .NET Standard 2.0. dotnetStandardTests?: boolean, }

Terraform - targets.terraform

Key	Description
readme_title?	string Title for this package, typically used to display the README header in the format <Title> API Library (for example, “Your company language library”)‘
screencast?	string URL of a screencast to showcase on the project README. Must be an .mp4, .webm, or .mov file less than 10MB.
skip?	boolean Skip generation for this target
keep_files?	Array<string> An array of file paths, relative to the root of the SDK repository, that will not be deleted during codegen. Generally we recommend you use custom code instead, but keep_files can be useful for other files you manually add that need to persist through codegen. For example: keep_files: - .github/workflows/ci_tests.yml
edition?	“terraform.2025-10-08” | string
production_repo	string | null The production repo that publishes to the Terraform Registry. The Terraform Registry requires GitHub repos to be prefixed with terraform-provider-<providername>, e.g. Acme-Org/terraform-provider-acme.
provider_name	string The name of the provider that users import. This is usually a single word, and is prefixed by your org name.
publish	{ // Enable releasing to Hashicorp. See // /docs/guides/publish#terraform-terraform-registry hashicorp_registry: boolean, github?: { // Additional files to upload to GitHub Releases // after publishing. release_assets: Array<string | { // Name for this release asset in GitHub Releases. name?: string, // Path to the release asset file, relative to the // repository root. path: string, }>, }, // Release-please configuration. Controls the // generated release-please workflow and config // files. release?: { // Branch that release-please targets for release // PRs and changelog generation. branch?: string, // Whether to mark GitHub Releases as pre-releases. prerelease?: boolean, }, }
options?	{ // Override the Go module path used in imports. For // example, if your module is hosted at // my-custom-host.com/acme/terraform-provider-acme // instead of the default // {repository.host}/{repository.full_name}. go_module_path_override?: string, // Explicitly set the Go SDK package to depend on go_sdk_package?: string, // Explicitly set the Go SDK version to depend on go_sdk_version?: string, // Explicitly set the Go version to use go_language_version?: string, // Automatically infer all possible resources and // data sources from the stainless config infer_all_services?: boolean, // Generate tfplugindocs // tps://github.com/hashicorp/terraform-plugin-docs) // for the provider generate_docs?: boolean, // whether to enable a timeout property for resources timeouts?: boolean | { // Attribute name for timeout parameter name?: string, // Default timeout for the resource and // subresources’ Terraform operations in // milliseconds or ISO8601. // // You can override this in subresources or // individual methods. // // This doesn’t affect the request-level timeout. default?: number | string, }, data_source?: { filtering: { // Attribute name for the find one by filter for // singular data sources find_one_by_property_name?: string, }, response_items: { // Attribute name for the result collection for list // data sources (default: items) collection_property_name?: string, // The maximum number of rows to fetch by default default_max_rows?: number, // Attribute name for the maximum number of rows in // the response max_rows_property_name?: string, }, }, }

OpenAPI - targets.openapi

Key	Description
readme_title?	string Title for this package, typically used to display the README header in the format <Title> API Library (for example, “Your company language library”)‘
production_repo?	string | null The production repo that this target is linked to. For example, AcmeOrg/acme-openapi. You can optionally add a branch target, such as AcmeOrg/acme-openapi#master. By default, the target branch is main.
screencast?	string URL of a screencast to showcase on the project README. Must be an .mp4, .webm, or .mov file less than 10MB.
skip?	boolean Skip generation for this target
keep_files?	Array<string> An array of file paths, relative to the root of the SDK repository, that will not be deleted during codegen. Generally we recommend you use custom code instead, but keep_files can be useful for other files you manually add that need to persist through codegen. For example: keep_files: - .github/workflows/ci_tests.yml
edition?	“openapi.2025-10-08” | string
options?	{ files?: Record<string, { with: Array<“code-samples” | “transforms”>, }>, }

SupportedLanguage

• node
• typescript
• python
• go
• java
• kotlin
• ruby
• terraform
• cli
• php
• csharp
• sql
• http
• openapi

Resource - resources.*

Key	Description
custom?	boolean Set custom: true to use customer_code content for the resource instead of generated code
models?	Record<string, string | Model> Configure the models—named types—defined in the resource. Each key in the object is the name of the model and the value is either the name of a schema in #/components/schemas or an object with more detail.
methods?	Record<string, string | Method> Configure the methods defined in this resource. Each key in the object is the name of the method and the value is either an endpoint (for example, get /foo) or an object with more detail.
description?	string Add a docstring for the resource.
standalone_api?	boolean If true, don’t prefix any type names with this resource or its ancestors’ names. For example, consider an external resource with customers nested under it: With standalone_api set to true, Go will generate an ExternalCustomerListParams type in the requests package. With standalone_api set to false, Go will generate a CustomerListParams type in the external_requests package.
terraform?	boolean | { // The name of the Terraform resource (prefixed by // your organization name) name?: string, // whether to enable a timeout property timeouts?: boolean | { // Attribute name for timeout parameter name?: string, // Default timeout for the resource and // subresources’ Terraform operations in // milliseconds or ISO8601. // // You can override this in subresources or // individual methods. // // This doesn’t affect the request-level timeout. default?: number | string, }, // Whether to generate Terraform resource resource?: boolean, // Whether to generate Terraform data sources data_source?: boolean | { filtering: { // Attribute name for the find one by filter for // singular data sources find_one_by_property_name?: string, }, response_items: { // Attribute name for the result collection for list // data sources (default: items) collection_property_name?: string, // The maximum number of rows to fetch by default default_max_rows?: number, // Attribute name for the maximum number of rows in // the response max_rows_property_name?: string, }, }, // Configures whether a warning message is shown to // users when they attempt to delete a resource that // does not have a delete endpoint. // // - warning: Does nothing upon delete, but // generates a warning message before the user // attempts to create or delete the resource. // // - no_warning: Does nothing upon delete, and does // not generate a warning message. unsupported_delete_behavior?: “warning” | “no_warning”, // Skip tests and provide a reason skip_tests_reason?: string, // The schema version for this resource. This is // used by Terraform to track schema changes // and perform state migrations when the schema // evolves over time. // // Only valid for resources, not data sources. // Typically incremented by 1 for each // breaking schema change. version?: integer, } Terraform configuration options for this resource.
use_namespace_in_type_names?	boolean If true, always prefix parameters and unnamed response types with resource names. If false, don’t prefix parameters and unnamed response types with ancestor resource names. If this property isn’t present in your Stainless config, the default behavior for the language will be used (e.g., Go always prefixes while Node doesn’t). For example, consider the nested resource /financial_accounts/balances. Set use_namespace_in_type_names to true to generate names like FinancialAccountBalanceListParams. Now consider the nested resource financial_accounts/financial_transactions. Set use_namespace_in_type_names to false to generate names like FinancialTransactionGetResponse without the FinancialAccount prefix.
subresources?	Record<string, Resource> Define nested namespaces for accessing models and methods. For example, with a “cards” resource containing a “transactions” subresource, the generated Python method invocation is client.cards.transactions.retrieve().
deprecated?	string | Record<string, string> Set the deprecation message for this resource
document?	boolean Set to false to suppress code snippet documentation output.
mcp?	boolean | { // A list of tags that end-users can use to filter // which resources and endpoints to include tags?: Array<string>, } whether to generate MCP Server tools for this resource
default_request_options?	{ headers?: Record<string, string>, } Configure the default request options for this resource.
skip?	boolean | Array<SupportedLanguage> Skip SDK generation for a resource by specifying skip: true. Skip SDK generation for a resource per language by specifying the languages to skip (for example, skip: [go, node]). Skipping generation can aid in debugging code generation errors.
only?	Array<SupportedLanguage> Opposite of skip; if set, SDK generation is only performed for this resource.

Method - resources.*.methods.*

Key	Description
type?	“http” Describes a method for a standard http endpoint.
endpoint	string A pair of HTTP verb & path, e.g. get /foo, post /transactions/{user_id}
unwrap_response?	string | false Response property to be unwrapped so users don’t have to access it themselves
paginated?	boolean | string Provide paginated: true for methods whose responses are paginated. Or provide a string naming the page whose pagination should be matched. If omitted, pagination configuration is automatically determined using matching pages in the configuration. Learn more: https://www.stainless.com/docs/configure/pagination
skip_test_reason?	string | Record<string, string> Skip the generated unit test in all languages or particular languages with a given reason. This will skip the test in all languages: skip_test_reason: “Requires body parameter not yet implement by test harness.” This will skip the test in a specific language (multiple languages also can be specified): skip_test_reason: ruby: “TODO: Investigate Ruby test failure.”
body_param_name?	string Parameter name to be used for the request parameters argument. Required when the request body is not an object (for example, an array).
positional_params?	Array<string> When specified, this overrides the default behavior (to use the last path parameter as a positional parameter). If a parameter is in this list, it is generated as a positional parameter in the given order. If a parameter is not in this list, it is generated as a structured/named parameter.
streaming?	{ // The streaming protocol. // // Defaults to the protocol inferred from the // method’s response schema, or sse if none could // be inferred. type?: “sse” | “jsonl”, // The params type name to use for the generated // params types, for example: // // If given: ‘create_completion_request’ then the // Node SDK types will be // ‘CreateCompletionRequestNonStreaming’ & // ‘CreateCompletionRequestStreaming’. params_type_name?: string, // The request parameter that indicates whether or // not the response is streamed. If the response is // always streamed this should be set to null param_discriminator: string | null, // Name for the streaming method variant, in // applicable languages. method_name?: string | { go?: string, ruby?: string, }, // The path to the model that corresponds to the // data that will be sent in each Server-Sent-Event. // The model has to be defined in the same resource // as this method. If not given, defaults to the // same as the response schema. // // This should be in the format: $resource.$model. stream_event_model?: string, // Whether to use the entire Server-Sent-Event, // serialized as &#123; "event": ..., "data": ... &#125;, // for the stream_event_model. synthesize_event_and_data_properties?: boolean, // Skip configuring streaming in certain languages skip?: Array<SupportedLanguage>, }
default_request_options?	{ // Timeout in milliseconds or ISO8601 timeout?: number | string | null, // The default number of times to retry a failing // request max_retries?: number, } Configure the default request options for an individual method
docs?	{ // Specify the response property to reference in // example snippets. Set to ‘false’ to disable // property references, e.g. for logging the entire // response. response_property?: false | string, }
terraform?	{ // Define the type of method this endpoint // represents. // - create: handles creation of the resource. Must // be a POST // - read: handles reading of the resource. Must be // a GET // - list: handles listing of the resource. Must be // a GET // - update: handles updating of the resource. Must // be a PUT or PATCH // - delete: handles deleting the resource. Must be // a DELETE // - upsert: handles both updating and creating of // the resource. Can be PUT or PATCH // - skip: don’t include this method in generation method?: “create” | “read” | “list” | “upsert” | “update” | “delete” | “skip”, // Defined the name of the path param that is used // as the ID of the resource. id_path_param?: string, // Define the name of the property that represents // the ID for the resource. It may exist as a path, // body, or response parameter. id_property?: string, // Specify how the update method on the resource // should encode the request body. // - put: The entire resource is replaced with the // new resource. // - json_merge_patch: The resource is updated as a // JSON Merge Patch, only providing changed fields. // // If null, then json_merge_patch will be used for // PATCH endpoints, and put otherwise. update_behavior?: “put” | “json_merge_patch”, // Timeout for the entire Terraform operation in // milliseconds or ISO8601. // // This doesn’t affect the request-level timeout. default_timeout?: number | string, }
mcp?	boolean | { // A list of tags that end-users can use to filter // which resources and endpoints to include tags?: Array<string>, // Override the tool name for this endpoint tool_name?: string, // Override the description for this endpoint description?: string, } whether to generate MCP Server tools for this endpoint
cli?	{ // Whether or not to generate this method as a CLI // command. enabled?: boolean, // The GJSON filter to use to filter response data // into a more manageable // format. This can be overridden with the // --filter flag. // // For GJSON syntax, see: // ://github.com/tidwall/gjson/blob/master/SYNTAX.md filter?: string, // The default output format for this endpoint. This // can be overridden with // the --format flag when running the command. format?: “auto” | “explore” | “json” | “pretty” | “raw” | “yaml”, }
skip?	boolean | Array<SupportedLanguage> Skip SDK generation for a resource by specifying skip: true. Skip SDK generation for a resource per language by specifying the languages to skip (for example, skip: [go, node]). Skipping generation can aid in debugging code generation errors.
only?	Array<SupportedLanguage> Opposite of skip; if set, SDK generation is only performed for this resource.
deprecated?	string | Record<string, string> Set the deprecation message for this method. To set different deprecation messages for each language, provide an object with properties for each language and a default to use for unspecified languages. For example: deprecated: typescript: “Use fooBar instead.” go: “Use FooBar instead.” default: “Use /v2/foo/bar instead.” To set the same deprecation message for all languages, provide only the deprecation message as a string: deprecated: “Use /v2/foo/bar instead.”
document?	boolean Set to false to suppress code snippet documentation output.

Key	Description
type	”webhook_unwrap”
event_types?	Record<string, string> Map of webhook event types in the format [event_name]: event operation in OAS spec. If empty, it will infer the names and use all operations.
webhook_key_opt?	string | { name: string, // The encoding that the webhook signing key should // be provided in. Defaults to base64. encoding?: “base64” | “utf-8”, } | null The name of the client option that stores the webhook key used for verifying webhooks (or null to skip verification checks).
description?	string
summary?	string
discriminator?	any Specify the name of the field used to differentiate between webhook payloads as a string, or provide an OpenAPI discriminator definition.
skip?	boolean | Array<SupportedLanguage> Skip SDK generation for a resource by specifying skip: true. Skip SDK generation for a resource per language by specifying the languages to skip (for example, skip: [go, node]). Skipping generation can aid in debugging code generation errors.
only?	Array<SupportedLanguage> Opposite of skip; if set, SDK generation is only performed for this resource.
deprecated?	string | Record<string, string> Set the deprecation message for this method. To set different deprecation messages for each language, provide an object with properties for each language and a default to use for unspecified languages. For example: deprecated: typescript: “Use fooBar instead.” go: “Use FooBar instead.” default: “Use /v2/foo/bar instead.” To set the same deprecation message for all languages, provide only the deprecation message as a string: deprecated: “Use /v2/foo/bar instead.”
document?	boolean Set to false to suppress code snippet documentation output.

Note: WebSocket support is currently experimental and is only supported in TypeScript and Python.

Key	Description
type	”websocket”
description?	string
summary?	string
path	string
event_name_separator?	string Used to generate helper methods for each client event in Python, e.g. . for audio.input_buffer.commit to then output ws.audio.input_buffer.commit(*params)
client_event_schema_uri	string The reference path to the schema, e.g. #/components/schemas/Card, or the shorthand Card.
server_event_schema_uri	string The reference path to the schema, e.g. #/components/schemas/Card, or the shorthand Card.
query_params_schema_uri?	string The reference path to the schema, e.g. #/components/schemas/Card, or the shorthand Card.
skip?	boolean | Array<SupportedLanguage> Skip SDK generation for a resource by specifying skip: true. Skip SDK generation for a resource per language by specifying the languages to skip (for example, skip: [go, node]). Skipping generation can aid in debugging code generation errors.
only?	Array<SupportedLanguage> Opposite of skip; if set, SDK generation is only performed for this resource.
deprecated?	string | Record<string, string> Set the deprecation message for this method. To set different deprecation messages for each language, provide an object with properties for each language and a default to use for unspecified languages. For example: deprecated: typescript: “Use fooBar instead.” go: “Use FooBar instead.” default: “Use /v2/foo/bar instead.” To set the same deprecation message for all languages, provide only the deprecation message as a string: deprecated: “Use /v2/foo/bar instead.”
document?	boolean Set to false to suppress code snippet documentation output.

Key	Description
type	”alias” Describes an ‘alias’ to a method in the same resource. Used mainly for renaming a method and maintaining backwards compatibility.
to	string The name of the method that this alias should point to. This currently only supports aliasing HTTP methods within the same resource.
skip?	boolean | Array<SupportedLanguage> Skip SDK generation for a resource by specifying skip: true. Skip SDK generation for a resource per language by specifying the languages to skip (for example, skip: [go, node]). Skipping generation can aid in debugging code generation errors.
only?	Array<SupportedLanguage> Opposite of skip; if set, SDK generation is only performed for this resource.
deprecated?	string | Record<string, string> Set the deprecation message for this method. To set different deprecation messages for each language, provide an object with properties for each language and a default to use for unspecified languages. For example: deprecated: typescript: “Use fooBar instead.” go: “Use FooBar instead.” default: “Use /v2/foo/bar instead.” To set the same deprecation message for all languages, provide only the deprecation message as a string: deprecated: “Use /v2/foo/bar instead.”
document?	boolean Set to false to suppress code snippet documentation output.

Model - resources.*.models.*

Key	Description
type?	“model”
openapi_uri	string openapi_uri is a reference to the OpenAPI definition of the schema, e.g. #/components/schemas/Card or #/components/schemas/CardList/items. All $ref and indirect references to the schema this path points to will have the same canonical name and share a type definition. For schemas under #/components/schemas/*, you can specify just the last path segment instead of the full JSON path (e.g. Card instead of #/components/schemas/Card). If you need a more powerful way to match a schema, openapi_uri can also be a JMESPath or a JSONPath-plus query. This query should match exactly one schema, and not mutate or create new references.
deduplicate?	Array<string> Declaring a schema to be a model transforms all referentially-equal versions of that schema in the OpenAPI spec to be rendered as a reference, rather than re-declaring the definition. This doesn’t work if the schemas you want to reference the model are not referentially the same (i.e. a $ref in the OpenAPI spec). deduplicate tells the Stainless generator to render the schemas listed on it to render them as a reference to the model. This is useful when you have schemas that are either exactly the same, but referentially not equal (e.g. not defined in #/components/schemas/… OR if the schemas are similar, but close enough that you would want them to be the same type in the generated SDK.
force_generation?	boolean Stainless won’t generate models that aren’t used in an endpoint. Set this to true to generate this model even if it’s not used.
force_params_generation?	boolean Stainless won’t generate parameter classes that aren’t used in an endpoint. Set this to true to generate this model even if it’s not used.
param_model?	string The path to the model that is the param version of this response model. Results in generating utilities for converting from this response model to its param version. This should be in the format: $resource.$model.
skip?	boolean | Array<SupportedLanguage> Skip SDK generation for a resource by specifying skip: true. Skip SDK generation for a resource per language by specifying the languages to skip (for example, skip: [go, node]). Skipping generation can aid in debugging code generation errors.
only?	Array<SupportedLanguage> Opposite of skip; if set, SDK generation is only performed for this resource.

Key	Description
type	”alias”
to	string The path to the model this alias should point to. The model does not need to be in the same resource. This should be in the format: $resource.$model.
deprecated?	string | Record<string, string> Set the deprecation message for this model
skip?	boolean | Array<SupportedLanguage> Skip SDK generation for a resource by specifying skip: true. Skip SDK generation for a resource per language by specifying the languages to skip (for example, skip: [go, node]). Skipping generation can aid in debugging code generation errors.
only?	Array<SupportedLanguage> Opposite of skip; if set, SDK generation is only performed for this resource.

Readme - readme

Configuration of the examples in the README.md of the generated SDKs.

Learn more: https://www.stainless.com/docs/configure/readme

Key	Description
example_requests	{ default: ReadmeExampleMethod, headline: ReadmeExampleMethod, // Example of how to handle errors in the SDK. // // NOTE: Even though this is an “error” example, it // should be well-formed! (E.g. it shouldn’t have // missing or invalid parameters.) // It demonstrates how to handle network errors and // the like, not how to handle malformed requests, // since the SDK ensures that requests are // well-formed. errors?: ReadmeExampleMethod & { // The response properties to show in this example // code. E.g.: // // example_properties: // error: ‘Rate limit exceeded.’ // request_id: ‘req_123’ example_properties?: Record<string, unknown>, }, // For example code that shows how to retry requests. retries?: ReadmeExampleMethod, // For example code that demonstrates nested // parameters. nested_params?: ReadmeExampleMethod, // For example code that shows how to use a custom // HTTP agent. http_agent?: ReadmeExampleMethod, // For example code that shows how to make a raw API // request. raw_response?: ReadmeExampleMethod, // For example code that shows how to handle // timeouts. timeouts?: ReadmeExampleMethod, // For example code that shows how to set default // headers. default_headers?: ReadmeExampleMethod, // For example code that shows how to use pagination. pagination?: ReadmeExampleMethod, // For example code that shows how to use streaming. streaming?: ReadmeExampleMethod, file_uploads?: { type: “request”, // Endpoint to use as the example method, in the // format post /foo/bar/&#123;id&#125; endpoint: string, // The request params to include in the example. // // e.g. // // params: // query_param: ‘foo’ // body_param: true // path_param: id params: Record<string, unknown>, // The property on the response to log, e.g. id on // a get /accounts endpoints adds a // console.log(account.id) or equivalent in the // example response_property?: string, // The name of the variable to assign the result of // this request to for this example. // // For example, given the method post <br/> // /v1/customers, set assign_to: customer to // produce example code like this: // // ~~~ts // customer = client.customers.create(); // ~~~ assign_to?: string, // The name of the request parameter for the file. // E.g., file file_param: string, // The path and filename of the file being uploaded. // E.g., my/file.txt file_path?: string, }, // Override specific examples for the Go SDK go?: { default?: ReadmeExampleMethod, headline?: ReadmeExampleMethod, // Example of how to handle errors in the SDK. // // NOTE: Even though this is an “error” example, it // should be well-formed! (E.g. it shouldn’t have // missing or invalid parameters.) // It demonstrates how to handle network errors and // the like, not how to handle malformed requests, // since the SDK ensures that requests are // well-formed. errors?: ReadmeExampleMethod & { // The response properties to show in this example // code. E.g.: // // example_properties: // error: ‘Rate limit exceeded.’ // request_id: ‘req_123’ example_properties?: Record<string, unknown>, }, // For example code that shows how to retry requests. retries?: ReadmeExampleMethod, // For example code that demonstrates nested // parameters. nested_params?: ReadmeExampleMethod, // For example code that shows how to use a custom // HTTP agent. http_agent?: ReadmeExampleMethod, // For example code that shows how to make a raw API // request. raw_response?: ReadmeExampleMethod, // For example code that shows how to handle // timeouts. timeouts?: ReadmeExampleMethod, // For example code that shows how to set default // headers. default_headers?: ReadmeExampleMethod, // For example code that shows how to use pagination. pagination?: ReadmeExampleMethod, // For example code that shows how to use streaming. streaming?: ReadmeExampleMethod, file_uploads?: { type: “request”, // Endpoint to use as the example method, in the // format post /foo/bar/&#123;id&#125; endpoint: string, // The request params to include in the example. // // e.g. // // params: // query_param: ‘foo’ // body_param: true // path_param: id params: Record<string, unknown>, // The property on the response to log, e.g. id on // a get /accounts endpoints adds a // console.log(account.id) or equivalent in the // example response_property?: string, // The name of the variable to assign the result of // this request to for this example. // // For example, given the method post <br/> // /v1/customers, set assign_to: customer to // produce example code like this: // // ~~~ts // customer = client.customers.create(); // ~~~ assign_to?: string, // The name of the request parameter for the file. // E.g., file file_param: string, // The path and filename of the file being uploaded. // E.g., my/file.txt file_path?: string, }, }, // Override specific examples for the TypeScript SDK typescript?: { default?: ReadmeExampleMethod, headline?: ReadmeExampleMethod, // Example of how to handle errors in the SDK. // // NOTE: Even though this is an “error” example, it // should be well-formed! (E.g. it shouldn’t have // missing or invalid parameters.) // It demonstrates how to handle network errors and // the like, not how to handle malformed requests, // since the SDK ensures that requests are // well-formed. errors?: ReadmeExampleMethod & { // The response properties to show in this example // code. E.g.: // // example_properties: // error: ‘Rate limit exceeded.’ // request_id: ‘req_123’ example_properties?: Record<string, unknown>, }, // For example code that shows how to retry requests. retries?: ReadmeExampleMethod, // For example code that demonstrates nested // parameters. nested_params?: ReadmeExampleMethod, // For example code that shows how to use a custom // HTTP agent. http_agent?: ReadmeExampleMethod, // For example code that shows how to make a raw API // request. raw_response?: ReadmeExampleMethod, // For example code that shows how to handle // timeouts. timeouts?: ReadmeExampleMethod, // For example code that shows how to set default // headers. default_headers?: ReadmeExampleMethod, // For example code that shows how to use pagination. pagination?: ReadmeExampleMethod, // For example code that shows how to use streaming. streaming?: ReadmeExampleMethod, file_uploads?: { type: “request”, // Endpoint to use as the example method, in the // format post /foo/bar/&#123;id&#125; endpoint: string, // The request params to include in the example. // // e.g. // // params: // query_param: ‘foo’ // body_param: true // path_param: id params: Record<string, unknown>, // The property on the response to log, e.g. id on // a get /accounts endpoints adds a // console.log(account.id) or equivalent in the // example response_property?: string, // The name of the variable to assign the result of // this request to for this example. // // For example, given the method post <br/> // /v1/customers, set assign_to: customer to // produce example code like this: // // ~~~ts // customer = client.customers.create(); // ~~~ assign_to?: string, // The name of the request parameter for the file. // E.g., file file_param: string, // The path and filename of the file being uploaded. // E.g., my/file.txt file_path?: string, }, }, // Override specific examples for the Java SDK java?: { default?: ReadmeExampleMethod, headline?: ReadmeExampleMethod, // Example of how to handle errors in the SDK. // // NOTE: Even though this is an “error” example, it // should be well-formed! (E.g. it shouldn’t have // missing or invalid parameters.) // It demonstrates how to handle network errors and // the like, not how to handle malformed requests, // since the SDK ensures that requests are // well-formed. errors?: ReadmeExampleMethod & { // The response properties to show in this example // code. E.g.: // // example_properties: // error: ‘Rate limit exceeded.’ // request_id: ‘req_123’ example_properties?: Record<string, unknown>, }, // For example code that shows how to retry requests. retries?: ReadmeExampleMethod, // For example code that demonstrates nested // parameters. nested_params?: ReadmeExampleMethod, // For example code that shows how to use a custom // HTTP agent. http_agent?: ReadmeExampleMethod, // For example code that shows how to make a raw API // request. raw_response?: ReadmeExampleMethod, // For example code that shows how to handle // timeouts. timeouts?: ReadmeExampleMethod, // For example code that shows how to set default // headers. default_headers?: ReadmeExampleMethod, // For example code that shows how to use pagination. pagination?: ReadmeExampleMethod, // For example code that shows how to use streaming. streaming?: ReadmeExampleMethod, file_uploads?: { type: “request”, // Endpoint to use as the example method, in the // format post /foo/bar/&#123;id&#125; endpoint: string, // The request params to include in the example. // // e.g. // // params: // query_param: ‘foo’ // body_param: true // path_param: id params: Record<string, unknown>, // The property on the response to log, e.g. id on // a get /accounts endpoints adds a // console.log(account.id) or equivalent in the // example response_property?: string, // The name of the variable to assign the result of // this request to for this example. // // For example, given the method post <br/> // /v1/customers, set assign_to: customer to // produce example code like this: // // ~~~ts // customer = client.customers.create(); // ~~~ assign_to?: string, // The name of the request parameter for the file. // E.g., file file_param: string, // The path and filename of the file being uploaded. // E.g., my/file.txt file_path?: string, }, }, // Override specific examples for the Kotlin SDK kotlin?: { default?: ReadmeExampleMethod, headline?: ReadmeExampleMethod, // Example of how to handle errors in the SDK. // // NOTE: Even though this is an “error” example, it // should be well-formed! (E.g. it shouldn’t have // missing or invalid parameters.) // It demonstrates how to handle network errors and // the like, not how to handle malformed requests, // since the SDK ensures that requests are // well-formed. errors?: ReadmeExampleMethod & { // The response properties to show in this example // code. E.g.: // // example_properties: // error: ‘Rate limit exceeded.’ // request_id: ‘req_123’ example_properties?: Record<string, unknown>, }, // For example code that shows how to retry requests. retries?: ReadmeExampleMethod, // For example code that demonstrates nested // parameters. nested_params?: ReadmeExampleMethod, // For example code that shows how to use a custom // HTTP agent. http_agent?: ReadmeExampleMethod, // For example code that shows how to make a raw API // request. raw_response?: ReadmeExampleMethod, // For example code that shows how to handle // timeouts. timeouts?: ReadmeExampleMethod, // For example code that shows how to set default // headers. default_headers?: ReadmeExampleMethod, // For example code that shows how to use pagination. pagination?: ReadmeExampleMethod, // For example code that shows how to use streaming. streaming?: ReadmeExampleMethod, file_uploads?: { type: “request”, // Endpoint to use as the example method, in the // format post /foo/bar/&#123;id&#125; endpoint: string, // The request params to include in the example. // // e.g. // // params: // query_param: ‘foo’ // body_param: true // path_param: id params: Record<string, unknown>, // The property on the response to log, e.g. id on // a get /accounts endpoints adds a // console.log(account.id) or equivalent in the // example response_property?: string, // The name of the variable to assign the result of // this request to for this example. // // For example, given the method post <br/> // /v1/customers, set assign_to: customer to // produce example code like this: // // ~~~ts // customer = client.customers.create(); // ~~~ assign_to?: string, // The name of the request parameter for the file. // E.g., file file_param: string, // The path and filename of the file being uploaded. // E.g., my/file.txt file_path?: string, }, }, // Override specific examples for the Ruby SDK ruby?: { default?: ReadmeExampleMethod, headline?: ReadmeExampleMethod, // Example of how to handle errors in the SDK. // // NOTE: Even though this is an “error” example, it // should be well-formed! (E.g. it shouldn’t have // missing or invalid parameters.) // It demonstrates how to handle network errors and // the like, not how to handle malformed requests, // since the SDK ensures that requests are // well-formed. errors?: ReadmeExampleMethod & { // The response properties to show in this example // code. E.g.: // // example_properties: // error: ‘Rate limit exceeded.’ // request_id: ‘req_123’ example_properties?: Record<string, unknown>, }, // For example code that shows how to retry requests. retries?: ReadmeExampleMethod, // For example code that demonstrates nested // parameters. nested_params?: ReadmeExampleMethod, // For example code that shows how to use a custom // HTTP agent. http_agent?: ReadmeExampleMethod, // For example code that shows how to make a raw API // request. raw_response?: ReadmeExampleMethod, // For example code that shows how to handle // timeouts. timeouts?: ReadmeExampleMethod, // For example code that shows how to set default // headers. default_headers?: ReadmeExampleMethod, // For example code that shows how to use pagination. pagination?: ReadmeExampleMethod, // For example code that shows how to use streaming. streaming?: ReadmeExampleMethod, file_uploads?: { type: “request”, // Endpoint to use as the example method, in the // format post /foo/bar/&#123;id&#125; endpoint: string, // The request params to include in the example. // // e.g. // // params: // query_param: ‘foo’ // body_param: true // path_param: id params: Record<string, unknown>, // The property on the response to log, e.g. id on // a get /accounts endpoints adds a // console.log(account.id) or equivalent in the // example response_property?: string, // The name of the variable to assign the result of // this request to for this example. // // For example, given the method post <br/> // /v1/customers, set assign_to: customer to // produce example code like this: // // ~~~ts // customer = client.customers.create(); // ~~~ assign_to?: string, // The name of the request parameter for the file. // E.g., file file_param: string, // The path and filename of the file being uploaded. // E.g., my/file.txt file_path?: string, }, }, // Override specific examples for the PHP SDK php?: { default?: ReadmeExampleMethod, headline?: ReadmeExampleMethod, // Example of how to handle errors in the SDK. // // NOTE: Even though this is an “error” example, it // should be well-formed! (E.g. it shouldn’t have // missing or invalid parameters.) // It demonstrates how to handle network errors and // the like, not how to handle malformed requests, // since the SDK ensures that requests are // well-formed. errors?: ReadmeExampleMethod & { // The response properties to show in this example // code. E.g.: // // example_properties: // error: ‘Rate limit exceeded.’ // request_id: ‘req_123’ example_properties?: Record<string, unknown>, }, // For example code that shows how to retry requests. retries?: ReadmeExampleMethod, // For example code that demonstrates nested // parameters. nested_params?: ReadmeExampleMethod, // For example code that shows how to use a custom // HTTP agent. http_agent?: ReadmeExampleMethod, // For example code that shows how to make a raw API // request. raw_response?: ReadmeExampleMethod, // For example code that shows how to handle // timeouts. timeouts?: ReadmeExampleMethod, // For example code that shows how to set default // headers. default_headers?: ReadmeExampleMethod, // For example code that shows how to use pagination. pagination?: ReadmeExampleMethod, // For example code that shows how to use streaming. streaming?: ReadmeExampleMethod, file_uploads?: { type: “request”, // Endpoint to use as the example method, in the // format post /foo/bar/&#123;id&#125; endpoint: string, // The request params to include in the example. // // e.g. // // params: // query_param: ‘foo’ // body_param: true // path_param: id params: Record<string, unknown>, // The property on the response to log, e.g. id on // a get /accounts endpoints adds a // console.log(account.id) or equivalent in the // example response_property?: string, // The name of the variable to assign the result of // this request to for this example. // // For example, given the method post <br/> // /v1/customers, set assign_to: customer to // produce example code like this: // // ~~~ts // customer = client.customers.create(); // ~~~ assign_to?: string, // The name of the request parameter for the file. // E.g., file file_param: string, // The path and filename of the file being uploaded. // E.g., my/file.txt file_path?: string, }, }, // Override specific examples for the C# SDK csharp?: { default?: ReadmeExampleMethod, headline?: ReadmeExampleMethod, // Example of how to handle errors in the SDK. // // NOTE: Even though this is an “error” example, it // should be well-formed! (E.g. it shouldn’t have // missing or invalid parameters.) // It demonstrates how to handle network errors and // the like, not how to handle malformed requests, // since the SDK ensures that requests are // well-formed. errors?: ReadmeExampleMethod & { // The response properties to show in this example // code. E.g.: // // example_properties: // error: ‘Rate limit exceeded.’ // request_id: ‘req_123’ example_properties?: Record<string, unknown>, }, // For example code that shows how to retry requests. retries?: ReadmeExampleMethod, // For example code that demonstrates nested // parameters. nested_params?: ReadmeExampleMethod, // For example code that shows how to use a custom // HTTP agent. http_agent?: ReadmeExampleMethod, // For example code that shows how to make a raw API // request. raw_response?: ReadmeExampleMethod, // For example code that shows how to handle // timeouts. timeouts?: ReadmeExampleMethod, // For example code that shows how to set default // headers. default_headers?: ReadmeExampleMethod, // For example code that shows how to use pagination. pagination?: ReadmeExampleMethod, // For example code that shows how to use streaming. streaming?: ReadmeExampleMethod, file_uploads?: { type: “request”, // Endpoint to use as the example method, in the // format post /foo/bar/&#123;id&#125; endpoint: string, // The request params to include in the example. // // e.g. // // params: // query_param: ‘foo’ // body_param: true // path_param: id params: Record<string, unknown>, // The property on the response to log, e.g. id on // a get /accounts endpoints adds a // console.log(account.id) or equivalent in the // example response_property?: string, // The name of the variable to assign the result of // this request to for this example. // // For example, given the method post <br/> // /v1/customers, set assign_to: customer to // produce example code like this: // // ~~~ts // customer = client.customers.create(); // ~~~ assign_to?: string, // The name of the request parameter for the file. // E.g., file file_param: string, // The path and filename of the file being uploaded. // E.g., my/file.txt file_path?: string, }, }, // Override specific examples for the Terraform // provider terraform?: { default?: ReadmeExampleMethod, headline?: ReadmeExampleMethod, // Example of how to handle errors in the SDK. // // NOTE: Even though this is an “error” example, it // should be well-formed! (E.g. it shouldn’t have // missing or invalid parameters.) // It demonstrates how to handle network errors and // the like, not how to handle malformed requests, // since the SDK ensures that requests are // well-formed. errors?: ReadmeExampleMethod & { // The response properties to show in this example // code. E.g.: // // example_properties: // error: ‘Rate limit exceeded.’ // request_id: ‘req_123’ example_properties?: Record<string, unknown>, }, // For example code that shows how to retry requests. retries?: ReadmeExampleMethod, // For example code that demonstrates nested // parameters. nested_params?: ReadmeExampleMethod, // For example code that shows how to use a custom // HTTP agent. http_agent?: ReadmeExampleMethod, // For example code that shows how to make a raw API // request. raw_response?: ReadmeExampleMethod, // For example code that shows how to handle // timeouts. timeouts?: ReadmeExampleMethod, // For example code that shows how to set default // headers. default_headers?: ReadmeExampleMethod, // For example code that shows how to use pagination. pagination?: ReadmeExampleMethod, // For example code that shows how to use streaming. streaming?: ReadmeExampleMethod, file_uploads?: { type: “request”, // Endpoint to use as the example method, in the // format post /foo/bar/&#123;id&#125; endpoint: string, // The request params to include in the example. // // e.g. // // params: // query_param: ‘foo’ // body_param: true // path_param: id params: Record<string, unknown>, // The property on the response to log, e.g. id on // a get /accounts endpoints adds a // console.log(account.id) or equivalent in the // example response_property?: string, // The name of the variable to assign the result of // this request to for this example. // // For example, given the method post <br/> // /v1/customers, set assign_to: customer to // produce example code like this: // // ~~~ts // customer = client.customers.create(); // ~~~ assign_to?: string, // The name of the request parameter for the file. // E.g., file file_param: string, // The path and filename of the file being uploaded. // E.g., my/file.txt file_path?: string, }, }, // Override specific examples for the CLI cli?: { default?: ReadmeExampleMethod, headline?: ReadmeExampleMethod, // Example of how to handle errors in the SDK. // // NOTE: Even though this is an “error” example, it // should be well-formed! (E.g. it shouldn’t have // missing or invalid parameters.) // It demonstrates how to handle network errors and // the like, not how to handle malformed requests, // since the SDK ensures that requests are // well-formed. errors?: ReadmeExampleMethod & { // The response properties to show in this example // code. E.g.: // // example_properties: // error: ‘Rate limit exceeded.’ // request_id: ‘req_123’ example_properties?: Record<string, unknown>, }, // For example code that shows how to retry requests. retries?: ReadmeExampleMethod, // For example code that demonstrates nested // parameters. nested_params?: ReadmeExampleMethod, // For example code that shows how to use a custom // HTTP agent. http_agent?: ReadmeExampleMethod, // For example code that shows how to make a raw API // request. raw_response?: ReadmeExampleMethod, // For example code that shows how to handle // timeouts. timeouts?: ReadmeExampleMethod, // For example code that shows how to set default // headers. default_headers?: ReadmeExampleMethod, // For example code that shows how to use pagination. pagination?: ReadmeExampleMethod, // For example code that shows how to use streaming. streaming?: ReadmeExampleMethod, file_uploads?: { type: “request”, // Endpoint to use as the example method, in the // format post /foo/bar/&#123;id&#125; endpoint: string, // The request params to include in the example. // // e.g. // // params: // query_param: ‘foo’ // body_param: true // path_param: id params: Record<string, unknown>, // The property on the response to log, e.g. id on // a get /accounts endpoints adds a // console.log(account.id) or equivalent in the // example response_property?: string, // The name of the variable to assign the result of // this request to for this example. // // For example, given the method post <br/> // /v1/customers, set assign_to: customer to // produce example code like this: // // ~~~ts // customer = client.customers.create(); // ~~~ assign_to?: string, // The name of the request parameter for the file. // E.g., file file_param: string, // The path and filename of the file being uploaded. // E.g., my/file.txt file_path?: string, }, }, // Override specific examples for the SQL SDK sql?: { default?: ReadmeExampleMethod, headline?: ReadmeExampleMethod, // Example of how to handle errors in the SDK. // // NOTE: Even though this is an “error” example, it // should be well-formed! (E.g. it shouldn’t have // missing or invalid parameters.) // It demonstrates how to handle network errors and // the like, not how to handle malformed requests, // since the SDK ensures that requests are // well-formed. errors?: ReadmeExampleMethod & { // The response properties to show in this example // code. E.g.: // // example_properties: // error: ‘Rate limit exceeded.’ // request_id: ‘req_123’ example_properties?: Record<string, unknown>, }, // For example code that shows how to retry requests. retries?: ReadmeExampleMethod, // For example code that demonstrates nested // parameters. nested_params?: ReadmeExampleMethod, // For example code that shows how to use a custom // HTTP agent. http_agent?: ReadmeExampleMethod, // For example code that shows how to make a raw API // request. raw_response?: ReadmeExampleMethod, // For example code that shows how to handle // timeouts. timeouts?: ReadmeExampleMethod, // For example code that shows how to set default // headers. default_headers?: ReadmeExampleMethod, // For example code that shows how to use pagination. pagination?: ReadmeExampleMethod, // For example code that shows how to use streaming. streaming?: ReadmeExampleMethod, file_uploads?: { type: “request”, // Endpoint to use as the example method, in the // format post /foo/bar/&#123;id&#125; endpoint: string, // The request params to include in the example. // // e.g. // // params: // query_param: ‘foo’ // body_param: true // path_param: id params: Record<string, unknown>, // The property on the response to log, e.g. id on // a get /accounts endpoints adds a // console.log(account.id) or equivalent in the // example response_property?: string, // The name of the variable to assign the result of // this request to for this example. // // For example, given the method post <br/> // /v1/customers, set assign_to: customer to // produce example code like this: // // ~~~ts // customer = client.customers.create(); // ~~~ assign_to?: string, // The name of the request parameter for the file. // E.g., file file_param: string, // The path and filename of the file being uploaded. // E.g., my/file.txt file_path?: string, }, }, // Examples specific to the Python SDK python?: { default?: ReadmeExampleMethod, headline?: ReadmeExampleMethod, // Example of how to handle errors in the SDK. // // NOTE: Even though this is an “error” example, it // should be well-formed! (E.g. it shouldn’t have // missing or invalid parameters.) // It demonstrates how to handle network errors and // the like, not how to handle malformed requests, // since the SDK ensures that requests are // well-formed. errors?: ReadmeExampleMethod & { // The response properties to show in this example // code. E.g.: // // example_properties: // error: ‘Rate limit exceeded.’ // request_id: ‘req_123’ example_properties?: Record<string, unknown>, }, // For example code that shows how to retry requests. retries?: ReadmeExampleMethod, // For example code that demonstrates nested // parameters. nested_params?: ReadmeExampleMethod, // For example code that shows how to use a custom // HTTP agent. http_agent?: ReadmeExampleMethod, // For example code that shows how to make a raw API // request. raw_response?: ReadmeExampleMethod, // For example code that shows how to handle // timeouts. timeouts?: ReadmeExampleMethod, // For example code that shows how to set default // headers. default_headers?: ReadmeExampleMethod, // For example code that shows how to use pagination. pagination?: ReadmeExampleMethod, // For example code that shows how to use streaming. streaming?: ReadmeExampleMethod, file_uploads?: { type: “request”, // Endpoint to use as the example method, in the // format post /foo/bar/&#123;id&#125; endpoint: string, // The request params to include in the example. // // e.g. // // params: // query_param: ‘foo’ // body_param: true // path_param: id params: Record<string, unknown>, // The property on the response to log, e.g. id on // a get /accounts endpoints adds a // console.log(account.id) or equivalent in the // example response_property?: string, // The name of the variable to assign the result of // this request to for this example. // // For example, given the method post <br/> // /v1/customers, set assign_to: customer to // produce example code like this: // // ~~~ts // customer = client.customers.create(); // ~~~ assign_to?: string, // The name of the request parameter for the file. // E.g., file file_param: string, // The path and filename of the file being uploaded. // E.g., my/file.txt file_path?: string, }, raw_streaming_response?: ReadmeExampleMethod, }, } Configuration for the request examples used in the README.md for the various SDKs. Each example by default inherits off the default endpoint, and the default endpoint must have a response body. We suggest you use the most standard endpoint for the default example, and the most important example for the headline example
example_types?	{ object?: ReadmeExampleModelObject, nullable?: ReadmeExampleModelObject, enum?: ReadmeExampleModelEnum, union?: ReadmeExampleModelObject, intersection?: ReadmeExampleModelObject, } Configuration for the models/types to use for demonstration of how to instantiate and access different types in the SDK.
include_stainless_attribution?	boolean Include a powered by Stainless attribution in the readme. A paid plan is required to set this to false; see our pricing page for details.

ReadmeExampleMethod

Key	Description
type	”request”
endpoint	string Endpoint to use as the example method, in the format post /foo/bar/{id}
params	Record<string, unknown> The request params to include in the example. e.g. params: query_param: ‘foo’ body_param: true path_param: id
response_property?	string The property on the response to log, e.g. id on a get /accounts endpoints adds a console.log(account.id) or equivalent in the example
assign_to?	string The name of the variable to assign the result of this request to for this example. For example, given the method post /v1/customers, set assign_to: customer to produce example code like this: customer = client.customers.create();

ReadmeExampleModelObject

Key	Description
type	”model”
model	string The dotted path to the model defined in the config. For example, a ‘transaction’ model defined in the ‘cards.transactions’ resource would be ‘cards.transactions.transaction’
property	string The property on the model schema to use as an example

ReadmeExampleModelEnum

Key	Description
type	”model”
model	string The dotted path to the model defined in the config. For example, a ‘transaction’ model defined in the ‘cards.transactions’ resource would be ‘cards.transactions.transaction’
option	string The enum member to reference in examples

pagination

Defines pagination schemes for pagination helpers and auto-pagination in the SDKs.

See our pagination guide for more details and examples.

PaginationScheme

Key	Description
name	string
description?	string
type	”cursor” | “cursor_id” | “cursor_url” | “fake_page” | “offset” | “page_number”
request	Record<string, unknown>
response	Record<string, unknown>
param_location?	“query” | “body”
continue_on_empty_items?	boolean If set to true, the auto pagination helpers will continue to fetch pages even if there are no items returned, and will only stop when it is impossible to fetch another page

PaginationProperty - x-stainless-pagination-property

Key	Description
is_top_level_array?	boolean Are the pagination items the direct, root-level response from the endpoint?
from_header?	string Which header value the pagination config property should be pulled from
purpose?	“items” | “has_next_page” | “max_per_page” | “next_cursor_param” | “next_cursor_field” | “previous_cursor_param” | “previous_cursor_field” | “cursor_item_id” | “next_cursor_id_param” | “previous_cursor_id_param” | “cursor_url_field” | “page_number_param” | “current_page_number_field” | “total_page_count_field” | “offset_total_count_field” | “offset_count_start_field” | “offset_count_param” The purpose of the pagination property. More details and examples can be found in our Pagination docs Generic: items response field containing the items in the page Type: offset offset_total_count_field response field indicating the total number of results available to be fetched offset_count_start_field response field indicating the offset count used to fetch the next page offset_count_param request param used to fetch the next offset page Type: cursor next_cursor_param request param used to fetch the next page previous_cursor_param request param used to fetch the previous page next_cursor_field response field indicating the cursor value used to fetch the next page Type: cursor_id cursor_item_id response field indicating the cursor ID used to fetch the next page next_cursor_id_param request param used to fetch the next page previous_cursor_id_param request param used to fetch the previous page Type: cursor_url cursor_url_field response field indicating the URL used to fetch the next page Type: page_number page_number_param request param used to fetch the next page current_page_number_field response field indicating the current page number total_page_count_field response field indicating the total number of pages available
required?	boolean

Settings - settings

Key	Description
license?	”Apache-2.0” | “MIT” | { // The name given to this license, should be a valid // SPDX identifier name: string, // The license contents. contents: string, // The file extension that the LICENSE file will be // generated to extension?: string, } License to use in all SDKs (defaults to Apache-2.0)
per_endpoint_security?	boolean When true, the security field on an operation will be respected and the SDK will only send matching security schemes. For example: security: [{ BearerAuth: [] }, { APIKeyAuth }] paths: /accounts: post: security: [{ BearerAuth: [] }] By default, if the SDK is given the client option for the APIKeyAuth scheme, then it will happily send it. When per_endpoint_security is set to true, the SDK will only try and send the BearerAuth header.
file_header?	string Custom header to add at the top of all generated SDK files. The header will be added as a comment at the very top of each generated file, before the “File generated from our OpenAPI spec by Stainless” line. Each language will use its appropriate comment syntax automatically. Example usage for copyright headers: settings: file_header: | Copyright (c) 2025 ACME Corporation. All rights reserved. This source code is licensed under the terms described in the LICENSE file in the root directory of this source tree. The above will generate (in TypeScript): // Copyright (c) 2025 ACME Corporation. // All rights reserved. // // This source code is licensed under the terms described in the LICENSE file in // the root directory of this source tree. // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
mock_server?	“steady” The mock server to run the auto-generated tests against. Currently, we only support steady.
python?	{ // The license classifier to use in the Python // package metadata. https://pypi.org/classifiers/ license_classifier?: string, }
disable_mock_tests?	boolean If set to true, all generated integration tests that hit the mock HTTP server are marked as skipped.
unwrap_response_fields?	Array<string> Response envelopes, like a top-level “data” field, can be described here with [data]
positional_params?	false If specified as false, then we disable positional params for the entire SDK.
require_websocket_dependencies?	boolean When set to true, WebSocket dependencies are listed as required dependencies rather than optional. Use this when the API primarily communicates over WebSockets and most consumers will need them.
unwrap_multiproperty_response_fields?	boolean Normally, response envelopes are not unwrapped if they have more than one top-level property. This unwraps them anyway.
suggest_all_potential_models?	boolean Suggest every schema that could be a model as Model/Recommended, not just those that are repeated

ClientSettings - client_settings

Settings for customizing the Client class in the SDKs.

Key	Description
opts?	Record<string, ClientOpt> Extra arguments that the client accepts, such as an API key. Learn more: https://www.stainless.com/docs/configure/client#client-opts
default_client_example_name?	string The default name to use for the generated example client instantiated variable. If not set, defaults to ‘client’. This is used in the generated examples, e.g. const client = new Acme();.
default_client_name?	string The default name to use for the generated client class(es). If not set, defaults to the organization name.
default_env_prefix?	string The default prefix to use for environment variables, e.g. ACME -> ACME_BASE_URL. If not set, defaults to the organization name. Note this is only used for cases where Stainless generates an environment variable name, if you have an explicit environment variable set, e.g. in client_settings.opts.read_env, this env prefix will not apply.
idempotency?	{ // Header to send the idempotency token in header: string, } Configure idempotency behaviour
omit_stainless_headers?	boolean Do not send X-Stainless-* headers with each request. This can be useful if your API has a headers allowlist.
default_headers?	Record<string, string> Headers sent with every API request
default_timeout?	number | string Configure the default timeout for client calls, in milliseconds or ISO 8601 (default is 60 seconds)
default_retries?	{ // Maximum number of times to retry for all // endpoints. Use 0 to disable retries. max_retries: integer, // Seconds to wait before the first retry. initial_delay_seconds: number, // We increase the retry time with exponential // backoff, each retry taking twice as long as the // last, until this value of max seconds to retry. max_delay_seconds: number, } Default retry settings for all endpoints.
response_headers?	Record<string, string>
python?	{ // Default resource limits for the HTTP client. See // s://www.python-httpx.org/advanced/resource-limits // for defaults and more information. default_http_limits: { // Maximum number of allowable connections max_connections?: integer, // Number of allowable keep-alive connections max_keepalive_connections?: integer, // Time limit on idle keep-alive connections in // seconds keepalive_expiry?: number, }, } Python-specific client settings

ClientOpt - client_settings.opts.*

Key	Description
type	”boolean” | “number” | “string” | “integer”
description?	string Description used for this option in the generated SDKs
example?	unknown Example value used in tests or example snippets
default?	unknown Default value to use if no value provided by the user
nullable?	boolean Whether this client option is required
read_env?	string Environment variable that this option should read from
auth?	{ security_scheme: string, role?: “value” | “username” | “password” | “client_id” | “client_secret”, } Indicates that this client option is used to provide credentials for the given security scheme. Learn more: https://www.stainless.com/docs/configure/client/#authentication
server_variable?	string Links this client option to a variable in the url configured by environments. environments: production: https://{region}.acme.com Then server_variable: “region” will mean the value of the {region} will be replaced by the value of this client option.
send_in_header?	string Send the value given to this option in a header on every request
send_as_query_param?	string Use this client opt to fill out the query parameters in requests.
send_as_body_param?	string Use this client opt to fill out the body parameters in requests.
send_as_path_param?	string Use this client opt to fill out the path parameters in requests. Note that the path parameter is required to make the request, and should either be provided either on the client or on the request if the requests requires it.
required_in_tests?	boolean Whether to provide this argument in unit tests. Set to true if this argument is required for internal request tests to run successfully

QuerySettings - query_settings

Key	Description
nested_format?	“dots” | “brackets” Configures how query parameters with nested objects render in the query string. Accepted values are brackets (the default) and dots. Example object: { a: { b: “c” } } brackets syntax -> a[b]=c dot syntax -> a.b=c
array_format?	“comma” | “repeat” | “indices” | “brackets” Configures how query parameters with array values render in the query string. Accepted values are brackets, comma (the default), and repeat. Example object: { in: [“foo”, “bar”] } brackets syntax -> in[]=foo&in[]=bar comma syntax -> in=foo,bar repeat syntax -> in=foo&in=bar

SecurityConfig - security

Overrides for the top-level security keys in the OpenAPI spec. See our authentication documentation for more details.

Key	Description
[key: string]	[Array<string>]

SecurityScheme - security_schemes

Key	Description
type	”http”
description?	string
scheme	”bearer”
bearerFormat?	string
x-stainless-auth?	{ scheme_keyword?: string, }

Key	Description
type	”http”
description?	string
scheme	”basic”
x-stainless-auth?	{ disable_base64?: boolean, scheme_keyword?: string, }

Key	Description
type	”http”
description?	string
scheme	”digest”
x-stainless-auth?	{ scheme_keyword?: string, }

Key	Description
type	”apiKey”
description?	string
in?	“header” | “query”
name	string

Key	Description
type	”oauth2”
description?	string
flows	{ implicit?: { authorizationUrl: string, refreshUrl?: string, scopes: Record<string, string>, }, password?: { tokenUrl: string, refreshUrl?: string, scopes: Record<string, string>, }, clientCredentials?: { tokenUrl: string, refreshUrl?: string, scopes: Record<string, string>, }, authorizationCode?: { authorizationUrl: string, tokenUrl: string, refreshUrl?: string, scopes: Record<string, string>, }, }

StreamingConfig - streaming

Key

Description

on_event

Array<{ kind?: “event”, handle: “break” | “continue” | “done” | “yield” | “error”, // The SSE event type to match against. null // indicates an event with a missing event_type event_type: null | string | Array<string>, // Specify a property that if present on a chunk, // indicates that an error occurred error_property?: string, } | { kind: “fallthrough”, handle: “break” | “continue” | “done” | “yield” | “error”, // Specify a property that if present on a chunk, // indicates that an error occurred error_property?: string, } | { kind?: “data”, handle: “break” | “continue” | “done” | “yield” | “error”, data_starts_with: string, }> An array of streaming event handlers. This can be used to define how specific events / data messages should be handled. Note: the order of the events defined here will be the same order that the SDK checks each event in. See our streaming configuration guide for more details.

OpenAPIConfig - openapi

Describes changes to the input OpenAPI spec and whether or not to add code samples to the output OpenAPI spec. See our transforms guide for more details.

Key	Description
transforms?	Array<{ command: “update”, reason: string, // Replace values at existing paths. Fails if path // doesn’t exist. // // Supports {{value}} templating for string // manipulation. Supports matches_schema for finding // duplicate schemas. // // Examples: // ~~~yaml // # Fix incorrect type with filter // - command: update // reason: “Account IDs are strings” // args: // target: ‘$.paths..parameters[?(@.name == // “account_id”)].schema.type’ // value: “string” // // # String templating: append text // - command: update // reason: “Add deprecation notice” // args: // target: // “$.components.schemas.LegacyUser.description” // value: “{{value}}\n\nDEPRECATED: Use NewUser // instead” // template: true // // # Schema matching: replace duplicates // - command: update // reason: “Replace duplicate error schemas with // $ref” // args: // target: // - matches_schema: // $.components.schemas.ErrorTemplate // ignore: $.components.schemas.ErrorTemplate // value: // $ref: ”#/components/schemas/Error” // ~~~ args: { // A JSONPath Plus // (https://www.npmjs.com/package/jsonpath-plus) // query pointing to the value(s) to replace. Can be // a string, array of strings, or array mixing // strings with matches_schema queries. target: string | Array<string | { // JSONPath to template schema. Finds all schemas // that deep-equal this one. matches_schema: string, // Path(s) to exclude from matching (e.g., the // template itself). ignore?: string | Array<string>, }>, // The new value to set at the target location(s). value: unknown, // If true, enables {{value}} substitution in string // values. Use for appending/prepending to strings. // Example: “{{value}}\nAdditional notes” or “[BETA] // {{value}}”. Requires value to contain {{value}} // and target to be a string. template?: boolean, }, } | { command: “append”, reason: string, // Add items to arrays or add new properties to // objects. Attempting to add a property that // already exists will fail. This alerts you when // the spec is fixed. // // Use for temporary fixes. For intentional // overrides, use merge. // // Examples: // ~~~yaml // # Add to array // - command: append // reason: “Add id to required fields” // args: // target: “$.components.schemas.User.required” // value: “id” // // # Add property (fails if exists) // - command: append // reason: “API spec missing id field, adding // temporarily” // args: // target: “$.components.schemas.User.properties” // value: // id: // type: “string” // format: “uuid” // ~~~ args: { // A JSONPath Plus // (https://www.npmjs.com/package/jsonpath-plus) // query pointing to array(s) or object(s) to append // to. Can be a string, array of strings, or array // mixing strings with matches_schema queries. target: string | Array<string | { // JSONPath to template schema. Finds all schemas // that deep-equal this one. matches_schema: string, // Path(s) to exclude from matching (e.g., the // template itself). ignore?: string | Array<string>, }>, // For arrays: item(s) to push. For objects: // properties to add (fails if property already // exists). value: unknown, }, } | { command: “merge”, reason: string, // Merge an object into targets. Overwrites existing // properties. Uses deep merge, so nested objects // are merged recursively. // // Use for permanent overrides like // x-stainless-naming or x-stainless-skip. For // temporary fixes, use append. // // Examples: // ~~~yaml // # Add x-stainless extension // - command: merge // reason: “Terraform doesn’t need pagination // params” // args: // target: ’$..parameters[?(@.name == “limit”)]’ // value: // schema: // x-stainless-skip: [“terraform”] // // # Set language-specific naming // - command: merge // reason: “Avoid Python parameter conflict” // args: // target: // “$.components.schemas.Request.properties.timeout” // value: // x-stainless-naming: // python: // method_argument: “api_timeout” // ~~~ args: { // A JSONPath Plus // (https://www.npmjs.com/package/jsonpath-plus) // query pointing to object(s) to merge into. Can be // a string, array of strings, or array mixing // strings with matches_schema queries. target: string | Array<string | { // JSONPath to template schema. Finds all schemas // that deep-equal this one. matches_schema: string, // Path(s) to exclude from matching (e.g., the // template itself). ignore?: string | Array<string>, }>, // The object to deep merge into the target // location(s). Properties from this object will be // merged into existing properties. value: Record<string, unknown>, }, } | { command: “remove”, reason: string, // Delete nodes or specific keys from objects. // // Examples: // ~~~yaml // # Remove nodes // - command: remove // reason: “Remove problematic examples” // args: // target: // - “$.paths...examples” // - “$.components.schemas.*.example” // // # Remove specific keys // - command: remove // reason: “Remove incorrect default” // args: // target: // “$.components.schemas.User.properties.role” // keys: [“default”] // // # Remove with filter // - command: remove // reason: “Remove deprecated parameters” // args: // target: ‘$.paths..parameters[?(@.deprecated == // true)]’ // ~~~ args: { // A JSONPath Plus // (https://www.npmjs.com/package/jsonpath-plus) // query pointing to the node(s) to remove. Can be a // string, array of strings, or array mixing strings // with matches_schema queries. target: string | Array<string | { // JSONPath to template schema. Finds all schemas // that deep-equal this one. matches_schema: string, // Path(s) to exclude from matching (e.g., the // template itself). ignore?: string | Array<string>, }>, // If target points to an object, remove these // specific keys from the object. If not provided, // removes the entire target node. keys?: Array<string>, }, } | { command: “copy”, reason: string, // Copy a value to one or more destinations. Creates // destination if parent exists. The source value is // deep cloned to each destination. // // Examples: // ~~~yaml // # Copy schema // - command: copy // reason: “Duplicate User schema” // args: // from: “$.components.schemas.User” // to: “$.components.schemas.Admin” // // # Copy to multiple destinations // - command: copy // reason: “Reuse error schema” // args: // from: “$.components.schemas.NotFoundError” // to: // - // et.responses.404.content.application/json.schema” // - // et.responses.404.content.application/json.schema” // ~~~ args: { // A JSONPath Plus // (https://www.npmjs.com/package/jsonpath-plus) // query pointing to the source value to copy. Must // match exactly one node. from: string, // A JSONPath Plus // (https://www.npmjs.com/package/jsonpath-plus) // query pointing to the destination(s). Can be a // string, array of strings, or array mixing strings // with matches_schema queries. If destination // doesn’t exist, creates it (parent must exist). to: string | Array<string | { // JSONPath to template schema. Finds all schemas // that deep-equal this one. matches_schema: string, // Path(s) to exclude from matching (e.g., the // template itself). ignore?: string | Array<string>, }>, }, } | { command: “move”, reason: string, // Move or rename a value from one location to // another. // // If from and to share the same parent the node // will be renamed. Otherwise it will be relocated. // Only accept a single source and destination // target. // // Examples: // ~~~yaml // # Rename a schema key // - command: move // reason: “Normalize schema name to PascalCase” // args: // from: “$.components.schemas.user_response” // to: “$.components.schemas.UserResponse” // // # Move property between schemas // - command: move // reason: “Relocate userId from Request to User // schema” // args: // from: // “$.components.schemas.Request.properties.userId” // to: “$.components.schemas.User.properties.id” // ~~~ args: { // A JSONPath Plus // (https://www.npmjs.com/package/jsonpath-plus) // query pointing to the source value to move. Must // match exactly one node. from: string, // A JSONPath Plus // (https://www.npmjs.com/package/jsonpath-plus) // query pointing to the destination. The parent of // the target should exist. to: string, }, }> List of transforms to apply to the OpenAPI spec before SDK generation. See our transforms reference for available commands. Note: openapi.transforms was named openapi.transformations in early versions of Stainless. The names are interchangeable, but we recommend you use the newer openapi.transforms.
code_samples?	{ // adds x-readme.samples-languages readme?: boolean, // alias for x-codeSamples redocly?: boolean, // alias for x-codeSamples mintlify?: boolean, // alias for x-codeSamples bump.sh?: boolean, // alias for x-codeSamples gitbook?: boolean, // alias for x-codeSamples x-codeSamples?: boolean, // adds x-stainless-snippets stainless?: boolean, } | “readme” | “redocly” | “mintlify” | “bump.sh” | “gitbook” | “x-codeSamples” | “stainless” Defines automatic snippet generation directly into your OpenAPI spec. We support the following providers: Stainless (adds x-stainless-snippets), ReadMe, x-codeSamples, Bump.sh, GitBook, Redocly, and Mintlify (the latter four are aliases for x-codeSamples). See our third-party docs integration docs for more details.
code_sample_languages?	Record<string, boolean> Controls which languages to include in generated code samples. By default, all languages configured in targets are enabled, and curl, powershell are disabled.

custom_casings

InitialismConfig

Key

Description

initialism

boolean If set to true, the term is used as an initialism: treated as an abbreviation of initial letters (for example, “CPU” and “API”). If set to false, the term is removed from the set of initialisms. By default we use [3ds, ach, acl, ai, api, ats, cpu, crm, db, dns, e2e, eeoc, gb, gpu, hd, hris, html, http, https, id, ip, iso, jsonl, kb, kyb, kyc, lfs, mb, mp3, mp4, nft, saml, sdk, sku, sms, ss, ssh, sso, url] as initialisms. Example: custom_casings: mcp: { initialism: true }

CasingConfig

Key	Description
snake	string Term rendered with lowercase characters separated by underscores. Example: custom_casings: payment_method: snake: “payment_method”
pascal	string Term rendered with the first character of each word capitalized and joined together. Example: ~~~yaml custom_casings: payment_method: pascal: “PaymentMethod” ~~~
capital	string Term rendered with the first character of each word capitalized and separated by a space. Example: ~~~yaml custom_casings: payment_method: capital: “Payment Method” ~~~
camel	string Term rendered with the first word in lowercase, followed by the first character of each subsequent word capitalized and joined together. Example: custom_casings: payment_method: camel: “paymentMethod”

CodeflowConfig - codeflow

Configures various codeflow (automated releases to package managers) options.

Key	Description
release_environment?	string GitHub environment to run the release workflow in.
publish_packages?	boolean Whether publishing to package managers should be included in GitHub automations.
reviewers?	Array<string> List of default reviewers to assign to a customer release PR
code_owners?	Record<string, Array<string>> Github CODEOWNERS file content to add to SDK repositories Example: code_owners: ’*’: [‘@acme/sdk-team-1’] ‘src/**’: [‘@acme/sdk-team-2’]
detect_breaking_changes?	boolean Enable to automatically detect some breaking changes. With detect_breaking_changes enabled, we’ll check out the public API test files in their pre-release state and attempt to compile/lint them against your new SDK version. If your previous test code fails to compile with your new SDK, we surface the errors as an indicator that your new release contains breaking changes.

DiagnosticsConfig - diagnostics

Configures diagnostics that appear in builds and the Studio.

Key	Description
ignored	Record<string, true | Array<string | { location: string, reason: string, } | { target: SupportedLanguage, reason: string, }>> Diagnostic types to ignore.