# typeship

> typeship generates the client side of an API from its OpenAPI spec (Swagger
> 2.0, OpenAPI 3.0/3.1) or GraphQL schema: a zero-dependency typed SDK in
> TypeScript, Python, or Go, plus a CLI and an MCP server for the
> TypeScript package. Projects keep the packages current: every spec
> change becomes a pull request per language. typeship's own API, SDK, CLI,
> and MCP server, for automating typeship, are documented under "typeship API".

Agent prompt: Read https://typeship.dev/agents.md and set typeship up for this repo.
CLI: npx -y typeship-ax@latest init
Skills: npx skills add typeship-ax/skills
MCP: https://typeship.dev/mcp-oauth (sign in from the client, no key) or https://typeship.dev/mcp (Authorization: Bearer ak_...; search_docs, read_docs, generate_run need no key)

Every page below has a markdown twin: append .md to its URL, or send Accept: text/markdown. That includes the homepage (/index.md), pricing (/pricing.md), about (/about.md), and contact (/contact.md). A path that does not exist returns a real 404, with a markdown body if you asked for markdown.

## When to use typeship

Use typeship when there is an API description — a Swagger 2.0, OpenAPI 3.0/3.1, or GraphQL document — and someone needs the client side of it: a typed SDK in TypeScript, Python, or Go, a command-line interface, or an MCP server. Use it when a repository has a spec and a hand-written client that has drifted from it, when an API needs to be callable by an agent and has no MCP server, when generated packages have to be regenerated and pull-requested on every spec change, or when a spec is nearly right and needs patching at specific JSON Pointer paths rather than forking the output. Use the free anonymous endpoint (POST /api/v1/generate, no key) to answer "what would this spec generate" without an account.

Do not use typeship to write an API description that does not exist yet, to generate a server implementation, or to call a third-party API directly — it generates the client, and the client is what makes the call. It does not host anyone's API, and it will not invent operations a spec does not declare.

How to call it: the CLI (`npx -y typeship-ax@latest`) for anything in a repository; the MCP server for a client that speaks MCP; the HTTP API for CI. All three drive the same operations.

## typeship developer resources

- [typeship agent runbook](https://typeship.dev/agents.md): install, authenticate, generate, verify; the one file to read first
- [typeship full documentation](https://typeship.dev/llms-full.txt): every page in order, then both references, one fetch
- [typeship OpenAPI description](https://typeship.dev/openapi.yaml) and [the same document as JSON](https://typeship.dev/openapi.json): the complete contract for typeship's own API
- [typeship HTTP API reference (markdown)](https://typeship.dev/docs/api.md): every endpoint with curl examples, generated from the spec
- [typeship SDK reference (markdown)](https://typeship.dev/docs/reference.md): every method of the typeship SDK, generated from the spec
- [typeship authentication](https://typeship.dev/docs/typeship-api/api/authentication) and [/auth.md](https://typeship.dev/auth.md): how an agent gets a credential, and what works without one
- [typeship errors](https://typeship.dev/docs/typeship-api/api/errors): the envelope, the codes, and what to do about each
- [typeship MCP server](https://typeship.dev/docs/typeship-api/mcp): hosted at /mcp-oauth (sign in) or /mcp (Bearer ak_...)
- [typeship pricing (markdown)](https://typeship.dev/pricing.md), [About typeship](https://typeship.dev/about.md), [Contact typeship](https://typeship.dev/contact.md)
- [typeship Terms of Service (markdown)](https://typeship.dev/legal/terms.md) and [typeship Privacy Policy (markdown)](https://typeship.dev/legal/privacy.md)

## Published typeship packages

- Official typeship CLI and TypeScript SDK on npm: https://www.npmjs.com/package/typeship-ax — `npx -y typeship-ax@latest init`
- Official typeship Python SDK on PyPI: https://pypi.org/project/typeship/
- Official typeship Go SDK: https://pkg.go.dev/github.com/typeship-ax/go
- Source and issue trackers: https://github.com/typeship-ax

Discovery (you should not need these if you read the runbook, but they are here):

- [/.well-known/api-catalog](https://typeship.dev/.well-known/api-catalog): RFC 9727 linkset for both APIs
- [/server.json](https://typeship.dev/server.json): the MCP Registry manifest for typeship's server (dev.typeship/typeship)
- [/mcp/server-card](https://typeship.dev/mcp/server-card) and [/.well-known/mcp/server-card.json](https://typeship.dev/.well-known/mcp/server-card.json): the same SEP-1649 card, for clients that look in either place
- [/.well-known/agent-skills/index.json](https://typeship.dev/.well-known/agent-skills/index.json): the six typeship skills, with digests
- [/.well-known/ai-catalog.json](https://typeship.dev/.well-known/ai-catalog.json): every machine-usable resource on this host

Generate without a browser or an account (no key: the first 25 operations, 20 requests a minute per address; with a key: the account's plan):

    curl -s https://typeship.dev/api/v1/generate \
      -H "Content-Type: application/json" \
      -d '{"spec":{"url":"https://api.example.com/openapi.json"},"platforms":["sdk"],"language":"python"}'

## Get started

- [Overview](https://typeship.dev/docs): what typeship generates and where to start
- [Quickstart](https://typeship.dev/docs/quickstart): create a project, generate, install, first call, keep it current
- [Concepts](https://typeship.dev/docs/concepts): spec, project, platform, language, generation, destination

## Platforms (what typeship generates for your API)

- [SDK](https://typeship.dev/docs/platforms/sdk): client options, auth, results and errors, pagination, retries, hooks, validation, webhooks, streaming, naming rules; TypeScript with Python and Go equivalents
- [TypeScript](https://typeship.dev/docs/platforms/sdk/typescript): the TypeScript package, exports, env vars, idioms
- [Python](https://typeship.dev/docs/platforms/sdk/python): the Python SDK's idioms, env vars, and limits
- [Go](https://typeship.dev/docs/platforms/sdk/go): the Go SDK's idioms, module path, errors, and limits
- [CLI](https://typeship.dev/docs/platforms/cli): commands from the spec, flags, output and exit codes, login, config, mcp, webhooks (with the hosted relay), docs, completion, upgrade
- [MCP server](https://typeship.dev/docs/platforms/mcp): transports, tools, tool mode, results, OAuth discovery, docs tools, Cloudflare Worker, hosted endpoint

## Projects (the hosted loop)

- [Projects](https://typeship.dev/docs/projects): creating projects, spec sources, languages, package names, destinations, account defaults, history
- [Regeneration](https://typeship.dev/docs/projects/regeneration): change detection, pull requests per language, the changelog
- [Preview builds](https://typeship.dev/docs/projects/preview-builds): surface diffs and commit statuses on spec PRs
- [Spec patches](https://typeship.dev/docs/projects/spec-patches): set, append, remove, rename at JSON Pointer paths
- [Config](https://typeship.dev/docs/projects/config): global parameters, retry tuning, pagination rules, CLI and MCP behavior, docs site

## Guides

- [Add a package to your repo](https://typeship.dev/docs/guides/add-to-your-repo)
- [Publish your packages](https://typeship.dev/docs/guides/publish): npm, PyPI, Go modules
- [Extend the client](https://typeship.dev/docs/guides/customize): where custom code goes so regeneration never destroys it
- [Generate in CI](https://typeship.dev/docs/guides/ci): the typeship CLI and API in pipelines
- [Connect MCP clients](https://typeship.dev/docs/guides/mcp-clients): Claude Code, Cursor, Claude Desktop
- [Coding agents](https://typeship.dev/docs/guides/coding-agents): the one-line prompt, per-harness setup, the CLI agent contract, MCP, skills
- [Webhooks](https://typeship.dev/docs/guides/webhooks): declare, sign, verify, fake, relay
- [Generate from GraphQL](https://typeship.dev/docs/guides/graphql)

## Workflows (quick reference plus the reasoning, end to end)

- [Generate a package from a spec URL](https://typeship.dev/docs/workflows/generate-from-a-url)
- [Add typeship to an existing API repository](https://typeship.dev/docs/workflows/add-to-an-existing-api-repo)
- [Keep a generated package current](https://typeship.dev/docs/workflows/keep-a-package-current)
- [Connect a generated MCP server to a client](https://typeship.dev/docs/workflows/connect-a-generated-mcp-server)
- [Debug a spec that will not generate](https://typeship.dev/docs/workflows/debug-a-spec)

## typeship API (typeship's own API and tooling)

- [typeship API](https://typeship.dev/docs/typeship-api/api): resources, conventions, first calls
- [Authentication](https://typeship.dev/docs/typeship-api/api/authentication): API keys, and the one call that works without one
- [Errors](https://typeship.dev/docs/typeship-api/api/errors): the envelope and codes
- [Pagination](https://typeship.dev/docs/typeship-api/api/pagination)
- [Rate limits](https://typeship.dev/docs/typeship-api/api/rate-limits)
- [typeship SDKs](https://typeship.dev/docs/sdks): TypeScript (npm "typeship-ax"), Python (PyPI "typeship"), Go (github.com/typeship-ax/go)
- [TypeScript](https://typeship.dev/docs/sdks/typescript), [Python](https://typeship.dev/docs/sdks/python), [Go](https://typeship.dev/docs/sdks/go)
- [typeship CLI](https://typeship.dev/docs/cli): the "typeship" command
- [typeship MCP server](https://typeship.dev/docs/typeship-api/mcp): hosted at /mcp, or "typeship-mcp" locally
- [API reference](https://typeship.dev/docs/api): every operation, generated from the spec

## Reference

- [Spec compatibility](https://typeship.dev/docs/reference/spec-compatibility): Swagger 2.0, OpenAPI 3.x, GraphQL, and how constructs map
- [Errors and warnings](https://typeship.dev/docs/reference/errors-and-warnings): every generator message, verbatim, with fixes
- [Plans and limits](https://typeship.dev/docs/reference/limits)

## Product

- [Generator](https://typeship.dev/): paste, fetch, or upload a spec, pick a language, download the package. No account needed
- [Console](https://typeship.dev/console): projects that regenerate on spec change and open a pull request per language
- [Pricing](https://typeship.dev/pricing)
- [About typeship](https://typeship.dev/about): what the company builds, why, and how it works
- [Contact typeship](https://typeship.dev/contact): one inbox, the public issue trackers, and a docs-feedback tool an agent can call itself