Concepts
The eight concepts that connect your API spec to generated packages, review, and releases.
Typeship maintains a CLI, MCP server, or SDK from your API. These eight concepts describe what you provide, what Typeship generates, and what you review:
| Concept | Meaning |
|---|---|
| Project | One API product, its settings, and the Targets you maintain together. |
| Spec | The OpenAPI or GraphQL contract for the Project. It can draw from one file or several; Typeship records the exact revision used for each Generation. |
| Target | One CLI, MCP server, or SDK maintained from the Spec. Each Target has its own configuration and release history. |
| Delivery | Where a Target goes, such as a GitHub repository or hosted MCP endpoint. |
| Generation | One attempt to produce a Target from a specific Spec revision and configuration. It records the files, coverage, warnings, and result. |
| Draft | The Target's review branch and pull request in a repository Delivery. It holds the proposed package changes, version, and checks. |
| Release | An immutable package version recorded after a checked Draft with package changes merges. Publishing to a registry has its own status. |
| Diagnostics | Findings about the Spec that help you correct API problems before generation and release. |
flowchart LR Project --> Spec Project --> Target Project --> Delivery Spec --> Diagnostics Spec --> Generation Target --> Generation Generation --> Draft Delivery --> Draft Draft --> Release
For example, a Project for the fictional Parcel API could use one Spec to maintain a CLI for support staff and a TypeScript SDK for applications. Each is a separate Target with its own Delivery, Draft, and release history.
From source change to release
For a GitHub Spec, Typeship reports compatibility, Diagnostics, and Target previews on the source pull request. Merging that source change can start a Generation for each affected Target. A URL Spec can also trigger generation when its content changes, without a source pull request.
For a repository Delivery, Typeship opens or updates one Draft per Target. Review its files, package version, conflicts, and checks before merging. Typeship carries the code you last merged into the next Draft. It also preserves non-overlapping changes you make on the Draft; overlapping changes need your decision. See Generation behavior and Customize generated packages.
Merging a checked Draft with package changes creates a Release. Changes only to tests or checks update the code Typeship carries forward but do not create a release. Your repository can publish a Release to a registry after the merge; publishing status shows whether each destination succeeded.
Start with Projects, Specs, or Targets to configure a saved workflow.