DEV Community: Stainless

Introducing the (experimental!) Stainless SQL SDK generator

CJ Avilla — Wed, 18 Feb 2026 15:09:31 +0000

If you run analytics, reconciliation, or batch jobs in PostgreSQL, pulling data from REST APIs usually means ETL scripts, intermediary services, or brittle sync pipelines. The data you need is one HTTP request away, but PostgreSQL is not designed to call HTTP endpoints as part of a query plan.

You can bolt on ad-hoc HTTP functions, but you lose typing, pagination ergonomics, and a spec-driven interface.

We built an experimental SQL SDK generator that turns an OpenAPI spec into a PostgreSQL extension that uses PL/Python for HTTP requests. Every API endpoint becomes a SQL function. Every response type becomes a composite type. (We explain why we chose SQL functions over Foreign Data Wrappers below.)

A SQL SDK enables users to query your API using standard SQL.

What you get: REST API calls as SQL functions

To show you how our SQL SDK generator works, we used a subset of the Stripe OpenAPI spec to generate an experimental SQL SDK. You can install it by cloning the extension repo and running ./scripts/repl or by manually building with make install.

Each API endpoint maps to a SQL function. Each resource maps to a PostgreSQL schema. The result is a typed interface to a REST API, accessible from any PostgreSQL client.

How it works

The extension is built on two layers:

PL/Python functions call a Stainless-generated Python SDK to handle HTTP requests, authentication, retries, request serialization, response parsing, and other networking concerns.
SQL function wrappers initialize the client, perform lenient type adaptation from Python objects to PostgreSQL composite types, and expose a typed SQL interface. A single client is initialized per session for performance.

Paginated endpoints employ SQL functions that use WITH RECURSIVE CTEs to repeatedly fetch pages using PL/Python function calls. Because the outer SQL function can be used inline, PostgreSQL can push down LIMIT clauses and stop requesting new pages once enough rows have been produced.

If pagination were implemented entirely in Python, PostgreSQL would buffer the full result set at the PL/Python boundary before applying LIMIT. By keeping auto-pagination in SQL, the query planner retains control over row consumption and can short-circuit additional HTTP requests.

The result is a standard PostgreSQL extension. Install with make install and load with CREATE EXTENSION:

CREATE EXTENSION IF NOT EXISTS plpython3u;
CREATE EXTENSION stripe;

Then configure with ALTER DATABASE.

For example, to configure an API key:

-- For persistent configuration (ensure your logs are secured):
ALTER DATABASE my_database SET stripe.secret_key = 'sk_test_...';

-- Or for a single session:
SET stripe.secret_key = 'sk_test_...';

Type-safe composite types, not `JSONB` blobs

Each API resource maps to a PostgreSQL schema. stripe_customer contains the customer composite type with typed fields: id TEXT, created BIGINT, email TEXT, livemode BOOLEAN.

The generator types fields where the spec is precise. Nested objects map to composite types, and arrays become typed arrays.

You get real column access instead of JSONB->>'field' casting:

-- Typed fields, not JSONB extraction
SELECT id, email, created, livemode
FROM stripe_customer.list()
LIMIT 10;

For complex parameters, the extension generates make_* constructor functions. The generator produces these from the OpenAPI spec, and they stay in sync when the spec changes.

What it looks like in practice

Create a customer:

SELECT *
FROM stripe_customer.create(
  email := 'jane@example.com',
  name := 'Jane Doe'
);

List customers:

SELECT id, email, name
FROM stripe_customer.list()
LIMIT 200;

The extension handles pagination automatically. A LIMIT 200 for an API that returns 100 items per page makes exactly two HTTP requests. Apply LIMIT as close to the API function call as possible so PostgreSQL can stop consuming rows once the limit is satisfied.

The real payoff is combining API data with your existing tables:

SELECT
  c.id AS stripe_id,
  c.email,
  o.total_amount,
  o.created_at
FROM stripe_customer.list() c
JOIN orders o ON o.email = c.email
WHERE o.created_at > NOW() - INTERVAL '30 days';

This query joins live Stripe customer data from the API with your local orders table. This replaces an ETL pipeline and staging tables with a single query.

Where SQL SDKs fit

SQL SDKs work well in many workflows, but they’re not a universal solution for every problem. They are most effective when you want to pull API data into analytical queries, scheduled jobs, or batch pipelines that already run inside PostgreSQL.

ETL and data sync

Combine materialized views with pg_cron for scheduled data pulls:

CREATE MATERIALIZED VIEW stripe_customers AS
SELECT id, email, name, created
FROM stripe_customer.list();

SELECT cron.schedule(        
  job_name  => 'refresh-stripe-customers',
  schedule  => '0 */4 * * *',
  command   => 'REFRESH MATERIALIZED VIEW CONCURRENTLY stripe_customers'
);

Every four hours, your database has a fresh snapshot of Stripe customers. Query it like any other table.

Business analytics

Ad-hoc queries that combine API data with your operational database: revenue reconciliation, customer segmentation, churn analysis. The queries run where the data already lives.

Batch LLM workflows

Select the latest support tickets, call an LLM classification endpoint, and write labels back to a table for downstream reporting. As LLM APIs publish OpenAPI specs, SQL SDKs make batch inference from SQL practical.

Where SQL SDKs are not a fit

SQL SDKs are not intended for low latency production OLTP paths. Each function call issues one or more HTTP requests, introducing network latency, rate limits, and remote failure modes. PostgreSQL’s planner optimizes relational operators over local data; it is not a cost based planner for REST APIs. Core SQL concepts such as predicate pushdown, join reordering, and index selectivity do not map cleanly to HTTP endpoints, so small query changes can result in additional remote calls. Use SQL SDKs for analytical and batch workloads where expressiveness and integration matter more than tail latency.

Why not generate Foreign Data Wrappers?

Generating Foreign Data Wrappers (FDWs) for APIs is appealing, but there are several drawbacks.

Performance is hard to reason about

A REST API FDW would hide the HTTP requests it makes.

The FDW has to determine which requests to make based on a query, making it a query planner for HTTP requests. A small change to a query could silently result in a less performant plan with many more HTTP requests. This would not be easy to debug.

An FDW over a REST API ends up being a leaky abstraction.
APIs are not always relational

FDWs shine when the data they’re modeling is relational. If the data an API provides is not relational, then it’s not well-suited for being represented as tables in an FDW.

Plain SQL functions work for any API.
A new interface to learn

Modeling API data in FDW tables would result in a different interface from the API and its SDKs, which means your users would have to learn a new API.

Plain SQL functions grouped by resource matches the existing structure of your API and its SDKs.

Current status: experimental

The SQL SDK generator works best with OpenAPI 3.x specifications that use standard request and response bodies and predictable pagination patterns. We generated a Stripe SQL SDK as the first example, but the generator is not Stripe-specific.

This is an experimental release. We're sharing it because we want feedback from developers who work at the intersection of APIs and databases. We're also expanding coverage and want to hear about OpenAPI specs that break the generator.

Expect breaking changes. This is not ready for production workloads. We are actively developing the generator and want to hear which use cases matter most to you.

If you’re using our SQL SDK generator in any capacity we’d love to hear from you. Let us know what you’re working on, if you run into any issues, or if you have feedback.

Try it out

The Stripe SQL SDK is available as a reference for what the generator produces. Clone the repo, run make install, load with CREATE EXTENSION stripe, and set stripe.secret_key.

Want a generated extension for your API? Sign up here to get early access and tell us which APIs you want to query from SQL. We are working toward supporting any API with an OpenAPI spec.

Sharper than ever: the Stainless C# SDK generator is now generally available

CJ Avilla — Tue, 17 Feb 2026 16:48:00 +0000

C# has a unique place in the programming language ecosystem. It powers enterprise software, AAA games, and even front-end web development through Blazor.

Our goal is to generate idiomatic SDKs that work great in all of these environments. Stainless provides high-quality C# code that takes full advantage of the language, and it feels like our SDKs are hand-crafted by an experienced .NET developer. We include things like strong typing, composition with LINQ, and good tooling support. These are things every C# developer expects.

It's a high bar, but it's one we managed to hit with the GA release of our C# SDK generator. Since launching our C# beta last summer, we've added more features while improving stability.

Key highlights

Full .NET Standard 2.0 support
Idiomatic types, conversions, and great editor tooling
Async enumerables for SSE/JSONL and auto-paging
Strong naming support
Minimal dependencies
Publishing to NuGet
File uploads and downloads
Sensible equality methods
Built-in generated tests
The ability to make raw requests when needed

Some noteworthy C# generator design decisions

Our goal is to generate idiomatic SDKs that feel at home in each language's ecosystem. We also strive to support advanced features and functionality, even if a particular language doesn't have native support for them. This approach shines through in some of the design decisions we made.

.NET Standard 2.0 support

The .NET ecosystem is splintered. Lots of people use .NET Standard, which has a limited subset of the full .NET functionality common across various .NET implementations, such as on vanilla Windows, UWP, Azure Functions 1.x, Xamarin, and many other runtimes. Others use .NET itself and have access to all of the modern features that make C# great.

The SDKs we generate have wide compatibility and provide the best developer experience possible. On .NET Standard 2.0, our SDKs are still full-featured, and have good DX even though some language features are missing.

On .NET 8 and above, our SDKs are fully idiomatic to the language, and take advantage of the available features.

We accomplished this by considering both stacks carefully as we built our generator. In many cases we were able to accomplish our goals with extensions which allowed us to create record classes that operate as normal classes on .NET Standard. In some cases we rely on preprocessor directives, although this is quite rare, and we ensure we only do this when truly required. As a result, our generated SDKs are still easy to read while supporting both stacks.

Amazing unions

Like many languages, C# does not support unions or sum types natively. There are a lot of tradeoffs when designing unions, and we don't have time to get into them all here. The bottom line is that every language has a unique set of constraints, so careful consideration is needed.

Our solution is for our unions to be backed internally by an object and a JsonElement. The object holds the union variant if one exists, and the JsonElement holds the raw JSON data from the API. This allows us to represent data that doesn’t match the union perfectly, which can be a problem if the OpenAPI schema deviates from the actual API. We have constructors for each possible variant, as well as an unknown variant constructor, which operates as an escape hatch. This can be useful for bypassing the OpenAPI schema when required.

To complement the constructors, we create implicit convertors from the variants. This keeps the DX light, as users don't need to wrap all of their unions. We also generate helper functions for switching and matching, which are inspired by the popular OneOf .NET library.

Basically, the goal was to make unions easy to use without compromising on type-safety or readability. Let’s take a look at an example below, where we have a Dealership SDK, which contains a Vehicle union with Car and Truck variants.

[JsonConverter(typeof(VehicleConverter))]
public record class Vehicle
{
    public object? Value { get; } = null;

    JsonElement? _element = null;

    // Gets the raw Json value, if the user needs it
    public JsonElement Json
    {
        get
        {
            return this._element ??=
                JsonSerializer.SerializeToElement(this.Value);
        }
    }

    // This property exists on both `Car` and `Truck`, so we
    // automatically bubble it up. We want the user to be able
    // to access it without having to destructure the union
    public long WheelsCount
    {
        get
        {
            return Match(
                car: (x) => x.WheelsCount,
                truck: (x) => x.WheelsCount
            );
        }
    }

    // For constructing a car variant
    public Vehicle(Car value, JsonElement? element = null)
    {
        this.Value = value;
        this._element = element;
    }

    // For constructing a truck variant
    public Vehicle(Truck value, JsonElement? element = null)
    {
        this.Value = value;
        this._element = element;
    }

    // For constructing an unknown variant
    public Vehicle(JsonElement element)
    {
        this._element = element;
    }

    // Helper method for picking a specific variant
    public bool TryPickCar([NotNullWhen(true)] out Car? value)
    {
        value = this.Value as Car;
        return value != null;
    }

    public bool TryPickTruck([NotNullWhen(true)] out Truck? value)
    {
        value = this.Value as Truck;
        return value != null;
    }

    // Exhaustive matching with no return type
    public void Switch(Action<Car> car, Action<Truck> truck)
    {
        switch (this.Value)
        {
            case Car value:
                car(value);
                break;
            case Truck value:
                truck(value);
                break;
            default:
                throw new DealershipSdkInvalidDataException(
                    "Data did not match any variant of Vehicle"
                );
        }
    }

    // Exhaustive matching with return type
    public T Match<T>(Func<Car, T> car, Func<Truck, T> truck)
    {
        return this.Value switch
        {
            Car value => car(value),
            Truck value => truck(value),
            _ => throw new DealershipSdkInvalidDataException(
                "Data did not match any variant of Vehicle"
            ),
        };
    }

    // These implicit operators are a lighter-weight way
    // to construct the union. Notice that we don't create one
    // for the unknown variant, as that's considered a more advanced
    // feature and in that case the user should be more explicit
    // about what they want.
    public static implicit operator Vehicle(Car value) => new(value);

    public static implicit operator Vehicle(Truck value) =>
        new(value);

    // ...snip...
}

This design delivers strong developer experience without sacrificing type safety or readability, and still allows developers to bypass the OpenAPI schema when needed.

Immutability by default

Many C# SDKs do not use immutable record classes even though mutability leaves room for logic bugs, thread-safety issues, and potentially sub-optimal performance. Part of making a great SDK is preventing these foot-guns wherever possible, so that developers can focus on building software.

Our C# SDKs use immutable record classes which are idiomatic and work around the issues above. Models are record classes, arrays use ImmutableArray, and dictionaries use FrozenDictionary. While looking at existing C# SDKs, we found a lot of prior art of people using mutable classes, like List and Dictionary, inside of supposedly immutable classes. We believe in a higher bar than this and made sure the data structures we generate are truly immutable.

Type-safe models with flexibility

A good SDK should make it difficult, but not impossible, to deviate from the OpenAPI spec. Usually, the spec is correct, and we want it to inform the type system and, by extension, the user. Pragmatically, sometimes the API deviates from its spec. Although there are numerous ways to work around this in the Stainless config, sometimes users still need to be able to use the SDK before this happens. This means our data model needs to support some amount of flexibility.

We work around this by backing our models with an internal read-only dictionary of <string, JsonElement> which holds the raw data. We immutably expose this to the user so that they can get the raw data if needed. Users can also construct models from their own dictionary, which allows them to bypass the schema when sending requests.

When the user doesn’t need to bypass the schema, they can use the C# properties we generate to access the model’s data. This makes the experience seamless, as if those properties were the actual backing data themselves.

Internally, we cache data so that the user doesn’t have to pay the JSON deserialization cost every time they access the same property. We do this in a thread-safe manner so that the end-user doesn’t have to think about it, and our models still appear entirely immutable.

Here’s what a model might look like:

[JsonConverter(typeof(JsonModelConverter<Cat, CatFromRaw>))]
// JsonModel holds RawData, which is the backing dictionary. It is
// also responsible for caching
public sealed record class Cat : JsonModel
{
    // Marked as required in the schema
    // (throws exception if missing)
    public required string FurColour
    {
        get
        {
            return this.RawData.GetNotNullClass<string>("furColour");
        }
        init { this.RawData.Set("furColour", value); }
    }

    // Marked as optional in the schema
    // (returns null if missing)
    public long? WhiskerCount
    {
        get
        {
            return this.RawData.GetNullableStruct<long>(
                "whiskerCount"
            );
        }
        init { this.RawData.Set("whiskerCount", value); }
    }

    // Constructor for object initializer syntax
    public Cat() { }

    public Cat(Cat cat)
        : base(cat) { }

    public Cat(IReadOnlyDictionary<string, JsonElement> rawData)
    {
        this._rawData = new(rawData);
    }

    // Constructor for bypassing the schema
#pragma warning disable CS8618
    [SetsRequiredMembers]
    Cat(FrozenDictionary<string, JsonElement> rawData)
    {
        this._rawData = new(rawData);
    }
#pragma warning restore CS8618

    // Constructor that allows setting all required members as
    // parameters, with the option of also using the
    // object initializer syntax
    [SetsRequiredMembers]
    public Cat(string furColour)
        : this()
    {
        this.FurColour = furColour;
    }

    // ... snip ...
}

You would instantiate the object like so:

Cat cat = new Cat()
{
    FurColour = "orange",
    WhiskerCount = 24
};

Or:

Cat cat = new Cat("orange")
{
    WhiskerCount = 24
};

Trusted by teams in production

The strongest proof of our SDK quality is real teams shipping production systems that depend on them. Here are a few companies using Stainless-generated C# SDKs today:

Our goal for this release was to make C# a first-class citizen in the Stainless ecosystem, with SDKs that feel at home in real .NET codebases. Our C# generator reflects that philosophy throughout: runtime-aware code generation, idiomatic models, strong typing with pragmatic escape hatches, and a focus on long-term maintainability over short-term convenience.

If you’d like to dig deeper, explore the changelog or start generating SDKs today by signing up for a Stainless account.

We’re excited to see what you build, and we’d love feedback from teams adding C# to their supported languages.

Iterate on your SDKs locally with the Stainless Language Server

CJ Avilla — Thu, 12 Feb 2026 20:10:18 +0000

Stainless users configure their SDKs with two files: a stainless.yml config and an OpenAPI spec. Together, these files define how your API maps to generated SDKs, from resource structure and method naming to type definitions and pagination behavior. Getting them right is what makes the difference between a generated SDK that feels hand-written and one that feels auto-generated.

Until now, editing these files meant working in the Stainless Studio or pushing changes and waiting for build feedback. That workflow works, but there are some limitations. You make a change, trigger a build, wait for diagnostics, fix an issue, and repeat. For quick iterations on your config or spec, that loop is slower than it needs to be.

Today, we're releasing the Stainless Language Server, which brings the editing capabilities of the Studio directly into your local development environment. If you use VS Code, Cursor, Neovim, Zed, or any editor that supports the Language Server Protocol, you can now get real-time feedback on your Stainless config and OpenAPI spec as you type.

What the Language Server does

The Stainless Language Server understands the relationship between your stainless.yml and your OpenAPI spec. It knows which endpoints map to which resources, which schemas are referenced where, and what valid configuration options look like in context. That understanding powers a set of features that make local editing significantly more productive.

Real-time diagnostics and quick fixes

The language server analyzes your Stainless config and OpenAPI spec in real-time, surfacing errors, warnings, and suggestions directly in your editor. This helps you catch issues before running a build. When a diagnostic does appear, common issues come with an autofix you can apply with one click, and warning-level diagnostics can be suppressed with a single action.

It’s powered by the same diagnostic engine as Studio, so you get identical feedback locally without leaving your editor.

Intelligent completions

When editing your stainless.yml, the language server offers context-aware autocompletion. It suggests valid config keys, endpoint paths, and schema names drawn from your OpenAPI spec. If you're defining a new resource method, it will suggest available endpoints. If you're referencing a schema, it will complete from the schemas defined in your spec.

This is especially useful for large APIs. Instead of switching between your config and a long OpenAPI spec to find the right path or schema name, completions surface the options directly.

Go to definition and find all references

You can use "Go to definition" to jump from a reference in your Stainless config straight to the corresponding schema, parameter, or endpoint in your OpenAPI spec. Use "Find all references" to see where a particular schema or endpoint is used across both files.

For teams working with specs that have hundreds of endpoints, this navigation alone saves significant time. You don't need to manually search through a large YAML file to find where a schema is defined or where an endpoint is referenced.

Codelenses in your OpenAPI spec

Codelenses appear inline in your OpenAPI spec, showing which schemas and endpoints are already configured in your Stainless config. This gives you a quick visual overview of your API's SDK coverage without switching files. You can see at a glance which parts of your spec are represented in your SDKs and which aren't.

Live transformations

If you use Stainless Transforms to reshape your OpenAPI spec, the language server generates and updates your transformed spec in real-time as you edit your config. You can see the effect of each transform immediately, without running a separate build step.

Getting set up

Setup takes a few minutes. Install the Stainless CLI, initialize your workspace, and add the extension for your editor.

Install the CLI:

brew tap stainless-api/tap
brew install stl

Initialize your workspace:

stl init

This creates a .stainless/workspace.json file that the language server uses to identify your project and locate your config and spec files.

Install the editor extension:

For VS Code and Cursor, search for "Stainless" in the Extensions view and install it. The extension bundles the langauge server, so no separate LSP installation is needed.

For Neovim and other LSP-compatible editors, install the language server package globally via npm:

npm install -g @stainless-api/stainless-language-server

Then configure your LSP client to run stainless-language-server --stdio. The server activates for YAML and JSON files when it detects .stainless/workspace.json in your project. The setup guide has editor-specific configuration examples.

The local development workflow

With the language server running, the workflow for iterating on your SDK configuration looks like this:

Open your stainless.yml and OpenAPI spec in your editor
Edit your config with completions and inline validation guiding you
See diagnostics in real-time as you type, catching misconfigurations before they reach a build
Use go-to-definition to navigate between your config and spec
Review codelenses to check SDK coverage across your API
When you're satisfied, push your changes to Stainless for a full build

This is the same set of features available in the Stainless Studio, now running locally. For teams that prefer working in their own editor, or that want to use AI coding tools like Claude or Cursor alongside their Stainless config, the language server makes that possible.

Try it out

The Stainless Language Server is available now. Install the VS Code extension or the npm package and check out the documentation for detailed setup instructions. If you run into issues or have feedback, reach out to support@stainless.com.

Stainless CLI generator: your API, now with `--help`

CJ Avilla — Mon, 09 Feb 2026 16:14:14 +0000

You can now generate a command line tool for your API directly from your OpenAPI spec with Stainless. Enable the CLI target in the Studio to generate a command line interface with proper argument parsing, automatic pagination, and the documentation features developers expect.

Command line tools are one of the fastest ways for developers (and agents!) to interact with APIs. They're scriptable, composable, and ideal for quick experimentation and iteration. Building a high-quality CLI tool that people actually want to use, however, requires a lot of work. You need to get a lot of things right, like output formatting, pagination, shell completions, manpages, cross-platform distribution, and more. Due to the amount of time and effort that’s normally required, many API providers either don’t provide a CLI or only provide a minimal, watered-down tool that developers find wanting.

With today's release, Stainless makes supporting the CLI easier than ever. You can generate a CLI tool from the same spec that powers your SDKs and keep everything in sync automatically.

Go, CLI, Go!

Under the hood, when we generate a CLI tool for your API, it’s actually a wrapper around your Go SDK.

A common question among our earliest CLI users was, “why Go?” It’s a great question! We chose Go for several reasons, but most of them boil down to the high performance and ease of distribution Go provides.

Go compiles to native binaries with no external runtime dependencies and near-instant startup time. Your users don't have to have Go installed, all they see is a fast, efficient, and native executable.

Go also has excellent cross-compilation support, which makes it easy for you to ship builds for macOS, Linux, and Windows across multiple architectures. That makes distribution straightforward for you, and installation easy for your users.

What you get

Every CLI tool we generate follows a resource-based structure that mirrors your API:

your-project [resource [sub-resource...]] method-name --method-arg value

For example, with an API that manages people, using the CLI would look like this:

# Retrieve a person by ID
your-project people retrieve --id 123

# Create a new person
your-project people create --job "President" \
    --name.full-name "Abraham Lincoln" \
    --name.nickname "Abe Lincoln"

# List all people (paginated automatically)
your-project people list

Method names and flags use kebab-case, the --help flag gives you full documentation for any command, and man pages are generated automatically so man your-project will work out of the box for your end users.

Shell completions are included for Bash, Zsh, fish, and PowerShell, and the CLI also works on Windows using the standard --flag=value syntax.

Argumentative arguments

Argument parsing is one of those problems that looks simple until you try to create a polished implementation. Shell scripting has many quirks that make complex payloads awkward. JSON requires nested quoting that's easy to mess up. If you want tab completion and proper --help documentation, your flags need to be defined statically (which rules out infinitely nested paths like --messages.0.content.0.text).And so on.

We spent a lot of time working through the tradeoffs. The design we landed on optimizes common cases, but handles complex structures with grace when you need them.

Pass simple values with intuitive syntax familiar to command line users:

your-project users create --name "Alice" --role admin

Use dot notation for nested objects up to two levels deep:

your-project people create \
    --name.first "Abraham" \
    --name.last "Lincoln" \
    --address.city "Springfield"

For anything deeper, or for complex polymorphic types, pass YAML or JSON inline:

  # YAML
  your-project people create \
      --name 'first: Abraham, last: Lincoln'

  # JSON
  your-project people create \
      --name '{"first": "Abraham", "last": "Lincoln"}'

Pass array values with repeated flags:

your-project users update --tag admin --tag reviewer --tag owner

Pipe full payloads via stdin. JSON and YAML both work:

your-project people create <<YAML
name:
  full_name: Abraham Lincoln
  nickname: Honest Abe
job: President
YAML

You can also combine piped input with flags. Flags override values from stdin, which is useful for templating:

cat base-user.json | your-project users create --role admin

Built for AI agents

CLI tools make great interfaces for agents.

When an agent uses raw HTTP, it has to construct headers, manage authentication, serialize request bodies, and parse responses. A CLI takes care of all of that: authentication is handled using environment variables, request bodies become flags, and responses come back as structured JSON. All by default!

And, perhaps most critically, a CLI tool is self-documenting. An agent can run --help to discover what's available.

We tested this with a CLI generated for the Spotify API. Claude Code ran --help to discover the available commands, constructed valid requests, and parsed the responses without needing external documentation.

https://www.youtube.com/watch?v=sXH3WBYMKFw

The same properties that make CLIs good for humans also apply to agents:

Predictable structure: resource method --flag value
Self-documenting: --help on every command
Good error messages: clear feedback when something's wrong and suggestions for mistyped command names or flags
Standard conventions: kebab-case flags, JSON output, meaningful exit codes

Robust distribution

Building a binary is one thing, but distributing it across platforms, setting up package managers, and keeping versions in sync with your API changes is quite another.

The Stainless CLI generator plugs into the same release flow as your other Stainless SDKs. When you merge a release PR, we use GoReleaser to automatically build binaries for macOS (arm64 and amd64), Linux (arm64, amd64, 386), and Windows (arm64, amd64, 386), and each release publishes to GitHub with all compiled binaries.

For macOS users, we support Homebrew out of the box. Configure your tap repository and Stainless keeps the formula updated automatically. Your users can install your CLI with a single command:

brew install your-org/tools/your-project

We're also working on support for more package managers, like npm.

Get started today

Enable the CLI target in your Stainless config alongside your Go SDK:

targets:
  go:
    # ...
  cli:
    binary_name: your-project

Check out our CLI generator docs for more details on setup and configuration. If you have any feedback, please reach out to support@stainless.com. We'd love to hear what you think!

How to generate a TypeScript SDK from your OpenAPI spec

CJ Avilla — Mon, 09 Feb 2026 15:47:45 +0000

If you maintain a public API, you've probably faced the same question: how do you help developers (and agents) integrate quickly without forcing them to hand-craft HTTP requests, parse JSON responses, and handle edge cases on their own?

The answer is a platform, not a single artifact. SDKs, documentation, and other tools work together to shape how developers experience your API.

This guide focuses on one component: the TypeScript SDK. For JavaScript and TypeScript developers, it is often the deciding factor between choosing your API or moving on to a competitor with better tooling.

This guide covers how to generate a TypeScript SDK from an OpenAPI specification. It covers the traditional approaches, where they fall short, and how to produce a production-ready SDK that feels hand-crafted.

Why a TypeScript SDK matters for your API

Without an SDK, developers must:

Read your API documentation and manually construct HTTP requests
Handle authentication headers, query parameter serialization, and request body formatting
Parse responses and map them to their own types
Implement error handling, retries, and pagination logic from scratch
Keep their integration code updated as your API evolves

A well-designed TypeScript SDK eliminates all of this. Developers get type-safe methods with autocomplete, compile-time error checking, and built-in handling for common patterns.

Integration time drops significantly.

The payoff is faster adoption and fewer support tickets, especially when something goes wrong. Strong TypeScript types make it easier for developers and agents to detect, understand, and recover from incorrect usage.

The traditional approach: OpenAPI Generator

The legacy starting point is the open-source OpenAPI Generator. It supports dozens of languages, including TypeScript, and can scaffold a client library from your spec in minutes.

Here's the typical workflow:

# Generate a TypeScript SDK using the fetch template
openapi-generator-cli generate \
  -i path/to/openapi.yaml \
  -g typescript-fetch \
  -o ./generated-sdk

This produces a functional SDK with TypeScript interfaces for your models and a client class with methods for each endpoint.

For internal tools or quick prototypes, this works. For a public-facing SDK that represents your product, the limitations become apparent quickly.

Where basic code generation falls short

Generic, non-idiomatic code. The templates produce functional output, but method names, class structures, and patterns don't always match what TypeScript developers expect. The code feels generated, not designed.

Missing advanced features. Real APIs need pagination, retries with exponential backoff, and structured error handling. OpenAPI Generator doesn't include these. Your users must implement them manually, which leads to inconsistent behavior across integrations.

Manual maintenance burden. Every time your API changes, you re-run the generator, manually bump versions, and publish to npm. There's no built-in handling for breaking changes or automated release workflows. The onus is entirely on your team.

Limited customization. Tweaking the output requires forking Mustache templates, which quickly becomes a maintenance project of its own.

We designed Stainless for teams that run into these limits. It takes the same OpenAPI input, but optimizes for production SDKs rather than scaffolding. The table below compares the two approaches.

Feature	OpenAPI Generator	Stainless
Error Handling	Basic (`ResponseError`, `FetchError`, `RequiredError`)	Rich hierarchy with many specific error types
Retry Logic	None built-in	Exponential backoff with jitter, Retry-After support
Pagination	Returns raw paginated response	Auto-pagination with async iterators
Streaming (SSE)	Not supported	Full SSE parser with `Stream` class
API Ergonomics	Verbose method names, single object params	Clean method names, positional + optional params
Type Safety	Good (`FromJSON` / `ToJSON` transforms)	Excellent (strict mode, exactOptionalPropertyTypes)
Middleware Support	Pre/post/onError middleware	Request options per-call
File Uploads	Basic FormData/Blob	`Uploadable` type (`File`, `Response`, `ReadStream`)
Documentation	JSDoc from OpenAPI spec	Rich TSDoc with code examples
Raw Response Access	Via ApiResponse wrapper	`.asResponse()` and `.withResponse()`
Environment Config	`basePath` in Configuration	Multiple named environments and env vars
Module System	Single export pattern	Dual ESM/CJS with conditional exports

How to generate a TypeScript SDK from OpenAPI with Stainless: the recommended approach

Stainless generates TypeScript SDKs from OpenAPI that follow idiomatic language conventions and include production features like retries, pagination, and structured errors by default.

This approach comes from experience building large-scale SDK platforms, including work on Stripe’s SDK infrastructure, where maintaining high-quality, hand-crafted SDKs across many languages required far more than mapping endpoints to methods.

Getting started

You can create a new project from an OpenAPI spec in about one minute:

Sign up for Stainless. Create an account at app.stainless.com using your GitHub account, then create an organization for yourself or your company.
Create a project. Create a new Stainless project for your API by providing an OpenAPI spec. You can paste a URL to a hosted spec, upload a file, or start from an example such as the Petstore API.

Note: A Stainless project represents a single API. From one project, you can generate and manage multiple SDKs in different languages, along with related artifacts such as documentation sites, CLIs, MCP servers, or Terraform providers, all driven from the same OpenAPI spec.

Once you create the project project, Stainless generates a TypeScript SDK and opens it in the Studio inside the dashboard. Stainless also invites you to a GitHub repository containing the generated SDK code.

What you get out of the box

The generated TypeScript SDK includes retry logic, streaming, pagination, and error handling that you would otherwise build and maintain yourself. Here's what that looks like in practice, using the OpenAI Node SDK as an example.

Zero dependencies. Stainless uses the built-in fetch API for HTTP requests. The SDK works in Node.js, Deno, Bun, Cloudflare Workers, Vercel Edge Runtime, and modern browsers without pulling in a single dependency.

Full type safety. Every model, request, and response is fully typed. Developers get autocomplete for all parameters and compile-time validation of their API calls:

import OpenAI from 'openai';

const client = new OpenAI(); // Uses OPENAI_API_KEY env var by default

const response = await client.responses.create({
    model: 'gpt-5.2',
    instructions: 'You are a coding assistant that talks like a pirate',
    input: 'Are semicolons optional in JavaScript?',
});

console.log(response.output_text);

Streaming (SSE). For APIs that support Server-Sent Events, the SDK provides a Stream class with async iteration built in. No manual SSE parsing required:

const stream = await client.responses.create({
    model: 'gpt-5.2',
    input: 'Say "Sheep sleep deep" ten times fast!',
    stream: true,
});

for await (const event of stream) {
    console.log(event);
}

Auto-pagination. List endpoints return async iterators that handle page tokens automatically. Developers don't need to write pagination logic:

// Automatically fetches more pages as needed.
for await (const job of client.fineTuning.jobs.list({ limit: 20 })) {
    console.log(job);
}

// Or work with a single page at a time:
let page = await client.fineTuning.jobs.list({ limit: 20 });
for (const job of page.data) {
    console.log(job);
}

Automatic retries. The SDK automatically retries for connection errors, 408 timeouts, 429 rate limits, and 5xx server errors with exponential backoff. Developers can configure this globally or per-request:

// Configure the default for all requests:
const client = new OpenAI({
    maxRetries: 0, // default is 2
});

// Or override per-request:
await client.chat.completions.create(
    { model: 'gpt-5.2', messages: [{ role: 'user', content: 'Hello!' }] },
    { maxRetries: 5 },
);

Configuring, publishing, and keeping SDKs in sync

Beyond what's generated out of the box, Stainless handles the operational side of SDK management:

SDK configuration. A stainless.yaml file controls how your API maps to SDK methods: resource grouping, pagination schemes, method naming, and more. The dashboard includes an LSP-powered editor with autocomplete and inline documentation.

Automated publishing. Connect your npm account and new SDK versions publish automatically when your API spec changes. Stainless supports secure OIDC-based trusted publishing through GitHub Actions.

Automated regeneration. A GitHub Action in your API repository keeps SDKs in sync automatically: open a PR that changes your spec and Stainless previews the SDK diff; merge it and release PRs are opened across all your SDK repos.

Real-world examples

Stainless generates the official, production SDKs for several major API providers, collectively handling millions of API calls daily:

OpenAI Node SDK: millions of weekly downloads
Anthropic TypeScript SDK: powers Claude integrations
Lithic Node SDK: card issuing and payment processing
Modern Treasury Node SDK: payment operations platform

Conclusion

Basic code generation tools work for internal tools or prototypes. For a public SDK that represents your product, you need production-ready features: zero dependencies, full type safety, built-in pagination and retries, and automated publishing.

Stainless generates TypeScript SDKs with these features built in. The result is faster adoption, fewer support tickets, and a stronger API platform.

Ready to generate your TypeScript SDK? Get started with Stainless or read the documentation to learn more.

DEV Community: Stainless

Introducing the (experimental!) Stainless SQL SDK generator

What you get: REST API calls as SQL functions

How it works

Type-safe composite types, not JSONB blobs

What it looks like in practice

Where SQL SDKs fit

ETL and data sync

Business analytics

Batch LLM workflows

Where SQL SDKs are not a fit

Why not generate Foreign Data Wrappers?

Current status: experimental

Try it out

Sharper than ever: the Stainless C# SDK generator is now generally available

Key highlights

Some noteworthy C# generator design decisions

.NET Standard 2.0 support

Amazing unions

Immutability by default

Type-safe models with flexibility

Trusted by teams in production

Iterate on your SDKs locally with the Stainless Language Server

What the Language Server does

Real-time diagnostics and quick fixes

Intelligent completions

Go to definition and find all references

Codelenses in your OpenAPI spec

Live transformations

Getting set up

The local development workflow

Try it out

Stainless CLI generator: your API, now with `--help`

Go, CLI, Go!

What you get

Argumentative arguments

Built for AI agents

Robust distribution

Get started today

How to generate a TypeScript SDK from your OpenAPI spec

Why a TypeScript SDK matters for your API

The traditional approach: OpenAPI Generator

Where basic code generation falls short

How to generate a TypeScript SDK from OpenAPI with Stainless: the recommended approach

Getting started

What you get out of the box

Configuring, publishing, and keeping SDKs in sync

Real-world examples

Conclusion

Type-safe composite types, not `JSONB` blobs