Go configuration

When enabled, ensures that all required properties are always included in API requests, even if they have default values or are otherwise optional in the implementation.

Overrides the API-wide api.settings.auto-generate-idempotency-key for this SDK. Set true to attach an idempotency-key header to eligible requests (POST and PUT by default) unless the caller provides one, or false to opt this SDK out when auto-generation is enabled API-wide. Pass an object to customize header-name and methods.

Customizes the name of the client constructor function. This allows you to specify a custom name for the function that users will call to create a new instance of the client.

Specifies the name of the generated client struct. This determines the primary client type name that users will interact with in the generated Go SDK.

Sets the name of the exported client that will be used in code snippets and documentation examples. This is useful for customizing how the client appears in generated documentation.

The default number of retries for failed requests. When not set, the generated SDK uses its own built-in default. SDK users can still override this per-request via request options.

Controls how the offset parameter is interpreted for auto-paginated endpoints.

• item-index: The offset counts individual items (e.g., offset 20 skips the first 20 items).
• page-index: The offset counts pages (e.g., offset 3 skips to page 3).

When enabled, the generated SDK omits the X-Fern-Language, X-Fern-SDK-Name, and X-Fern-SDK-Version headers from HTTP requests.

When enabled, the generated SDK sends a single structured User-Agent header of the form {sdkName}/{version} ({os}; {arch}) {runtime}/{runtimeVersion} (for example, my-sdk/0.0.1 (linux; x86_64) Go/1.22.0), carrying SDK, operating system, architecture, and runtime information in place of the default User-Agent and discrete platform headers. A configured user-agent template supplies the leading product token. If omitFernHeaders is enabled, no User-Agent or platform headers are sent and this option has no effect.

When enabled, the generated SDK exposes option.WithUserAgentAppInfo(name, version, comment), which appends a {name}/{version} ({comment}) product token to the User-Agent header so an application built on the SDK can identify itself to the API. The application passes a required name plus an optional version and comment; "" drops that part of the token. An explicit User-Agent header takes precedence, and omitFernHeaders suppresses the header entirely.

1
option.WithUserAgentAppInfo("partner-app", "3.1.0", "+https://partner.example")
2
// User-Agent: my-sdk/0.0.1 (linux; x86_64) Go/1.22.0 partner-app/3.1.0 (+https://partner.example)

Generates auto-pagination for endpoints whose cursor or offset page property is a top-level request body property (for example, cursor: $request.cursor). The generated pager advances the page by setting the field on the request object instead of on the query string. This defaults to false because enabling it changes the affected methods’ return types from a response to a pager. Nested body page properties (for example, cursor: $request.pagination.cursor) are unsupported and still generate a plain, non-paginated method.

Generates mock server (wire) tests to verify that the SDK sends the correct HTTP requests and correctly handles responses per the API spec. When enabled, Docker is required as a runtime dependency to run the generated tests.

Use this option if you plan to depend on the generated Go SDK from within your project, and not depend on it as a separate, published Go module.

You can generate the Go SDK code into a gen/go/api package with the following generators.yml configuration:

1
default-group: local
2
groups:
3
  local:
4
    generators:
5
      - name: fern-go-sdk
6
        version: 0.13.0
7
        config:
8
          importPath: github.com/<YOUR_ORGANIZATION>/<YOUR_REPOSITORY>/generated/go
9
        output:
10
          location: local-file-system
11
          path: ../generated/go

When enabled, includes legacy client options for backward compatibility with older versions of the SDK. This is useful for maintaining compatibility when upgrading SDK versions.

Controls whether file upload properties are generated as inline request properties instead of separate parameters. When enabled, file upload fields become part of the request struct rather than being passed as individual function parameters.

When enabled, path parameters are inlined into request types rather than being passed as separate function parameters. This creates a more unified request structure where path parameters are included in the request object.

Use this option if you plan to distribute the generated Go SDK as a separate, published Go module.

You can generate the Go SDK code into a separate module (defined with its own go.mod) with the following generators.yml configuration:

1
default-group: local
2
groups:
3
  local:
4
    generators:
5
      - name: fern-go-sdk
6
        version: 0.13.0
7
        config:
8
          module:
9
            path: github.com/<YOUR_ORGANIZATION>/<YOUR_REPOSITORY>
10
        output:
11
          location: local-file-system
12
          path: ../generated/go

This configuration will generate a go.mod alongside the rest of the Go SDK code at the target output location. With this, import statements within the generated Go SDK are all resolved from the configured module path.

By default, the generated go.mod will be set to 1.13. You can override this behavior by specifying the version key:

1
default-group: local
2
groups:
3
  local:
4
    generators:
5
      - name: fern-go-sdk
6
        version: 0.13.0
7
        config:
8
          module:
9
            path: github.com/<YOUR_ORGANIZATION>/<YOUR_REPOSITORY>
10
            version: "1.19"
11
        output:
12
          location: local-file-system
13
          path: ../generated/go

If you want to depend on the generated Go SDK locally (without distributing it as a separate Go module), and you use the module configuration option, you will need to modify your project’s top-level go.mod to include a replace statement:

1
module github.com/your/module
2
3
require "github.com/your/sdk" v0.0.0
4
replace "github.com/your/sdk" v0.0.0 => "path/to/generated/sdk"

Specifies the package name for the generated Go code. This determines the package declaration that will appear at the top of generated Go files and affects how users import the SDK.

Lets callers omit the request body on endpoints with an optional request body. A request wrapper with a nil body sends no body and no Content-Type header, instead of the JSON literal null. Enable this when your API treats a missing body differently from a null one.

Only applies to request bodies declared as a single named type. Required bodies and inlined request properties are unaffected.

Controls whether the generated SDK emits server URL variable client options and construction-time base-URL template interpolation. Set to false to disable both, falling back to the base-URL behavior from before server URL templating.

Controls the union type generation strategy. Use ‘v0’ for the legacy union implementation or ‘v1’ for the newer, more robust union handling approach that provides better type safety and discriminated union support.

When enabled, uses io.Reader interface for handling byte request bodies instead of byte slices. This is more memory-efficient for large payloads and follows Go best practices for streaming data.

Sets a custom User-Agent header template for requests sent by the generated SDK. The template is resolved at generation time and supports the {packageName}, {version}, {language}, {generatorVersion}, {organization}, and {apiName} placeholders.

1
config:
2
  user-agent: "plantstore-go-sdk/{version}"

This sends User-Agent: plantstore-go-sdk/0.1.0. With includePlatformHeaders enabled, the resolved value leads the structured header: User-Agent: plantstore-go-sdk/0.1.0 (linux; x86_64) Go/1.22.0. A value that doesn’t end in a version, such as plantstore/sdk-go, is used as-is. The allowUserAgentAppInfo token is appended after either form.