Skip to main content

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}

# 'package' defines language-specific names and package settings to ensure that
# the generated SDK matches the name that you desire.
package:
  node:
    # 'name' is the name that will published to in the npm package registry.
    # It should be a name that you own, or isn't yet published to.
    name: "acme-typescript"
    # 'repo' should link to the production repository that the SDK outputs to.
    # It is manually editable, but it's recommended to go through the publish
    # flow on the web app which will guide you through linking the GitHub app
    # to your stainless account.
    repo: "stainless-sdks/acme-typescript"
  python:
    name: "acme-python"
    repo: "stainless-sdks/acme-python"
  go:
    name: "acme-go"
    repo: "stainless-sdks/acme-go"
  ruby:
    name: "acme"
    repo: "stainless-sdks/acme-ruby"

# '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:
  opts:
    username:
      type: string
      auth:
        security_scheme: BasicAuth
        role: username
      read_env: ACME_USERNAME
    password:
      type: string
      auth:
        security_scheme: BasicAuth
        role: password
      read_env: ACME_PASSWORD
    acme_api_key:
      type: string
      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: {}

Config​

KeyDescription
organizationOrganization

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

package?{
node?: Node,
python?: Python,
java?: Java,
kotlin?: Kotlin,
go?: Go,
ruby?: Ruby,
}

Customization for each language's repo name and the name in the package manager.

environmentsRecord<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" }.

resourcesRecord<string, Resource>
readmeReadme

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

settingsSettings
query_settingsQuerySettings

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​

KeyDescription
namestring

Name of your organization or company (all lowercase)

docsstring

Link to your API docs

docs_title?string

Optional title for the API docs link. Defaults to "on $website".

contactstring

Support email address for bug reports or questions

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.

Package - package​

Node - package.node​

KeyDescription
namestring

Name this package should be published as (for example, "your-company" or "@your-company/sdk")

repostring

Repository name for this SDK under your GitHub organization

branch?string

Branch of the live repository that contains the SDK and is released from. Typically this is "main", but you may want to change it to eg "v2-beta" if you have an existing SDK you are replacing. Note that Stainless will also create other branches, like "next", for development (which cannot currently be renamed).

screencast?string

URL of a screencast to showcase on the project README. Must be an .mp4, .webm, or .mov file less <10MB.

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")'

skip?boolean

Skip generation for this package

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

Configure behaviour when the SDK is used in the browser

Python - package.python​

KeyDescription
namestring

Name this package should be published as (for example, "your-company" or "@your-company/sdk")

repostring

Repository name for this SDK under your GitHub organization

branch?string

Branch of the live repository that contains the SDK and is released from. Typically this is "main", but you may want to change it to eg "v2-beta" if you have an existing SDK you are replacing. Note that Stainless will also create other branches, like "next", for development (which cannot currently be renamed).

screencast?string

URL of a screencast to showcase on the project README. Must be an .mp4, .webm, or .mov file less <10MB.

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")'

skip?boolean

Skip generation for this package

Go - package.go​

KeyDescription
namestring

Name this package should be published as (for example, "your-company" or "@your-company/sdk")

repostring

Repository name for this SDK under your GitHub organization

branch?string

Branch of the live repository that contains the SDK and is released from. Typically this is "main", but you may want to change it to eg "v2-beta" if you have an existing SDK you are replacing. Note that Stainless will also create other branches, like "next", for development (which cannot currently be renamed).

screencast?string

URL of a screencast to showcase on the project README. Must be an .mp4, .webm, or .mov file less <10MB.

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")'

skip?boolean

Skip generation for this package

option_package_name?string

Override the name used for the internal option package

Java - package.java​

KeyDescription
namestring

Name this package should be published as (for example, "your-company" or "@your-company/sdk")

repostring

Repository name for this SDK under your GitHub organization

branch?string

Branch of the live repository that contains the SDK and is released from. Typically this is "main", but you may want to change it to eg "v2-beta" if you have an existing SDK you are replacing. Note that Stainless will also create other branches, like "next", for development (which cannot currently be renamed).

screencast?string

URL of a screencast to showcase on the project README. Must be an .mp4, .webm, or .mov file less <10MB.

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")'

skip?boolean

Skip generation for this package

reverse_domainstring

Reversed domain name controlled by the organization and used as a prefix for generated Java package names (for example, "org.example").

See https://maven.apache.org/guides/mini/guide-naming-conventions.html

maven_group_id?string

Maven groupId as a unique identifier. Defaults to reverse_domain + .api.

See https://maven.apache.org/guides/mini/guide-naming-conventions.html

sonatype_host?string

The Sonatype host to publish to. Defaults to "s01.oss.sonatype.org", but you may need to use "oss.sonatype.org" for older packages.

client_artifact_name?string

Name of the jar, without any version indicator. Defaults to "your-company-java".

Kotlin - package.kotlin​

KeyDescription
namestring

Name this package should be published as (for example, "your-company" or "@your-company/sdk")

repostring

Repository name for this SDK under your GitHub organization

branch?string

Branch of the live repository that contains the SDK and is released from. Typically this is "main", but you may want to change it to eg "v2-beta" if you have an existing SDK you are replacing. Note that Stainless will also create other branches, like "next", for development (which cannot currently be renamed).

screencast?string

URL of a screencast to showcase on the project README. Must be an .mp4, .webm, or .mov file less <10MB.

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")'

skip?boolean

Skip generation for this package

maven_group_id?string

Maven groupId as a unique identifier. Defaults to reverse_domain + .api.

See https://maven.apache.org/guides/mini/guide-naming-conventions.html

client_artifact_name?string

Name of the jar, without any version indicator. Defaults to "your-company-java".

reverse_domain?string

Reversed domain name controlled by the organization and used as a prefix for generated Java package names (for example, "org.example").

See https://maven.apache.org/guides/mini/guide-naming-conventions.html

sonatype_host?string

The Sonatype host to publish to. Defaults to "s01.oss.sonatype.org", but you may need to use "oss.sonatype.org" for older packages.

Ruby - package.ruby​

KeyDescription
namestring

Name this package should be published as (for example, "your-company" or "@your-company/sdk")

repostring

Repository name for this SDK under your GitHub organization

branch?string

Branch of the live repository that contains the SDK and is released from. Typically this is "main", but you may want to change it to eg "v2-beta" if you have an existing SDK you are replacing. Note that Stainless will also create other branches, like "next", for development (which cannot currently be renamed).

screencast?string

URL of a screencast to showcase on the project README. Must be an .mp4, .webm, or .mov file less <10MB.

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")'

skip?boolean

Skip generation for this package

Resource - resources.*​

KeyDescription
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.*​

KeyDescription
type?"http"

Describes a method for a standard http endpoint.

endpointstring

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" | "python" | "go" | "java" | "kotlin" | "ruby">

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" | "python" | "go" | "java" | "kotlin" | "ruby">

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

KeyDescription
type"alias"

Describes an 'alias' to a method in the same resource. Used mainly for renaming a method and maintaining backwards compatibility.

tostring

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" | "python" | "go" | "java" | "kotlin" | "ruby">

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" | "python" | "go" | "java" | "kotlin" | "ruby">

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.*​

KeyDescription
type?"model"
sourcestring

Source for the model, either a ref (for example, "Card") or an endpoint response object (for example, "get /blah")

path?string

To define a model based on a property within the source, assign a JMES-style path to rename a property within the model.

skip?boolean | Array<"node" | "python" | "go" | "java" | "kotlin" | "ruby">

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" | "python" | "go" | "java" | "kotlin" | "ruby">

Opposite of skip; if set, SDK generation is only performed for this resource.

KeyDescription
type"alias"
tostring

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" | "python" | "go" | "java" | "kotlin" | "ruby">

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" | "python" | "go" | "java" | "kotlin" | "ruby">

Opposite of skip; if set, SDK generation is only performed for this resource.

Readme - readme​

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

KeyDescription
type"request"
endpointstring

Endpoint to use as the example method, in the format post /foo/bar/{id}

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

KeyDescription
type"model"
modelstring

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'

propertystring

The property on the model schema to use as an example

ReadmeExampleModelEnum​

KeyDescription
type"model"
modelstring

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'

optionstring

The enum member to reference in examples

pagination​

PaginationScheme​

KeyDescription
namestring
description?string
type"cursor" | "cursor_id" | "cursor_url" | "fake_page" | "offset" | "page_number"
requestRecord<string, unknown>
responseRecord<string, unknown>

PaginationProperty​

key: x-stainless-pagination-property

KeyDescription
is_top_level_array?boolean
from_header?string
purpose?"items" | "next_cursor_param" | "next_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"
required?boolean

Settings - settings​

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

KeyDescription
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?{
// Number of times to retry for all endpoints. 0
// indicates to not retry at all
max_retries: integer,
// Seconds for 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,
}

ClientOpt​

key: client_settings.opts.*

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

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

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

custom_casings​

InitialismConfig​

KeyDescription
initialismboolean

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, hd, hris, html, http, https, id, ip, iso, kb, kyb, kyc, lfs, mb, mp3, mp4, nft, sku, sms, ss, ssh, sso, url] as initialisms.

CasingConfig​

KeyDescription
snakestring

Term rendered with lowercase characters separated by underscores (for example, "payment_method").

pascalstring

Term rendered with the first character of each word capitalized and joined together (for example, "PaymentMethod").

capitalstring

Term rendered with the first character of each word capitalized and separated by a space (for example, "Payment Method").

camelstring

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​

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

KeyDescription
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