OpenRouterTeam/openrouter-examples: a runnable example repo for the OpenRouter API

What openrouter-examples is for, and who it is aimed at

The repository describes itself as "Comprehensive, tested, executable examples demonstrating OpenRouter features across multiple ecosystems." That word, executable, is the whole pitch. This is not a client library and not a wrapper. It is a set of programs you run so that you can watch an OpenRouter feature behave, then lift the working call into your own code.

The audience is narrow and worth stating plainly. If you are integrating OpenRouter for the first time and your stack is TypeScript or a shell, the repository gives you a starting point that already runs. If you are on Python, it gives you nothing: the repository structure lists curl and typescript directories, and no Python track appears anywhere in the README or the top-level entries. That is a real gap given how much LLM integration work happens in Python.

The topics attached to the repository (ai, anthropic, docs, llm, openai, openrouter) describe the subject area rather than the contents. The actual feature coverage is much thinner than those tags suggest: prompt caching is the one feature with its own documentation page and its own examples in three separate ecosystems. Treat the repository as a prompt-caching reference with a general harness around it.

How the Bun monorepo and the Makefile fit together

The layout is a single root with two parallel tracks. The curl/ directory holds shell scripts that call the API with curl and pipe the responses through jq. The typescript/ directory is a Bun workspace monorepo with four packages: shared, fetch, ai-sdk-v5, and effect-ai, plus an openrouter-sdk package the README marks as TODO.

The data flow is deliberately duplicated rather than abstracted. Each package makes the same kind of request through a different client: raw fetch, the Vercel AI SDK v5, and Effect-TS. The shared package holds constants and types so that the examples do not drift on model names or endpoints, and the README calls this the "single source of truth." That is a sensible choice for a sample repository, where the point is to show idioms rather than to hide them behind an internal abstraction.

The Makefile is the only thing that ties the tracks together, and it is thin. Running make examples expands to the typescript target, which changes into the typescript directory and runs bun examples. The curl track is not part of that default: you have to ask for it with make curl. So the "run all examples" command does not, in fact, run all of them. That is a small documentation mismatch that will confuse anyone who reads the Quick Start literally.

Installing it and running your first example

Two prerequisites are named in the README: the Bun runtime and an OpenRouter API key. jq is needed only for the curl scripts. The repository ships a .env.sample containing a single key, OPENROUTER_API_KEY, with an empty value.

Start by exporting the key. The README's Quick Start uses this exact form:

export OPENROUTER_API_KEY="your-key-here"

Then install the TypeScript dependencies. The Makefile wraps the Bun install, so either of these works, and the second is what the Makefile runs underneath:

make install

cd typescript && bun install

With dependencies in place, run the TypeScript examples. The root target changes into typescript/ and invokes the workspace script:

make typescript

If you would rather see the raw HTTP shape of a request before any SDK is involved, run the curl track instead. It needs jq on your PATH:

make curl

To run one example on its own, the README gives the direct form. For the prompt-caching shell script:

bash curl/prompt-caching.sh

And for a single TypeScript package, from inside the package directory:

cd typescript/fetch && bun examples

The same pattern applies to typescript/ai-sdk-v5 and typescript/effect-ai. What you should see, according to the README, is verified output: the repository claims every example has been checked to work and that examples show expected outputs alongside verification. The README does not document what happens when a request fails, so do not expect a described error path.

Where the examples stop being useful

The clearest limitation is the SDK package. The repository structure in the README lists typescript/openrouter-sdk/ with the annotation "OpenRouter SDK examples (TODO)". If you arrived hoping for a supported client library with typed methods, this repository does not provide one yet. What it provides is hand-written calls through fetch and through third-party SDKs.

Prompt caching is the second place to be careful. The README links a documentation page and examples in curl, fetch, and ai-sdk-v5, and the effect-ai package has a prompt-caching directory as well. But caching behaviour is provider-dependent, and the repository does not claim to normalise across providers. The examples show how to structure a request; whether a given model or upstream provider actually caches it is outside what this repository can tell you.

There is also no release history. No releases were retrieved for the repository, which fits a samples project: you consume it by cloning or by copying files, not by pinning a version. That means there is no changelog to consult when an example breaks against a newer API. The last push to the repository was on 2026-03-30, so the code reflects the API as of that date and nothing later. If your integration depends on a feature added after that, the examples will not cover it.

openrouter-examples compared with the official OpenRouter docs

The obvious alternative is not a competing library but the documentation the repository itself points at: the homepage is https://openrouter.ai/docs, and every feature section in the README links back to a docs page. The difference in approach matters. The docs describe the API surface, parameters, and behaviour; this repository shows one working call per feature per ecosystem, with the surrounding project scaffolding needed to run it.

If you want to know which parameters exist, read the docs. If you want to know what a prompt-caching request looks like in Effect-TS, read the examples. The repository is a companion, not a substitute, and it is honest about that by linking out at every step.

The second alternative is to skip both and write the call yourself against the raw HTTP endpoint, which is essentially what the fetch package demonstrates. That is viable for a single integration and avoids pulling in the Bun workspace. It becomes worse the moment you want the same request expressed in three client styles, which is the specific thing this repository saves you from doing.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-03-30. That is roughly five and a half months before today, so the code is recent enough to be worth reading but there is no release cadence to rely on. There are no releases, no version tags in the README, and no dependency-upgrade workflow described. Upgrading means pulling the branch and re-running make install, then chasing whatever API changes have landed since the examples were last touched.

On licence: the README's License section points to LICENSE.md, and the repository metadata identifies the licence as MIT. That is permissive and typical for sample code, which means copying an example into your own project is the intended use. This is not legal advice, and if you are vendoring the examples into a commercial product you should read LICENSE.md yourself rather than take a summary.

The maintenance cost you should actually budget for is the shared constants package. Because model names and endpoints live in typescript/shared/, an API-side change touches every example at once. That is the design working as intended, but it also means the repository can go stale in a single commit if nobody updates that package.

Editorial conclusion

Adopt it if you are starting on the OpenRouter API from a TypeScript or shell stack and want code you can run before you read the docs. Skip it if you work in Python, or if you need a maintained client library rather than samples: the typescript/openrouter-sdk/ directory is marked TODO in the README. Before you build on it, verify two things yourself: whether the prompt-caching examples match your provider's caching rules, and whether the constants in typescript/shared/ still line up with the endpoints you plan to call.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. OpenRouterTeam/openrouter-examples on GitHub
4. Project website
5. README