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}

# '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
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: {}
targets:
node:
package_name: acme-typescript
production_repo: stainless-sdks/acme-typescript
publish:
npm: true
python:
package_name: acme
production_repo: stainless-sdks/acme-python
publish:
pypi:
package_name: acme-python
go:
package_name: acme-go
production_repo: stainless-sdks/acme-go
ruby:
gem_name: acme
production_repo: stainless-sdks/acme-ruby
publish:
rubygems: false

Config

KeyDescription
organizationOrganization

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

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

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

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

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

The name of the import, e.g. from <package_name> import …

publish{
pypi: boolean | {
// The name of the package in pypi, e.g. `pip
// install `
package_name?: string,
},
}
options?{ }

Go - targets.go

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

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

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

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.
//
// See
// uides/publish#java--kotlin-sonatype-maven-central
// for more information on how to publish your SDK.
sonatype_platform?: "portal" | "ossrh",
sonatype_host?: string,
},
}
options?{ }

Kotlin - targets.kotlin

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

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.
//
// See
// uides/publish#java--kotlin-sonatype-maven-central
// for more information on how to publish your SDK.
sonatype_platform?: "portal" | "ossrh",
sonatype_host?: string,
},
}
options?{ }

Ruby - targets.ruby

KeyDescription
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_namestring
publish{
rubygems: boolean,
}
options?{ }

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

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

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

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