API overview

Typeship's HTTP API for Specs, Targets, Generations, Diagnostics, and agent-driven automation.

The Typeship API lets you connect Specs, configure Targets, run Generations, and inspect results from your own automation. It operates the same resources as the Console. Your generated Targets call your API; the Typeship API manages their generation and delivery.

https://typeship.dev/api/v1

The generated reference is at API reference, and the OpenAPI document is at /openapi.yaml.

Resources

Resource	Purpose
`generate`	Generate one package from an inline or URL Spec without creating a Project.
`projects`	Own one API product, its Spec, and generation controls.
`targets`	Own one maintained generated product, its configuration, and its Draft.
`releases`	Read the releases created when checked Drafts merge, with each destination's publishing status, and retry publishing.
`deliveries`	Read or change where each Target's package goes, and see whether it needs action.
`specs`	Read or update source, patches, GraphQL settings, Diagnostic policy, and latest revision.
`spec_revisions`	Read immutable resolved graph metadata, exact source-document content, and Diagnostics.
`generations`	Read one Target Generation and its files.
`organization`	Read the authenticated Organization.
`api_keys`	List and revoke keys.

Conventions

JSON request and response bodies use snake_case.
Accept added response fields and handle unfamiliar values explicitly. See Response compatibility.
Treat resource IDs as opaque strings: store them and send them back unchanged. Common prefixes include prj_*, spec_*, srev_*, tgt_*, dlv_*, gen_*, and rel_*. Spec files are addressed by path within a revision.
Copy API key IDs from GET /api-keys; do not assume a prefix. An API key ID identifies the key for revocation and is separate from the secret used to authenticate.
Every Generation has one target_id, one resolved type, and one spec_revision_id.
Every response includes a server-generated Request-Id header. JSON responses include the same value in the top-level request_id field.
Caller-supplied request IDs are ignored.
Lists use cursor pagination.
Project create, retrieve, and update responses contain only Project-owned fields. Read Targets and their Deliveries from the canonical paginated Target endpoints.
Generation lists and multi-Target Project generation responses return metadata only. Generated files and indexes appear only when retrieving one Generation.
Retry-sensitive writes accept Idempotency-Key; see Idempotent writes.
Authenticate with an organization API key or organization-bound OAuth access token.

Conditional writes

Retrieve a Project, Target, Spec, Draft, or API key to get its ETag response header. Send that value in If-Match when you PATCH or DELETE the resource. The generated CLI uses --if-match, and MCP tools accept if_match. The header is optional; without it, the write applies to the current resource.

If the resource changes before your write, Typeship returns 412 precondition_failed and saves nothing from that request. Retrieve it again, reconcile your intended change with its current state, then retry with the new ETag. A 409 signals a resource-specific state conflict; follow that operation's recovery guidance. Git SHA fields in Draft merge requests guard the customer's repository state and remain in the JSON body.

curl -i https://typeship.dev/api/v1/projects/prj_4f8k2m7x9q1v6b3n \
  -H "Authorization: Bearer ak_..."
# Copy the ETag response header, including its quotation marks.
curl -i -X PATCH https://typeship.dev/api/v1/projects/prj_4f8k2m7x9q1v6b3n \
  -H "Authorization: Bearer ak_..." \
  -H 'If-Match: "copied-etag"' \
  -H "Content-Type: application/json" \
  -d '{"auto_generate":false}'

One-shot generation

curl -s https://typeship.dev/api/v1/generate \
  -H "Content-Type: application/json" \
  -d '{"spec":{"url":"https://typeship.dev/examples/petstore/openapi.yaml"},"target":{"type":"python_sdk"}}'

One-shot generation returns one package without creating a Project. Anonymous runs include 25 operations.

A cli Target is self-contained and requires no SDK descriptor or sibling Target.

Create a Project

This example uses a fictional Parcel API. Replace the repository and package names with your own.

curl -s https://typeship.dev/api/v1/projects \
  -H "Authorization: Bearer ak_..." \
  -H "Idempotency-Key: create-parcel-api" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Parcel API",
    "spec": {
      "source": {"type":"repository","repository":{"provider":"github","identifier":"parcel/api","path":"openapi/api.yaml"}},
      "diagnostic_policy": {"fail_on":"error","only_new":true,"suppressions":[]}
    },
    "targets": [
      {"name":"Parcel CLI","type":"cli","deliveries":[{"type":"repository","repository":{"provider":"github","identifier":"parcel/cli"}}]},
      {"name":"Parcel MCP","type":"mcp","deliveries":[{"type":"hosted_mcp"},{"type":"repository","repository":{"provider":"github","identifier":"parcel/mcp"}}]},
      {"name":"Parcel TypeScript SDK","type":"typescript_sdk","deliveries":[{"type":"repository","repository":{"provider":"github","identifier":"parcel/typescript","package_name":"@parcel/sdk"}}]},
      {"name":"Parcel Python SDK","type":"python_sdk","deliveries":[{"type":"repository","repository":{"provider":"github","identifier":"parcel/python","package_name":"parcel"}}]}
    ]
  }'

The response includes spec_id. The new Project starts automatic generation by default. Use the ID to retrieve Spec Revisions or change the Spec, and list the created tgt_* resources with GET /targets?project_id=. To request generation manually, call POST /projects/{id}/generate.

What the API does not do

Create API keys and change plans in the Console. Supply a supported OpenAPI or GraphQL spec; Typeship does not execute your application to construct it. Keep independently consumed APIs in separate Projects.

Overview