Overview

The typeship API is how you automate typeship: generate a package from a pipeline, create and configure projects in code, trigger regeneration, read generations and spec versions, and check usage. It is also how agents drive typeship. The typeship SDK, typeship CLI, and typeship MCP server are all generated from this API's spec by typeship itself, so they mirror it exactly.

https://typeship.dev/api/v1

The full reference, generated from the OpenAPI spec with request and response schemas and a playground, is at API reference. The spec itself is at /openapi.yaml.

Resources

Conventions

• JSON in and out, snake_case field names, ISO 8601 timestamps.
• Every resource has an object field and a typed, prefixed id: prj_, gen_, spec_, key_.
• Errors come in one envelope with a request id. See Errors.
• Lists page with a cursor. See Pagination.
• Authenticate with an API key. See Authentication.

A first call

Generate a Python package from a public spec:

curl -s https://typeship.dev/api/v1/generate \
  -H "Authorization: Bearer $TYPESHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"spec":{"url":"https://api.acme.example.com/openapi.json"},"platforms":["sdk"],"language":"python"}'

The response carries every file, the warnings, and metadata about what was generated:

{
  "files": [{ "path": "README.md", "content": "..." }, { "path": "acme/__init__.py", "content": "..." }],
  "warnings": [],
  "meta": {
    "title": "Acme API",
    "version": "2.3.0",
    "spec_format": "openapi",
    "package_name": "acme",
    "client_name": "AcmeClient",
    "operation_count": 6,
    "file_count": 18
  }
}

Ad hoc generation is capped at the first 25 operations and keeps nothing. To keep a package current, create a project:

curl -s https://typeship.dev/api/v1/projects \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme API",
    "spec_url": "https://api.acme.example.com/openapi.json",
    "platforms": ["sdk", "cli", "mcp"],
    "languages": ["typescript", "python"],
    "destinations": {
      "typescript": { "repo": "acme/acme-node" },
      "python": { "repo": "acme/acme-python" }
    },
    "auto_regen": true
  }'

Then regenerate on demand and read the result:

curl -s -X POST https://typeship.dev/api/v1/projects/prj_.../generations \
  -H "Authorization: Bearer ak_..."

The response is a list with one generation per language. See Generate in CI for a full pipeline.

What the API cannot do

• Create an API key. Keys are created in the console only. A leaked key that can mint keys is a leaked account.
• Change the plan. Billing runs through the console.
• Regenerate a repository-sourced project on demand. Those regenerate on push. Use generate now in the console to force one.