Typemark Documentation

Typemark API

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

Updated Nov 19, 20265 min read

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. It's built on this API and handles syncing and conflicts for you.

Create an API token

  1. Open your account

    Click your name at the bottom of the dashboard sidebar, then Account.

  2. Name the token

    Under API tokens, give the token a name that says where it's used, like GitHub Actions.

  3. Choose when it expires

    Pick 30 days, 90 days, a year, or never. When a token expires, requests with it stop working.

  4. Copy it

    Click Create token and copy the token. It starts with tmk_.

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.

curl https://typemark.dev/api/v1/user \
  -H "Authorization: Bearer $TYPEMARK_TOKEN"
{
  "user": {
    "id": "6945f00a-3d8a-4609-8dd8-eb4c1aa3fbab",
    "name": "Ada Lovelace",
    "email": "[email protected]",
    "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

MethodPathReturns
GET/userThe token's user, their plan, and the token itself
GET/projectsEvery project you own or are a member of
GET/projects/{slug}One project, with its page count and latest publish
POST/projectsCreates a project. Used by typemark create.
GET/projects/{slug}/deploymentsRecent publishes, newest first
GET/projects/{slug}/deployments/{id}One publish
GET/projects/{slug}/filesEvery file in the project, with its Git blob id, and the commit they're from
GET/projects/{slug}/archiveThe project's files as a .tar.gz. Pass sha for a specific commit.
POST/projects/{slug}/pushChanges, adds, or deletes files as one commit, then publishes. Used by typemark push.
POST/migrate/mintlifyConverts a Mintlify docs.json or mint.json into typemark.json. Used by typemark migrate.
POST/migrate/gitbook, /migrate/readmeConverts a GitBook space or a ReadMe project into Typemark pages and typemark.json. Used by typemark migrate.
POST/openapi/pagesThe 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/tokenRevokes the token that sent the request

Projects

curl https://typemark.dev/api/v1/projects/acme-docs \
  -H "Authorization: Bearer $TYPEMARK_TOKEN"
{
  "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

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

StatusCodeMeaning
403project_limitYour plan has no room for another project. The error adds upgrade_url.
403unconfirmedConfirm your email address first
422slug_takenAnother project has that slug
422invalidThe name is blank, or the slug isn't lowercase letters, numbers and hyphens or can't be used. The error adds field.
rolestring

Your role on the project: owner, editor, or viewer. See Team members.

lockedboolean

true when the project is read-only because the owner's plan doesn't cover it. See Billing.

repo_modestring

managed when Typemark hosts the repository, connected when it syncs with GitHub. github_repo is set for connected projects.

deploy_modestring

auto or manual. See Publishing.

deploy_statusstring

The latest build: pending, building, live, or failed.

site_statusstring

live when readers can see the site, offline when it's hidden.

urlstring

Where readers find the site: your custom domain once it's verified, otherwise https://{slug}.typemark.dev.

has_unpublished_changesboolean

In manual deploy mode, true when there are edits that haven't been published yet.

Deployments

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

curl "https://typemark.dev/api/v1/projects/acme-docs/deployments?limit=1" \
  -H "Authorization: Bearer $TYPEMARK_TOKEN"
{
  "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"
    }
  ]
}
statusstring

pending, building, success, or failed. When it's failed, error_message says why.

Example: wait for a publish in CI

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

#!/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:

{
  "error": {
    "code": "not_found",
    "message": "Not found."
  }
}
StatusCodeMeaning
400bad_requestA required parameter is missing
401unauthorizedThe token is missing, wrong, revoked, or expired
403forbiddenYour role on the project doesn't allow this, for example a viewer pushing
403plan_limitThe project owner's plan doesn't include this. The error adds feature and upgrade_url.
403project_limitCreating a project: your plan has no room for another one. The error adds upgrade_url.
403unconfirmedCreating a project: confirm your email address first
404not_foundThe project or deployment doesn't exist, or you aren't a member of the project
409conflictA push changes files that also changed on Typemark since base_sha. The error lists them in conflicts.
409stale_baseA push is based on a commit Typemark doesn't have. Pull the project again, then push.
409connected_repoThe project syncs with GitHub, so pushes go to GitHub instead
409busyAnother change to the project is being saved. Try again in a moment.
413too_largeA 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.
422slug_taken, invalidCreating a project: the slug is taken, or the name or slug isn't valid (field says which)
422invalid_specAn OpenAPI spec that won't parse. The message says where.
422invalid_pathA push names a path Typemark won't write: empty, starting with /, with a backslash, . or .. in it, or inside .git/ or .typemark/
422not_mintlify, not_gitbook, not_readmeMigrating: the files don't look like a Mintlify config, a GitBook space, or a ReadMe project
426cli_outdatedThe Typemark CLI is too old for the API. The hint says how to update. Only requests that name a CLI version get it.
429Too many requests. Wait for the number of seconds in the Retry-After header.
503git_errorThe 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.