---
title: "Add typeship to an existing API repository"
description: "The repository already has the API and its spec. Put the generated package beside it, wire a linked project, and let pull requests keep it current."
url: https://typeship.dev/docs/workflows/add-to-an-existing-api-repo
markdown: https://typeship.dev/docs/workflows/add-to-an-existing-api-repo.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.

# Add typeship to an existing API repository

The repository already has the API and its spec. Put the generated package beside it, wire a linked project, and let pull requests keep it current.

## Quick reference

```bash
# 1. once per machine
typeship login                                         # approve in the browser; a key is minted for this machine

# 2. once per repository: a project linked to the spec file in this repo
typeship projects create --name "Acme API" \
  --source '{"kind":"repo","repo":"acme/api","path":"openapi.yaml"}' \
  --languages '["typescript"]' --platforms '["sdk","cli","mcp"]' \
  --destinations '{"typescript":{"repo":"acme/api","directory":"packages/acme-node"}}'

# 3. the first generation lands as a pull request; merge it
typeship projects list-generations <project_id>
```

If the spec is served at a URL rather than a file, use `--spec-url https://...` instead of `--source`; typeship polls it every 30 minutes.

## Why these commands

**Install the GitHub App on the repository.** A repository source and a repository destination both go through the typeship GitHub App. The console prompts for it when you set a destination; the first `projects create` for a repository you have not connected returns the install link in the error. Install once per GitHub account or organization.

**The destination is a repository plus a directory.** Same repository as the API (`packages/acme-node`, `sdk/`) or a dedicated one (`acme/acme-node`). Same-repo keeps the spec and its client in one pull request stream; a dedicated repository keeps release history separate and is what you want when the package publishes to a registry. See [Add a package to your repo](https://typeship.dev/docs/guides/add-to-your-repo).

**Generated files are never edited by hand.** Wrap the client, add your own modules beside it, keep customizations in the project's config and spec patches so regeneration carries them. The package's `AGENTS.md` says this to coding agents too. See [Extend the client](https://typeship.dev/docs/guides/customize).

**Every spec change becomes a pull request per language** with the API changes in the body; review and merge. Preview builds on spec PRs show the diff before the spec merges. See [Regeneration](https://typeship.dev/docs/projects/regeneration).

## What can go wrong

| You see                                                    | Do                                                                                            |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `A spec source is required`                                | pass `--spec-url`, or `--source` with `kind: repo`, `repo`, and `path`                        |
| `plan_limit_reached` / `PLAN_LIMIT` on the second platform | the free plan runs one platform per project; add the rest on Pro, or start with the SDK alone |
| the first pull request never arrives                       | the GitHub App is not installed on the destination repository; the project page says so       |

> **For AI agents:** Do steps 1 and 2; stop before merging a pull request unless the user asked you to. Installing the GitHub App is a browser step for the user; give them the link from the error.

## Sitemap

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