---
title: "Concepts"
description: "The handful of nouns typeship uses, and how they relate: spec, project, platform, language, generation, destination, and the packages that come out."
url: https://typeship.dev/docs/concepts
markdown: https://typeship.dev/docs/concepts.md
section: "Get started"
---
> ## Documentation index
> Fetch the complete documentation index at https://typeship.dev/llms.txt (every page, one line each) or the full text at https://typeship.dev/llms-full.txt.
> Append .md to any docs URL, or send Accept: text/markdown, for the markdown twin of that page.

# Concepts

The handful of nouns typeship uses, and how they relate: spec, project, platform, language, generation, destination, and the packages that come out.

## Spec

Your API's contract: a Swagger 2.0, OpenAPI 3.0, or 3.1 document, or a GraphQL schema. typeship reads it and never writes to it. There are no vendor extensions to add. Everything typeship needs beyond the spec lives in the project.

## Project

One spec and its lineage. A project holds where the spec lives, which languages and platforms to generate, package names and destinations, spec patches, config, and the history of every generation and every spec version. See [Projects](https://typeship.dev/docs/projects/).

## Platform

One thing a project generates from the spec, with a switch each in project settings:

| Platform | What it is                                                                                           |
| -------- | ---------------------------------------------------------------------------------------------------- |
| `sdk`    | A typed client, in TypeScript, Python, or Go. Each language is its own platform. At least one is on. |
| `cli`    | Every operation as a command.                                                                        |
| `mcp`    | Every operation as a tool for coding agents.                                                         |

The CLI and MCP server are built on the TypeScript SDK and ship inside the TypeScript package, so they keep that SDK on. Pro is priced per platform. Turning a platform off stops generating it; nothing already delivered is removed.

## Language

The ecosystem a package is generated for: TypeScript, Python, or Go. A project generates one package per language, each written in that language's idiom rather than translated from a template. Python and Go packages are SDK-only.

## Package

What a generation produces for one language: a complete, publishable package with readable source and zero runtime dependencies. Its name derives from your API's title unless you set one. It carries `api.md`, a full surface reference, and `AGENTS.md`, context for coding agents.

## Generation

One run of the generator for one language, recorded with its trigger, warnings, and files. A generation is reproducible from its spec version. Generations are triggered manually, by a push to the spec, by the URL poller, or as a preview on a pull request.

## Spec version

The exact spec text a generation came from, content-addressed by hash and kept per project. Read them back through the typeship API for diffs and audits.

## Destination

Where a language's package lands: a repository and, optionally, a directory. Regeneration opens pull requests there. Dedicated repositories per language (`acme/acme-node`, `acme/acme-python`, `acme/acme-go`) are the recommended shape.

## Regeneration

The loop that keeps packages current: detect a spec change, generate every language, open one pull request per language with the API changes spelled out. See [Regeneration](https://typeship.dev/docs/projects/regeneration).

## Sitemap

[Every page of these docs](https://typeship.dev/llms.txt)