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
Open your account
Click your name at the bottom of the dashboard sidebar, then Account.
Name the token
Under API tokens, give the token a name that says where it's used, like
GitHub Actions.Choose when it expires
Pick 30 days, 90 days, a year, or never. When a token expires, requests with it stop working.
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
| 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
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}.
| 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. |
rolestringYour role on the project: owner, editor, or viewer. See Team members.
lockedbooleantrue when the project is read-only because the owner's plan doesn't cover it. See Billing.
repo_modestringmanaged when Typemark hosts the repository, connected when it syncs with GitHub. github_repo is set for connected projects.
deploy_modestringauto or manual. See Publishing.
deploy_statusstringThe latest build: pending, building, live, or failed.
site_statusstringlive when readers can see the site, offline when it's hidden.
urlstringWhere readers find the site: your custom domain once it's verified, otherwise https://{slug}.typemark.dev.
has_unpublished_changesbooleanIn 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"
}
]
}
statusstringpending, 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."
}
}
| 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.