Stainless config

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

# '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://app.stainlessapi.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: post /accounts/{account_id}/link
    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://app.stainlessapi.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://app.stainlessapi.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:
  node:
    package_name: acme-typescript
    production_repo: stainless-sdks/acme-typescript-public
    publish:
      npm: true
  python:
    package_name: acme
    project_name: acme-python
    production_repo: stainless-sdks/acme-python-public
    publish:
      pypi: true
  go:
    package_name: acme-go
    production_repo: stainless-sdks/acme-go-public
  ruby:
    gem_name: acme
    production_repo: stainless-sdks/acme-ruby-public
    publish:
      rubygems: false

Config

Key	Description
`organization`	`Organization` How the organization is represented in the SDKs, such as `name` and `github_org`.
`targets?`	`{ node?: Node, python?: Python, java?: Java, kotlin?: Kotlin, go?: Go, ruby?: Ruby, }`
`environments`	`Record<string, string>` Map of the name of the environment which appears in the SDK to the corresponding url to use. `{ "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` Configuration of the examples in the README.md of the generated SDKs.
`settings`	`Settings`
`query_settings`	`QuerySettings` Query string serialization options.
`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` Settings for customizing the Client class in the SDKs.
`pagination?`	`{ description?: string, type: "cursor" \| "cursor_id" \| "cursor_url" \| "fake_page" \| "offset" \| "page_number", request: Record<string, unknown>, response: Record<string, unknown>, } \| 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"]`
`errors?`	`ErrorsConfig` Defines custom error types in the SDKs.
`codeflow?`	`CodeflowConfig` Configures various codeflow (automated releases to package managers) options.
`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` Describes changes to the input OpenAPI spec and also whether or not to add code samples to the output OpenAPI spec.

Organization - `organization`

Key	Description
`name`	`string` Name of your organization or company (all lowercase)
`docs`	`string` Link to your API docs
`contact`	`string` Support email address for bug reports or questions
`security_contact?`	`string` Security email address for reporting vulnerabilities. Will be mentioned in the generated SECURITY.md
`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. Note that Stainless always generates a default security policy covering SDKs security issues. This field is for any additional terms you want to add and will be included in a section ' 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`

Node - `targets.node`

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
`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, }`
`options?`	{ 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
`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 // install ` package_name?: string, }, }
`options?`	{ // Disable warnings for fields that start with // `model_` disable_pydantic_namespace_protection?: boolean, }

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
`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, }

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
`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 `-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, }, } 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
`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 `-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, }, } 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
`gem_name`	`string`
`publish`	`{ rubygems: boolean, }`
`options?`	`{ }`

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.
`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
`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.
`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 all path parameters as positional parameters). 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 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, }`
`skip?`	`boolean \| Array<"node" \| "typescript" \| "python" \| "go" \| "java" \| "kotlin" \| "ruby" \| "terraform">` 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<"node" \| "typescript" \| "python" \| "go" \| "java" \| "kotlin" \| "ruby" \| "terraform">` 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<"node" \| "typescript" \| "python" \| "go" \| "java" \| "kotlin" \| "ruby" \| "terraform">` 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<"node" \| "typescript" \| "python" \| "go" \| "java" \| "kotlin" \| "ruby" \| "terraform">` 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 to will have the same canonical name and share a type definition. 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.
`source?`	`string` Deprecated: use `openapi_uri` instead. Source for the model, either a ref (for example, "Card") or an endpoint response object (for example, "get /blah")
`path?`	`string` Deprecated: use `openapi_uri` instead. To define a model based on a property within the `source`, assign a JMES-style path to rename a property within the model.
`no_params_suffix?`	`boolean` used to disable the automatic addition of the `Params` suffix in the Python SDK
`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<"node" \| "typescript" \| "python" \| "go" \| "java" \| "kotlin" \| "ruby" \| "terraform">` 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<"node" \| "typescript" \| "python" \| "go" \| "java" \| "kotlin" \| "ruby" \| "terraform">` 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<"node" \| "typescript" \| "python" \| "go" \| "java" \| "kotlin" \| "ruby" \| "terraform">` 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<"node" \| "typescript" \| "python" \| "go" \| "java" \| "kotlin" \| "ruby" \| "terraform">` Opposite of `skip`; if set, SDK generation is only performed for this resource.

Readme - `readme`

Key	Description
`example_requests`	{ default: ReadmeExampleMethod, headline: ReadmeExampleMethod, errors?: ReadmeExampleMethod & { // Specify example properties that are available on // the error object, e.g. // // example_properties: // message: 'Invalid parameter(s): type' // debugging_request_id: // '94d5e915-xxxx-4cee-a4f5-2xd6ebd279ac' 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/{id}` 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.
`include_stainless_attribution?`	`boolean` Include a powered by Stainless attribution in the readme

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

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" \| "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 `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
`sort_schema_properties?`	`boolean` Whether or not to sort schema properties before outputting types. Defaults to `true`
`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_tests?`	`boolean` If set to true, all generated unit tests are marked as skipped
`unwrap_response_fields?`	`Array<string>` Response envelopes, like a top-level "data" field, can be described here with [data]

ClientSettings - `client_settings`

Key	Description
`opts?`	`Record<string, ClientOpt>` Extra arguments that the client accepts, such as an API key
`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` 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. This value must be greater than 0. 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. More details on these options can be found here

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", }`
`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`

OpenAPIConfig - `openapi`

Key Description

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` x-codeSamples?: boolean, // adds `x-stainless-snippets` stainless?: boolean, } \| "readme" \| "redocly" \| "mintlify" \| "x-codeSamples" \| "stainless" Defines automatic snippet generation directly into your OpenAPI spec. Supported providers: readme x-codeSamples redocly, alias for `x-codeSamples` mintlify, alias for `x-codeSamples` stainless, adds `x-stainless-snippets`

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` 
  x-codeSamples?: boolean,
  // adds `x-stainless-snippets` 
  stainless?: boolean,
} | "readme" | "redocly" | "mintlify" | "x-codeSamples" | "stainless"

Defines automatic snippet generation directly into your OpenAPI spec.

Supported providers:

readme
x-codeSamples
redocly, alias for x-codeSamples
mintlify, alias for x-codeSamples
stainless, adds x-stainless-snippets

`custom_casings`

InitialismConfig

Key Description

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, kb, kyb, kyc, lfs, mb, mp3, mp4, nft, saml, sdk, sku, sms, ss, ssh, sso, url]` as initialisms.

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

Key Description

Key	Description
`union?`	{ // Points to a union schema where each entry is an // error schema. source: string, // The property that is used as a discriminator, // e.g. `type` discriminator: string, // The enum property that indicates what status // code(s) the schema should be used for. status_property: string, // Customise each individual variant. variants?: Record<string, { // Indicate that this error should be raised when // the given status code is returned. status_code?: integer, // By default the value of the discriminated // property is used as the name for the error. // // This field expects an object where the key is the // value of the discriminator property and the value // is the new name. // // For example, you can change the name for an error // with `type: 'api_method_not_found_error'` like // so: // // ```yaml // variants: // api_method_not_found_error: // name: not_found_error // ``` name?: string, }>, } Configure error types from a discriminated union of error responses
`message_property?`	`string` Response property to use for the error message.

union?

{
  // Points to a union schema where each entry is an 
  // error schema. 
  source: string,
  // The property that is used as a discriminator, 
  // e.g. `type` 
  discriminator: string,
  // The enum property that indicates what status 
  // code(s) the schema should be used for. 
  status_property: string,
  // Customise each individual variant. 
  variants?: Record<string, {
    // Indicate that this error should be raised when 
    // the given status code is returned. 
    status_code?: integer,
    // By default the value of the discriminated 
    // property is used as the name for the error. 
    //  
    // This field expects an object where the key is the 
    // value of the discriminator property and the value 
    // is the new name. 
    //  
    // For example, you can change the name for an error 
    // with `type: 'api_method_not_found_error'` like 
    // so: 
    //  
    // ```yaml 
    // variants: 
    //   api_method_not_found_error: 
    //     name: not_found_error 
    // ``` 
    name?: string,
  }>,
}

Configure error types from a discriminated union of error responses

message_property?

string

Response property to use for the error message.

CodeflowConfig - `codeflow`

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']`

Config​

Organization - organization​

Targets - targets​

Node - targets.node​

Python - targets.python​

Go - targets.go​

Java - targets.java​

Kotlin - targets.kotlin​

Ruby - targets.ruby​

Resource - resources.*​

Method - resources.*.methods.*​

Model - resources.*.models.*​

Readme - readme​

ReadmeExampleMethod​

ReadmeExampleModelObject​

ReadmeExampleModelEnum​

pagination​

PaginationScheme​

PaginationProperty​

Settings - settings​

ClientSettings - client_settings​

ClientOpt​

QuerySettings - query_settings​

OpenAPIConfig - openapi​

custom_casings​

InitialismConfig​

CasingConfig​

ErrorsConfig - errors​

CodeflowConfig - codeflow​

Config

Organization - `organization`

Targets - `targets`

Node - `targets.node`

Python - `targets.python`

Go - `targets.go`

Java - `targets.java`

Kotlin - `targets.kotlin`

Ruby - `targets.ruby`

Resource - `resources.*`

Method - `resources..methods.`

Model - `resources..models.`

Readme - `readme`

ReadmeExampleMethod

ReadmeExampleModelObject

ReadmeExampleModelEnum

`pagination`

PaginationScheme

PaginationProperty

Settings - `settings`

ClientSettings - `client_settings`

ClientOpt

QuerySettings - `query_settings`

OpenAPIConfig - `openapi`

`custom_casings`

InitialismConfig

CasingConfig

ErrorsConfig - `errors`

CodeflowConfig - `codeflow`