API overview

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

The Typeship API drives the same model as the Console. Typeship's SDKs, CLI, MCP server, API reference, and skills are generated from this API's own OpenAPI Definition, so the contract is dogfooded on every change.

https://typeship.dev/api/v1

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

Resources

Resource	Purpose
`generate`	Statelessly generate one Target from one inline or URL Definition.
`projects`	Own one API product, its Definition, and generation controls.
`targets`	Own one maintained generated product, configuration, Deliveries, edition, and release line.
`target_releases`	Read immutable destination releases after exact candidates merge.
`definitions`	Read or update source, patches, GraphQL settings, Diagnostic policy, and latest revision.
`definition_revisions`	Read immutable resolved graph metadata and exact source-document content.
`generations`	Read one Target Generation and its files.
`diagnostics`	Read deterministic findings and apply exact remediations.
`account`	Read the authenticated organization.
`api_keys`	List and revoke keys.

Conventions

JSON request and response bodies use snake_case.
Resource IDs are typed: prj_*, def_*, drev_*, doc_*, tgt_*, dlv_*, gen_*, rel_*, and key_*.
Every Generation has one target_id, one resolved generator, and one definition_revision_id.
Errors use one envelope and carry a request ID.
Lists use cursor pagination.
Project creation accepts Idempotency-Key.
Authenticate with an organization API key or organization-bound OAuth access token.

Stateless generation

curl -s https://typeship.dev/api/v1/generate \
  -H "Content-Type: application/json" \
  -d '{"definition":{"url":"https://api.acme.example.com/openapi.json"},"target":{"generator":"python-sdk"}}'

Stateless generation accepts exactly one Target. Anonymous runs include the first 25 operations and retain no Definition content or generated files.

Create a linked Project

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

The response includes definition_id. Use it to retrieve Definition Revisions or change the Definition. List the created tgt_* resources under /projects/{id}/targets. Triggering POST /projects/{id}/generations returns one independent Generation per active Target.

Deliberate boundaries

The API does not create API keys or change plans; those remain Console actions. Typeship does not execute customer code to construct Definitions, combine unrelated APIs, or expose compatibility aliases for prelaunch field names.

Overview

Resources

Conventions

Stateless generation

Create a linked Project

Deliberate boundaries

On this page