# Typemark API

> Create an API token and work with your projects and publishes from scripts and CI.

The Typemark API lets scripts and CI read your projects and their publishes, for example to wait for a publish to finish before a release goes out. It's on every plan.

To download, edit, and publish docs from the terminal or CI, use the [Typemark CLI](https://docs.typemark.dev/automation/cli). It's built on this API and handles syncing and conflicts for you.

## Create an API token

<Steps>
  <Step title="Open your account">
    Click your name at the bottom of the dashboard sidebar, then **Account**.
  </Step>
  <Step title="Name the token">
    Under **API tokens**, give the token a name that says where it's used, like `GitHub Actions`.
  </Step>
  <Step title="Choose when it expires">
    Pick 30 days, 90 days, a year, or never. When a token expires, requests with it stop working.
  </Step>
  <Step title="Copy it">
    Click **Create token** and copy the token. It starts with `tmk_`.
  </Step>
</Steps>

<Callout type="warning">
  The token is shown once. Store it in your CI's secrets right away, for example as `TYPEMARK_TOKEN`. If you lose it, revoke it and create a new one.
</Callout>

A token acts as you. It can read every project you own or are a member of, with your role on each one. Keep it out of code and anything public.

### Revoke a token

On the **Account** page, click **Revoke** next to the token. Anything using it stops working straight away. The list shows when each token was last used, so you can spot ones nothing needs anymore.

## Make a request

Send the token in the `Authorization` header. All endpoints live under `https://typemark.dev/api/v1`.

```bash
curl https://typemark.dev/api/v1/user \
  -H "Authorization: Bearer $TYPEMARK_TOKEN"
```

```json
{
  "user": {
    "id": "6945f00a-3d8a-4609-8dd8-eb4c1aa3fbab",
    "name": "Ada Lovelace",
    "email": "ada@acme.com",
    "plan": "pro",
    "trialing": false
  },
  "token": {
    "name": "GitHub Actions",
    "hint": "tmk_…Z4Fr",
    "created_at": "2026-11-16T10:12:00Z",
    "last_used_at": "2026-11-16T10:14:00Z",
    "expires_at": "2027-02-14T10:12:00Z"
  }
}
```

`plan` is `free`, `pro`, or `business`. `business` is the Enterprise plan: the API keeps the plan's earlier name so scripts that check it keep working.

## Endpoints

| Method | Path | Returns |
|--------|------|---------|
| `GET` | `/user` | The token's user, their plan, and the token itself |
| `GET` | `/projects` | Every project you own or are a member of |
| `GET` | `/projects/{slug}` | One project, with its page count and latest publish |
| `POST` | `/projects` | Creates a project. Used by `typemark create`. |
| `GET` | `/projects/{slug}/deployments` | Recent publishes, newest first |
| `GET` | `/projects/{slug}/deployments/{id}` | One publish |
| `GET` | `/projects/{slug}/files` | Every file in the project, with its Git blob id, and the commit they're from |
| `GET` | `/projects/{slug}/archive` | The project's files as a `.tar.gz`. Pass `sha` for a specific commit. |
| `POST` | `/projects/{slug}/push` | Changes, adds, or deletes files as one commit, then publishes. Used by `typemark push`. |
| `POST` | `/migrate/mintlify` | Converts a Mintlify `docs.json` or `mint.json` into `typemark.json`. Used by `typemark migrate`. |
| `POST` | `/migrate/gitbook`, `/migrate/readme` | Converts a GitBook space or a ReadMe project into Typemark pages and `typemark.json`. Used by `typemark migrate`. |
| `POST` | `/openapi/pages` | The pages Typemark generates from an OpenAPI spec: send `source` (its path in `typemark.json`), `content` (its text) and `group`. Used by `typemark dev`. Nothing is stored. |
| `DELETE` | `/token` | Revokes the token that sent the request |

### Projects

```bash
curl https://typemark.dev/api/v1/projects/acme-docs \
  -H "Authorization: Bearer $TYPEMARK_TOKEN"
```

```json
{
  "project": {
    "id": "c1111111-1111-1111-1111-111111111111",
    "name": "Acme Docs",
    "slug": "acme-docs",
    "role": "owner",
    "locked": false,
    "repo_mode": "connected",
    "github_repo": "acme/docs",
    "deploy_mode": "auto",
    "deploy_status": "live",
    "site_status": "live",
    "url": "https://docs.acme.com",
    "editor_url": "https://typemark.dev/projects/acme-docs/editor",
    "last_deployed_at": "2026-11-16T09:58:41Z",
    "last_deploy_commit_sha": "4f2c9e1a7b3d5f6e8c0a1b2d3e4f5a6b7c8d9e0f",
    "updated_at": "2026-11-16T09:58:41Z",
    "pages_count": 24,
    "has_unpublished_changes": false,
    "last_deployment": {
      "id": "8d0c2f4e-5b6a-4c3d-9e8f-7a6b5c4d3e2f",
      "status": "success",
      "commit_sha": "4f2c9e1a7b3d5f6e8c0a1b2d3e4f5a6b7c8d9e0f",
      "commit_message": "docs: update quickstart.mdx",
      "commit_author": "Ada Lovelace",
      "pages_changed": 1,
      "build_duration_ms": 1840,
      "error_message": null,
      "created_at": "2026-11-16T09:58:39Z",
      "completed_at": "2026-11-16T09:58:41Z"
    }
  }
}
```

`GET /projects` returns the same fields for each project, without `pages_count`, `has_unpublished_changes`, and `last_deployment`.

### Create a project

```bash
curl https://typemark.dev/api/v1/projects \
  -H "Authorization: Bearer $TYPEMARK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Docs", "slug": "acme-docs" }'
```

Creates a project you own, the same as **New project** on the dashboard: a `typemark.json` and a few starter pages, with the site offline until you publish it. `slug` is optional; without it, one is made from the name. The answer is `201` with the project, in the same shape as `GET /projects/{slug}`.

| Status | Code | Meaning |
|--------|------|---------|
| `403` | `project_limit` | Your plan has no room for another project. The error adds `upgrade_url`. |
| `403` | `unconfirmed` | Confirm your email address first |
| `422` | `slug_taken` | Another project has that slug |
| `422` | `invalid` | The name is blank, or the slug isn't lowercase letters, numbers and hyphens or can't be used. The error adds `field`. |

<ResponseField name="role" type="string">
  Your role on the project: `owner`, `editor`, or `viewer`. See [Team members](https://docs.typemark.dev/team/members#roles).
</ResponseField>

<ResponseField name="locked" type="boolean">
  `true` when the project is read-only because the owner's plan doesn't cover it. See [Billing](https://docs.typemark.dev/team/billing).
</ResponseField>

<ResponseField name="repo_mode" type="string">
  `managed` when Typemark hosts the repository, `connected` when it syncs with GitHub. `github_repo` is set for connected projects.
</ResponseField>

<ResponseField name="deploy_mode" type="string">
  `auto` or `manual`. See [Publishing](https://docs.typemark.dev/configuration/publishing).
</ResponseField>

<ResponseField name="deploy_status" type="string">
  The latest build: `pending`, `building`, `live`, or `failed`.
</ResponseField>

<ResponseField name="site_status" type="string">
  `live` when readers can see the site, `offline` when it's hidden.
</ResponseField>

<ResponseField name="url" type="string">
  Where readers find the site: your custom domain once it's verified, otherwise `https://{slug}.typemark.dev`.
</ResponseField>

<ResponseField name="has_unpublished_changes" type="boolean">
  In manual deploy mode, `true` when there are edits that haven't been published yet.
</ResponseField>

### Deployments

Each publish of the site is a deployment. Pass `limit` to choose how many you get back: 20 by default, up to 100.

```bash
curl "https://typemark.dev/api/v1/projects/acme-docs/deployments?limit=1" \
  -H "Authorization: Bearer $TYPEMARK_TOKEN"
```

```json
{
  "deployments": [
    {
      "id": "8d0c2f4e-5b6a-4c3d-9e8f-7a6b5c4d3e2f",
      "status": "success",
      "commit_sha": "4f2c9e1a7b3d5f6e8c0a1b2d3e4f5a6b7c8d9e0f",
      "commit_message": "docs: update quickstart.mdx",
      "commit_author": "Ada Lovelace",
      "pages_changed": 1,
      "build_duration_ms": 1840,
      "error_message": null,
      "created_at": "2026-11-16T09:58:39Z",
      "completed_at": "2026-11-16T09:58:41Z"
    }
  ]
}
```

<ResponseField name="status" type="string">
  `pending`, `building`, `success`, or `failed`. When it's `failed`, `error_message` says why.
</ResponseField>

## Example: wait for a publish in CI

After pushing docs changes to GitHub, wait until Typemark has published them:

```bash
#!/usr/bin/env bash
set -euo pipefail

API="https://typemark.dev/api/v1/projects/acme-docs/deployments?limit=1"

for attempt in $(seq 1 30); do
  latest=$(curl -fsS "$API" -H "Authorization: Bearer $TYPEMARK_TOKEN")
  status=$(echo "$latest" | jq -r '.deployments[0].status')
  sha=$(echo "$latest" | jq -r '.deployments[0].commit_sha')

  if [ "$sha" = "$GITHUB_SHA" ] && [ "$status" = "success" ]; then
    echo "Published $sha"
    exit 0
  fi
  if [ "$sha" = "$GITHUB_SHA" ] && [ "$status" = "failed" ]; then
    echo "$latest" | jq -r '.deployments[0].error_message'
    exit 1
  fi
  sleep 5
done

echo "Timed out waiting for Typemark to publish $GITHUB_SHA"
exit 1
```

## Errors

Errors come back as JSON with a code you can check and a message you can show:

```json
{
  "error": {
    "code": "not_found",
    "message": "Not found."
  }
}
```

| Status | Code | Meaning |
|--------|------|---------|
| `400` | `bad_request` | A required parameter is missing |
| `401` | `unauthorized` | The token is missing, wrong, revoked, or expired |
| `403` | `forbidden` | Your role on the project doesn't allow this, for example a viewer pushing |
| `403` | `plan_limit` | The project owner's plan doesn't include this. The error adds `feature` and `upgrade_url`. |
| `403` | `project_limit` | Creating a project: your plan has no room for another one. The error adds `upgrade_url`. |
| `403` | `unconfirmed` | Creating a project: confirm your email address first |
| `404` | `not_found` | The project or deployment doesn't exist, or you aren't a member of the project |
| `409` | `conflict` | A push changes files that also changed on Typemark since `base_sha`. The error lists them in `conflicts`. |
| `409` | `stale_base` | A push is based on a commit Typemark doesn't have. Pull the project again, then push. |
| `409` | `connected_repo` | The project syncs with GitHub, so pushes go to GitHub instead |
| `409` | `busy` | Another change to the project is being saved. Try again in a moment. |
| `413` | `too_large` | A push is over the limits: 500 files, 10 MB per file, 50 MB per push, 100 MB per project. An OpenAPI spec over 10 MB. |
| `422` | `slug_taken`, `invalid` | Creating a project: the slug is taken, or the name or slug isn't valid (`field` says which) |
| `422` | `invalid_spec` | An OpenAPI spec that won't parse. The message says where. |
| `422` | `invalid_path` | A push names a path Typemark won't write: empty, starting with `/`, with a backslash, `.` or `..` in it, or inside `.git/` or `.typemark/` |
| `422` | `not_mintlify`, `not_gitbook`, `not_readme` | Migrating: the files don't look like a Mintlify config, a GitBook space, or a ReadMe project |
| `426` | `cli_outdated` | The Typemark CLI is too old for the API. The `hint` says how to update. Only requests that name a CLI version get it. |
| `429` | | Too many requests. Wait for the number of seconds in the `Retry-After` header. |
| `503` | `git_error` | The project's repository couldn't be read or written. Try again in a moment. |

## Limits

Each IP address can make 300 API requests a minute, including up to 30 pushes, 30 archive downloads, and 30 OpenAPI specs.
