Customize responses

Response formats

When generating SDKs, response formats determine the structure of response types in supported languages. Three available response formats are available to choose from.

Configure the response format for a given target in the gen.yaml file:


typescript:  # Python and Go can be configured in a similar way
  responseFormat: flat  # Or envelope-http, or envelope
 
  packageName: @acme/super-sdk
  version: 0.1.0
  author: Speakeasy
 
  templateVersion: v2
  clientServerStatusCodesAsErrors: true
  maxMethodParams: 4
  flattenGlobalSecurity: true
  inputModelSuffix: input
  outputModelSuffix: output
  additionalDependencies:
    dependencies: {}
    devDependencies: {}
    peerDependencies: {}
  imports:
    option: openapi
    paths:
      callbacks: models/callbacks
      errors: models/errors
      operations: models/operations
      shared: models/components
      webhooks: models/webhooks

The following sections will reference this specification:


  /payments/{id}:
    get:
      operationId: getPayment
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Details about a payment
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Payment"
components:
  schemas:
    Payment:
      type: object
      required: [id,amount,currency]
      properties:
        id:
          type: integer
        amount:
          type: number
        currency:
          type: string

`responseFormat: flat`

The flat response format is the simplest and most ergonomic option, as it avoids generating a wrapper type, giving SDK users direct access to the response value.

When responseFormat: flat is enabled, the generated SDK code will return the Payment type directly with no indirection:

To debug HTTP metadata, users can pass a custom client to the SDK instance.

`responseFormat: envelope-http`

The envelope-http format builds response types with a wrapper that holds the response value and associated HTTP metadata.

When envelope-http is enabled, the generated SDK code will produce the response types below:

Built-in HTTP metadata is included in both custom and built-in error types that are thrown or returned from the SDK.

Of the three response formats, envelope-http provides the most details about the underlying HTTP requests but adds a layer of indirection with a wrapper value.

Accessing HTTP headers with envelope-http

When using envelope-http, HTTP headers are accessible through the httpMeta.response.headers property, providing a cleaner structure than using rawResponse:


const { data } = useEmployeesGetSuspense({
  companyId,
  page: currentPage,
  per: itemsPerPage,
});
 
console.log(data.httpMeta.response.headers.get("x-total-count"));

Headers in SDKs

Headers in SDKs are treated as metadata rather than structured response objects for several reasons:

Headers are metadata, separate from the main response payload
The dynamic nature of headers makes strict typing impractical
This approach follows standard SDK behavior across the industry

While headers can be defined with types in OpenAPI, SDKs generally don’t expose them as typed properties. The envelope-http format provides a clear separation between HTTP metadata (including headers) and the main response payload.

`responseFormat: envelope`

The responseFormat: envelope format builds response types with a wrapper that holds the response value and minimal information about the underlying HTTP response.

Using envelope-http instead of envelope is recommended as it provides a more complete view of the HTTP request and response.

When responseFormat: envelope is enabled, the generated SDK code will produce the response types below:

Last updated on September 16, 2025