---
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/guides/add-to-an-existing-api-repo
markdown: https://typeship.dev/docs/guides/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" \
  --definition '{"source":{"kind":"repository","repository":{"provider":"github","identifier":"acme/api"},"path":"openapi.yaml"}}' \
  --targets '[
    {"name":"Acme CLI","generator":"cli","deliveries":[{"kind":"repository","repository":{"provider":"github","identifier":"acme/api"},"directory":"packages/cli"}]},
    {"name":"Acme MCP","generator":"mcp","deliveries":[{"kind":"hosted_mcp"},{"kind":"repository","repository":{"provider":"github","identifier":"acme/api"},"directory":"packages/mcp"}]},
    {"name":"Acme TypeScript SDK","generator":"typescript-sdk","deliveries":[{"kind":"repository","repository":{"provider":"github","identifier":"acme/api"},"directory":"packages/sdk","package_name":"@acme/sdk"}]}
  ]'

# 3. run the first generation; it lands as a pull request
typeship projects generate <project_id>
```

If the Definition is served at a URL rather than stored in GitHub, use `--definition '{"source":{"kind":"url","url":"https://..."}}'`; typeship checks it every 30 minutes when automatic regeneration is on.

## Why these commands

**Install the GitHub App.** Repository sources and destinations use the Typeship GitHub App. If a repository is not connected, the Console prompts you and `projects create` returns an installation link. Install it once per GitHub account or organization.

**Choose the destination.** A Delivery selects a repository and directory. Use the API repository for a shared pull-request stream, or a dedicated repository for an independent package release history. See [Add a package to your repo](https://typeship.dev/docs/guides/add-to-your-repo).

**Keep custom code outside the generated tree.** Wrap the client or add modules beside it. Store generator changes in Project configuration and Definition patches so they survive regeneration. See [Extend the client](https://typeship.dev/docs/guides/customize).

**Review each changed Target independently.** A Definition change opens one destination pull request per changed Target. Source pull requests receive Preview Generations before the Definition merges. See [Regeneration](https://typeship.dev/docs/projects/regeneration).

## What can go wrong

| You see                                                          | Do                                                                                                                                |
| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `definition is required`                                         | Pass `--definition` with `source.kind: url`, or `source.kind: repository` plus a GitHub repository reference and entrypoint path. |
| `plan_limit_reached` / `PLAN_LIMIT` when linking another project | Free keeps one linked project current; upgrade for additional projects, or delete down to the project you want active             |
| 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)