---
title: "Overview"
description: "typeship's own HTTP API, for driving generation and projects from scripts, pipelines, and agents. Everything the console does, minus creating API keys."
url: https://typeship.dev/docs/typeship-api/api
markdown: https://typeship.dev/docs/typeship-api/api.md
section: "Get started"
---
> ## 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 own HTTP API, for driving generation and projects from scripts, pipelines, and agents. Everything the console does, minus creating API keys.

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](https://typeship.dev/docs/sdks), [typeship CLI](https://typeship.dev/docs/cli), and [typeship MCP server](https://typeship.dev/docs/typeship-api/mcp) are all generated from this API's spec by typeship itself, so they mirror it exactly.

```text
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](https://typeship.dev/docs/api). The spec itself is at [/openapi.yaml](https://typeship.dev/openapi.yaml).

## Resources

| Resource        | What it does                                                                                                                |
| --------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `generate`      | Run the generator on a spec. Returns files, stores nothing.                                                                 |
| `projects`      | Create, configure, list, update, and delete projects. Trigger regeneration. List a project's generations and spec versions. |
| `generations`   | Read a generation, including its files, and fetch a single file.                                                            |
| `spec_versions` | Read a spec version and its raw content.                                                                                    |
| `account`       | Read the account behind a key and set its defaults.                                                                         |
| `usage`         | Hosted generation allowance, included endpoints, and who has been calling (by surface and agent harness, last 30 days).     |
| `api_keys`      | List and revoke keys.                                                                                                       |

## 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](https://typeship.dev/docs/typeship-api/api/errors).
* Lists page with a cursor. See [Pagination](https://typeship.dev/docs/typeship-api/api/pagination).
* Authenticate with an API key. See [Authentication](https://typeship.dev/docs/typeship-api/api/authentication).

## A first call

Generate a Python package from a public spec:

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

```json
{
  "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:

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

```bash
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](https://typeship.dev/docs/guides/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.

## Sitemap

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