Projects
Keep one API's Spec, Targets, configuration, and generation history together.
A Project is your saved integration for one API. Connect its Spec, choose the Targets you want to generate, and use its history to review what changed and what each run produced.
Use the Quickstart to create your first Project. For an API already in GitHub, follow Connect a repository.
Project boundaries
Create one Project for an API that is consumed and versioned together. Its Spec can span multiple files. Use separate Projects for independently consumed APIs, even when they share a repository.
A Project must have at least one Target. Each Target has its own configuration, Deliveries, and release history. You can add CLI, MCP, or SDK Targets as your users' needs grow.
| To change or inspect | Open |
|---|---|
| Source, revisions, patches, or GraphQL settings | Spec |
| Generated packages and their destinations | Targets |
| Generated files, warnings, and coverage | Generations |
| API authorship findings and policy | Diagnostics |
| Shared client defaults | Configuration |
| Automatic generation | Generation behavior |
Validation before saving
When you create a Project or update its Spec, Typeship resolves, patches, parses, and analyzes the complete spec before saving. Correct any reported source errors and retry. Free Projects retain and diagnose the complete Spec; the operation cap applies when you generate each Target.
Organizations
Projects, API keys, and billing belong to your Typeship organization. Members share Project and Generation history. Admins manage billing, destructive organization actions, and keys created by other members.
API shape
Project IDs use the prj_* prefix. List responses contain summaries; retrieving a Project adds its shared configuration and generation controls. Retrieve Targets separately to read their Deliveries.
| Field | Use |
|---|---|
spec_id | Retrieve or update the source, patches, GraphQL settings, and Diagnostics policy. |
auto_generate | Generate on source and saved configuration changes. It defaults to true for new Projects. |
config | Set defaults shared by the Project's Targets. |
Update a Project
PATCH /projects/{project_id} requires at least one field. Omitted fields keep their current values.
| Field | Supplied value |
|---|---|
name | Replace the name with a nonempty string of at most 80 characters. |
auto_generate | Set true or false; null is invalid. |
config | Replace the complete shared configuration, including nested objects. null or {} clears it. With automatic generation on, affected Targets regenerate. See configuration update behavior. |
Project updates accept an optional If-Match header with the ETag from a Project retrieve response. A stale ETag returns 412 precondition_failed; retrieve, reconcile, and retry. Without the header, concurrent updates to different fields preserve each other's values; updates to the same field replace it in the order Typeship saves them. A 409 target_busy means a Target is publishing; retrieve the Project and retry after publishing finishes. A 502 response can mean the settings were saved but Typeship could not retire an obsolete release PR; retrieve the Project before retrying. See conditional writes.
Update source settings through the Spec, and generated surfaces through Targets.
Create a Project with {name, spec, targets, auto_generate?, config?}. Put each Delivery inside its Target descriptor. Set config.cli.relay: true on a CLI Target to enable the Pro webhook relay. After creation, use spec_id for Spec changes and typeship targets list --project-id <project_id> --all for Targets and Deliveries. See the Typeship API for request schemas and authentication.