---
title: "Overview"
description: "Typeship's HTTP API for Definitions, Targets, Generations, Diagnostics, and agent-driven automation."
url: https://typeship.dev/docs/typeship-api
markdown: https://typeship.dev/docs/typeship-api.md
section: "API"
---
> ## 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.

# 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.

```text
https://typeship.dev/api/v1
```

The generated reference is at [API reference](https://typeship.dev/docs/api), and the OpenAPI document is at [/openapi.yaml](https://typeship.dev/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

```bash
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

```bash
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.

## Sitemap

[Every page of these docs](https://typeship.dev/llms.txt)