Quickstart

Create a project, generate your first package, install it, and make a call. Then link the spec so it stays current.

By the end of this page you will have a generated TypeScript SDK for your API installed in a project and making calls, and a typeship project that regenerates it when the spec changes.

You need a spec at a URL typeship can fetch: Swagger 2.0, OpenAPI 3.0 or 3.1, or a GraphQL schema or endpoint. If you do not have one handy, any public OpenAPI URL works for the walkthrough.

The walkthrough uses the console. Every step is also a command, shown in the agent notes: install the typeship CLI with npm install -g typeship-ax (or run it without installing, npx -y typeship-ax@latest ...), then typeship login.

Create a project

Sign in to the console and choose new project. Give it a name, paste the spec URL, and pick platforms. The TypeScript SDK is on by default. Add CLI and MCP server if you want them in this walkthrough.

The name matters more than it looks. Package and repository defaults derive from it, so name the project after the API: "Acme API", not "test".

For AI agents

typeship projects create --name "Acme API" --spec-url https://api.acme.example.com/openapi.json --languages '["typescript"]' --platforms '["sdk","cli"]'

(needs TYPESHIP_TOKEN). No account yet? typeship generate run --spec '{"url":"..."}' --out sdk/ generates without one, and the runbook at /agents.md covers the rest.

Generate

On the project page, choose generate now. typeship fetches the spec, generates, and opens the generation: every file, browsable, with the warnings for anything it skipped or approximated. Read the warnings once. They tell you what the spec left out.

Choose download .zip to get the package.

For AI agentstypeship projects generate <project_id> > generations.json, then write each data[].files[] entry to disk; or, for a one-off, typeship generate run ... --out sdk/ writes the files directly.

Install and make a call

Unzip the package into your repository and build it once:

unzip acme.zip -d vendor/acme
cd vendor/acme && npm install && npm run build && cd -
npm install ./vendor/acme

Then call your API:

import { AcmeClient, unwrap } from "acme";

const client = new AcmeClient({ bearerToken: process.env.ACME_TOKEN! });

const result = await client.accounts.list({ limit: 5 });
if (!result.ok) throw result.error;

for await (const account of client.accounts.list()) {
  console.log(account.id);
}

Your resource and method names come from your spec. api.md in the package lists every one of them.

If you generated the CLI, it is on your PATH now:

acme login --token "$ACME_TOKEN"
acme accounts list --limit 5

Keep it current

Open the project's settings and set a destination: a repository for the TypeScript package, such as acme/acme-node, and optionally a directory. Install the typeship GitHub App on that repository when prompted.

Then decide how typeship notices changes. Auto-regen is on by default:

If the spec lives in a GitHub repository, switch the source to github repo with the repository and path. Pushes that touch the spec regenerate the package.
If the spec is served at a URL, nothing more to do. typeship polls every 30 minutes.

From now on, every spec change becomes a pull request in the destination repository, with the API changes listed in the body. Review and merge. See Regeneration.