---
title: "Overview"
description: "A project is one spec and everything typeship generates from it: languages, platforms, package names, destinations, and the history of every generation."
url: https://typeship.dev/docs/projects
markdown: https://typeship.dev/docs/projects.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.

# Overview

A project is one spec and everything typeship generates from it: languages, platforms, package names, destinations, and the history of every generation.

A project is one spec and its lineage. You point it at a spec once, choose the languages and platforms it should produce, and tell it where the packages go. From then on, every generation is recorded, every spec version is kept, and every change to the spec turns into a pull request.

## Create a project

In the [console](https://typeship.dev/console), choose **new project**, then:

1. Give it a name. Repository and package defaults are derived from it, so name it after the API.
2. Paste the spec URL. typeship fetches it server-side on every generation, so the URL must be publicly reachable. Swagger 2.0, OpenAPI 3.0 and 3.1, and GraphQL are accepted. See [Spec compatibility](https://typeship.dev/docs/reference/spec-compatibility).
3. Pick platforms: an SDK in TypeScript, Python, or Go, plus the CLI and MCP server. TypeScript alone is the default. Each platform is billed per month on Pro.

> **For AI agents:** Everything here is one call: 
> 
> `typeship projects create --name "Acme API" --spec-url <url> --languages '["typescript","python"]' --platforms '["sdk","cli"]' --destinations '{...}'`
> 
> . 
> 
> `typeship projects create --help`
> 
>  lists every field; 
> 
> `typeship projects update <id>`
> 
>  changes any of them later.

The project opens on its settings page, where you can switch the source to a GitHub repository, turn platforms on and off, and set destinations. You can also create a project from the [typeship API](https://typeship.dev/docs/typeship-api/api) with every field in one call.

## From an anonymous generation

An anonymous `POST /v1/generate` or `typeship generate run` from a spec URL leaves a claim link behind (`claim.url` in the response, also noted by the typeship CLI in `.typeship/claims.json`). Open it signed in and choose **claim into my organization**: the run becomes a project here with the same spec URL, language, platforms, package name, and config, ready to regenerate. Platforms beyond your plan are left off and can be turned on in settings. Claims last seven days and can be taken once. Nothing else about the anonymous run is kept.

> **For AI agents:** After an anonymous 
> 
> `typeship generate run --spec '{"url":...}'`
> 
> , read 
> 
> `claim.url`
> 
>  from the response (or 
> 
> `typeship doctor`
> 
> ) and hand it to the user; that is how an unauthenticated run becomes a linked project without a key ever crossing the conversation.

## Organizations

Projects, API keys, and the plan belong to an organization, not to you. Your first organization is created when you sign up, and the organization menu at the top of the console sidebar switches between the ones you belong to. **Manage organization** opens members and invitations: invite a teammate by email and they see the same projects and generation history. Admins alone change billing, delete projects, and revoke keys other members created; members do everything else.

## Spec sources

A project has exactly one source.

**A URL.** typeship fetches it, follows redirects, and times out after 15 seconds. Specs up to 10MB. No credentials are sent, so the URL must serve the spec without auth. If the URL answers with something that is not a spec, typeship tries it as a GraphQL endpoint and runs the introspection query.

**A file in a GitHub repository.** Install the typeship GitHub App on the repository, then set the source to **github repo** with the repository (`acme/acme-api`) and the spec path (`openapi/api.yaml`). Pushes to the default branch that touch that path trigger regeneration, and pull requests that touch it get [preview builds](https://typeship.dev/docs/projects/preview-builds). The App needs read and write access to contents, pull requests, and commit statuses.

Which source you use decides how changes are detected, and when breaking changes are reported. Both sources get the changelog, the `typeship/semver` status, and the `breaking` label on every regeneration pull request. A repository source also gets preview builds, which report the same diff on the spec's own pull request before it merges. See [Regeneration](https://typeship.dev/docs/projects/regeneration).

## Platforms

A platform is one thing typeship generates from the project's spec: an SDK in one language, the CLI, or the MCP server. Project settings lists them under **platforms** with a switch each, grouped as **SDKs**, **CLI**, and **MCP server**. Each platform's own settings sit under its switch, so a setting only shows when the thing it configures is on.

**SDKs.** One switch per language: TypeScript, Python, Go. Each language that is on is its own generation, its own package, and its own pull request, with its package name and destination under the switch. A project generates at least one SDK.

**CLI, MCP server.** Built on the TypeScript SDK and shipped inside its package, so turning one on turns the TypeScript SDK on with it and keeps it on. Python and Go packages are SDK-only. Under the CLI: login and whoami settings, the support URL, the update notice, and the [webhook relay](https://typeship.dev/docs/platforms/cli#webhooks-listen). Under the MCP server: the tool shape and the [hosted endpoint](https://typeship.dev/docs/platforms/mcp#hosted-endpoint). The hosted features need their platform on and a paid plan. Turning a platform off turns its hosted feature off, and the URL stops answering.

Turning a platform off stops generating it and stops its pull requests. Nothing already delivered is removed: files stay in your repositories and published packages stay published. The next pull request for the TypeScript package is generated without it.

Every platform that is on is billed per month on Pro. The section shows the count, and the price once billing is on. Free projects run one platform, an SDK in one language, so the other switches show a **Pro** badge until the account upgrades. On the API the same list is `platforms` plus `languages`, and the API applies the same rules: `cli` and `mcp` require `typescript` among the languages, a hosted toggle requires its platform, and more platforms than the plan allows is a 402.

## Package names

Every ecosystem gets a name derived from your API's title. The Acme API produces `acme` on npm, `acme` on PyPI (imported as `acme`), and a Go module whose path comes from its destination repository. Brand casing survives: GitHub stays `github`, not `git-hub`. Words that say what a thing is rather than which thing it is (`api`, `rest`, `platform`, `sdk`) are dropped, so "Acme Payments Platform API v2" becomes `acme-payments`.

Override any of them per project under **package names**: an npm name or scope (`@acme/api`), a PyPI distribution name, or a Go module path (`github.com/acme/acme-go`). Names must be valid for their registry. The CLI bin and environment variable prefix follow the npm name, so `@acme/api` gives you the `api` bin and `API_TOKEN`.

## Destinations

Each language has a destination: a repository and, optionally, a directory in it. Pull requests land there. Two shapes work:

* **A dedicated repository per language.** `acme/acme-node`, `acme/acme-python`, `acme/acme-go`. This is what the ecosystems expect. `go get` resolves a module to a repository root, so Go in particular wants its own repository.
* **A directory in the spec's repository.** For a TypeScript package, leaving the destination empty falls back to the repository the spec lives in.

Python and Go need an explicit repository. Without one, the generation still runs and is recorded, but no pull request opens.

## Generations and history

Every run is a generation: one per language, with its trigger (manual, webhook, poll, or preview), its warnings, and every file. The project page lists the fifty most recent. Open one to browse the files, read the warnings, and download the package as a zip. Generations that opened a pull request link to it.

Every distinct spec typeship generated from is kept as a spec version, content-addressed by hash, with its source. A generation records which spec version it came from, so a build is reproducible from its real input. Read them back through the [typeship API](https://typeship.dev/docs/typeship-api/api).

## Delete a project

Deleting a project removes its generations, spec versions, and relay sessions. Packages already merged into your repositories are unaffected.

## Sitemap

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