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 |
targets? | { |
environments | Record<string, string> Map of the name of the environment which appears in the SDK to the corresponding url to use. |
resources | { 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 |
client_settings? | ClientSettings Settings for customizing the Client class in the SDKs. |
pagination? | { Defines pagination schemes for pagination helpers and auto-pagination in the SDKs. |
unspecified_endpoints? | Array<string> List of endpoints to explicitly ignore, such as |
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 | { 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 |
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
' |
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 |
production_repo? | string | null The production repo that this target is linked to. For example, You can optionally add a branch target, such as |
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 |
publish | { |
options? | { |
custom? | { } |
Python - targets.python
Key | Description |
---|---|
readme_title? | string Title for this package, typically used to display the README header in the format |
production_repo? | string | null The production repo that this target is linked to. For example, You can optionally add a branch target, such as |
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. |
project_name? | string The Python project name, e.g. |
publish | { |
options? | { |
Go - targets.go
Key | Description |
---|---|
readme_title? | string Title for this package, typically used to display the README header in the format |
production_repo? | string | null The production repo that this target is linked to. For example, You can optionally add a branch target, such as |
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? | { |
Java - targets.java
Key | Description |
---|---|
readme_title? | string Title for this package, typically used to display the README header in the format |
production_repo? | string | null The production repo that this target is linked to. For example, You can optionally add a branch target, such as |
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 |
publish | { 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 |
production_repo? | string | null The production repo that this target is linked to. For example, You can optionally add a branch target, such as |
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 |
publish | { 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 |
production_repo? | string | null The production repo that this target is linked to. For example, You can optionally add a branch target, such as |
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 | { |
options? | { } |
Resource - resources.*
Key | Description |
---|---|
custom? | boolean Set |
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 |
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, |
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 |
deprecated? | string | Record<string, string> Set the deprecation message for this resource |
skip? | boolean | Array<SupportedLanguage> Skip SDK generation for a resource by specifying |
only? | Array<SupportedLanguage> Opposite of |
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. |
unwrap_response? | string | false Response property to be unwrapped so users don't have to access it themselves |
paginated? | boolean | string Provide |
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? | { Configure the default request options for an individual method |
docs? | { |
skip? | boolean | Array<"node" | "python" | "go" | "java" | "kotlin" | "ruby"> Skip SDK generation for a resource by specifying |
only? | Array<"node" | "python" | "go" | "java" | "kotlin" | "ruby"> Opposite of |
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" | "python" | "go" | "java" | "kotlin" | "ruby"> Skip SDK generation for a resource by specifying |
only? | Array<"node" | "python" | "go" | "java" | "kotlin" | "ruby"> Opposite of |
deprecated? | string | Record<string, string> Set the deprecation message for this method |
Model - resources.*.models.*
Key | Description |
---|---|
type? | "model" |
openapi_uri? | string
All If you need a more powerful way to match a schema, |
source? | string Deprecated: use Source for the model, either a ref (for example, "Card") or an endpoint response object (for example, "get /blah") |
path? | string Deprecated: use To define a model based on a property within the |
skip? | boolean | Array<"node" | "python" | "go" | "java" | "kotlin" | "ruby"> Skip SDK generation for a resource by specifying |
only? | Array<"node" | "python" | "go" | "java" | "kotlin" | "ruby"> Opposite of |
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" | "python" | "go" | "java" | "kotlin" | "ruby"> Skip SDK generation for a resource by specifying |
only? | Array<"node" | "python" | "go" | "java" | "kotlin" | "ruby"> Opposite of |
Readme - readme
Key | Description |
---|---|
example_requests | { 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 |
example_types? | { 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 |
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. |
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" | "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:
Type:
Type:
Type:
Type:
Type:
|
required? | boolean |
Settings - settings
Key | Description |
---|---|
license? | "Apache-2.0" | "MIT" | { License to use in all SDKs (defaults to Apache-2.0) |
python? | { |
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? | { 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? | { 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? | { |
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 Example object:
|
array_format? | "comma" | "repeat" | "indices" | "brackets" Configures how query parameters with array values render in the query string. Accepted values are Example object:
|
OpenAPIConfig - openapi
Key | Description |
---|---|
code_samples? | { Defines automatic snippet generation directly into your OpenAPI spec. Supported providers:
|
custom_casings
InitialismConfig
Key | Description |
---|---|
initialism | boolean If set to true, the term is used as an initialism: treated as an abbreviation of initial letters (for example, "CPU" and "API"). If set to false, the term is removed from the set of initialisms. By default we use |
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 |
---|---|
union? | { 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:
|