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 to generate and how they are published (npm, PyPI, Maven, etc.)
• The core hierarchy of the generated client
• Customization beyond your OpenAPI spec, like naming, organization, and behavior changes

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

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/guides/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/guides/configure#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?	“2025-10-10” | “2025-10-08”
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#, } 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]: { // Set custom: true to use customer_code content // for the resource instead of generated code custom?: boolean, // 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. models?: Record<string, string | Model>, // 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. methods?: Record<string, string | Method>, // Add a docstring for the resource. description?: string, // Terraform configuration options for this resource. 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, }, // Whether to generate Terraform resource resource?: boolean, // Whether to generate Terraform data sources data_source?: boolean, // 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, }, // 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(). subresources?: Record<string, Resource>, // Set the deprecation message for this resource deprecated?: string | Record<string, string>, // whether to generate MCP Server tools for this // resource mcp?: boolean | { // A list of tags that end-users can use to filter // which resources and endpoints to include tags?: Array<string>, }, // 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. skip?: boolean | Array<SupportedLanguage>, // Opposite of skip; if set, SDK generation is // only performed for this resource. only?: Array<SupportedLanguage>, }, // 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
security?	Array<SecurityConfig> Overrides the top-level security key in the OpenAPI spec.
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.
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
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 <10MB.
skip?	boolean Skip generation for this target
edition?	“typescript.2025-10-10” | “typescript.2025-10-08”
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 | { // 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, }, }
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 // // If set to true, it will generate an MCP tool for // every endpoint. If set to an object, you can // customize // the package name and whether resources are // enabled by default. 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, }, // 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, }, // The package manager used to install dependencies // and manage project builds. package_manager?: “pnpm” | “yarn”, }
custom?	{ }

MCP - targets.typescript.options.mcp_server

Key	Description
package_name?	string The name of the mcp package. Defaults to <typescript-package>-mcp
enable_all_resources?	boolean Adds all endpoints to the MCP server by default. Defaults to true. Set this value to false to opt-in each resource or endpoint to be included. e.g. resources: my_resource: mcp: true methods: … # all methods enabled another_resource: methods: create: endpoint: /v1/create mcp: true # just this endpoint is enabled
recommend_dynamic_tools?	boolean “Dynamic tools” are a feature of the MCP server that provides tools for LLMs to dynamically discover and invoke endpoints, rather than generating a tool for each endpoint. This is helpful if an API has a large number of endpoints, such that the default list of tools would be too long to display or not fit into LLM context windows. It can also be helpful if the user is unlikely to know in advance which tools they want to enable explicitly. If true, the MCP server will recommend these dynamic tools in the README, and enable them by default if no arguments are provided. If false, importing all tools will be recommended in the README. If unset, then we’ll recommend dynamic tools if the number of endpoints is greater than 20, but never enable it by default. In any case, dynamic tools can be enabled or disabled explicitly by the end user.
enable_code_tool?	boolean Generate a tool for the MCP server to run TypeScript code against your Stainless SDK. See https://www.stainless.com/docs/guides/generate-mcp-server-from-openapi#code-execution-tool for more information.
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.
enable_jq_filter?	boolean Whether to enable the JQ filter option on appropriate tools. Defaults to true.
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 | { // The Docker image name, e.g. “myorg/my-api-mcp” image_name: string, // The Docker registry to publish to registry?: string, }, }

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 <10MB.
skip?	boolean Skip generation for this target
edition?	“node.2025-10-08”
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 | { // 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, }, }
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 // // If set to true, it will generate an MCP tool for // every endpoint. If set to an object, you can // customize // the package name and whether resources are // enabled by default. 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, }, }
custom?	{ }

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 <10MB.
skip?	boolean Skip generation for this target
edition?	“python.2025-10-08”
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 | { // The name of the package in pypi, e.g. pip <br/> // install <package_name> package_name?: string, }, }
options?	{ }

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 <10MB.
skip?	boolean Skip generation for this target
edition?	“go.2025-10-08”
package_name	string The name of the root package, containing the top-level client, options, and methods.
options?	{ // 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, // 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, // Experimental: Setting to false will automatically // apply URI encoding to path parameters. Only Go // and Python don’t do this by default experimental_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, // Explicitly set the Go version to use go_language_version?: string, }

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 <10MB.
skip?	boolean Skip generation for this target
edition?	“java.2025-10-08”
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 [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, } See our publishing guide for more information on how to publish your SDK.
options?	{ }

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 <10MB.
skip?	boolean Skip generation for this target
edition?	“kotlin.2025-10-08”
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 [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, } See our publishing guide for more information on how to publish your SDK.
options?	{ }

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 <10MB.
skip?	boolean Skip generation for this target
edition?	“ruby.2025-10-08”
gem_name	string The name of the gem.
publish	{ rubygems: 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 <10MB.
skip?	boolean Skip generation for this target
edition?	“cli.2025-10-08”
binary_name?	string The name of the binary, defaults to the repository name.
options?	{ // 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” | “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_error_format?	“auto” | “explore” | “json” | “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?	{ 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, }, }

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 <10MB.
skip?	boolean Skip generation for this target
edition?	“php.2025-10-08”
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, }
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 <10MB.
skip?	boolean Skip generation for this target
edition?	“csharp.2025-10-08”
package_name	string The name of the root package, containing the top-level client, options, and methods.
publish	{ nuget: boolean, }
options?	{ }

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 <10MB.
skip?	boolean Skip generation for this target
edition?	“terraform.2025-10-08”
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, }
options?	{ // 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, // whether to enable a timeout property for resources timeouts?: boolean | { // Attribute name for timeout parameter name?: string, }, }

SupportedLanguage

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

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.
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, }, // Whether to generate Terraform resource resource?: boolean, // Whether to generate Terraform data sources data_source?: boolean, // 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.
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
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
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/guides/configure#pagination
skip_test_reason?	string | Record<string, string> Skip the generated unit test in all languages / particular languages with a given a reason
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.
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”, }
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?	{ // 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

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 | 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
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

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

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.
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 Name of the model this alias should point to. Aliases must point to a model within the same resource.
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/guides/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 & { example_properties?: Record<string, unknown>, }, retries?: ReadmeExampleMethod, nested_params?: ReadmeExampleMethod, http_agent?: ReadmeExampleMethod, raw_response?: ReadmeExampleMethod, timeouts?: ReadmeExampleMethod, default_headers?: ReadmeExampleMethod, pagination?: ReadmeExampleMethod, 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, assign_to?: string, file_param: string, file_path?: string, }, } 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.

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

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

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

key: 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” | “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)
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 prism 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.

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/guides/configure#client-opts
idempotency?	{ // Header to send the idempotency token in header: string, } Configure idempotency behaviour
default_headers?	Record<string, string> Headers sent with every API request
default_timeout?	string | number 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.

ClientOpt

key: client_settings.opts.*

Key	Description
type	”null” | “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”, } Configure authentication for this client option.
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
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_config

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
x-stainless-auth?	{ custom: 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>, }, }

OpenAPIConfig - openapi

Describes changes to the input OpenAPI spec and also whether or not to add code samples to the output OpenAPI spec.

Key	Description
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. Supported providers: readme x-codeSamples bump.sh, alias for x-codeSamples gitbook, alias for x-codeSamples redocly, alias for x-codeSamples mintlify, alias for x-codeSamples stainless, adds x-stainless-snippets
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.

CasingConfig

Key	Description
snake	string Term rendered with lowercase characters separated by underscores (for example, “payment_method”).
pascal	string Term rendered with the first character of each word capitalized and joined together (for example, “PaymentMethod”).
capital	string Term rendered with the first character of each word capitalized and separated by a space (for example, “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 (for example, “paymentMethod”).

ErrorsConfig - errors

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’]

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.