Typemark API
APIトークンを作成し、スクリプトやCIからプロジェクトとパブリッシュを操作します。
2026年11月19日更新2分で読めます
Typemark APIを使うと、スクリプトやCIからプロジェクトとそのパブリッシュを読み取れます。たとえば、リリースを出す前にパブリッシュの完了を待つといった用途に使えます。すべてのプランで利用できます。
ターミナルやCIからドキュメントをダウンロード、編集、パブリッシュするには、Typemark CLIを使ってください。CLIはこのAPIの上に構築されており、同期や競合の処理を代わりに行います。
APIトークンを作成する
アカウントを開く
ダッシュボードのサイドバー下部にある自分の名前をクリックし、Accountを選択します。
トークンに名前を付ける
API tokensの下で、トークンの用途がわかる名前を入力します。例:
GitHub Actions有効期限を選ぶ
30日、90日、1年、無期限から選択します。トークンが期限切れになると、それを使ったリクエストは動かなくなります。
コピーする
Create tokenをクリックし、トークンをコピーします。トークンは
tmk_で始まります。
トークンはあなたとして動作します。所有している、またはメンバーになっているすべてのプロジェクトを、それぞれでのあなたの役割に応じて読み取れます。コードや公開された場所には含めないでください。
トークンを無効化する
Accountページでトークンの横にあるRevokeをクリックします。そのトークンを使っている処理はすぐに動かなくなります。一覧には各トークンの最終使用日時が表示されるので、不要になったものを見つけられます。
リクエストを送信する
トークンはAuthorizationヘッダーで送信します。すべてのエンドポイントは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はfree、pro、businessのいずれかです。businessはEnterpriseプランのことです。プランを確認するスクリプトが動き続けるよう、APIでは以前のプラン名を維持しています。
エンドポイント
| Method | Path | Returns |
|---|---|---|
GET | /user | トークンのユーザー、そのプラン、トークン自体 |
GET | /projects | 所有している、またはメンバーになっているすべてのプロジェクト |
GET | /projects/{slug} | 1つのプロジェクト(ページ数と最新のパブリッシュを含む) |
POST | /projects | プロジェクトを作成します。typemark createで使用します。 |
GET | /projects/{slug}/deployments | 最近のパブリッシュ(新しい順) |
GET | /projects/{slug}/deployments/{id} | 1件のパブリッシュ |
GET | /projects/{slug}/files | プロジェクト内のすべてのファイル(Git blob ID と、それらが属するコミットを含む) |
GET | /projects/{slug}/archive | プロジェクトのファイルを.tar.gzで取得します。特定のコミットを指定するにはshaを渡します。 |
POST | /projects/{slug}/push | ファイルの変更、追加、削除を1つのコミットとしてまとめ、その後パブリッシュします。typemark pushで使用します。 |
POST | /migrate/mintlify | Mintlifyのdocs.jsonまたはmint.jsonをtypemark.jsonに変換します。typemark migrateで使用します。 |
POST | /migrate/gitbook, /migrate/readme | GitBookのスペースまたはReadMeプロジェクトを、Typemarkのページとtypemark.jsonに変換します。typemark migrateで使用します。 |
POST | /openapi/pages | OpenAPI仕様からTypemarkが生成するページ。source(typemark.json内のパス)、content(その本文)、groupを送信します。typemark devで使用します。何も保存されません。 |
DELETE | /token | このリクエストに使われたトークンを無効化します |
プロジェクト
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は、各プロジェクトについて同じフィールドを返します。ただしpages_count、has_unpublished_changes、last_deploymentは含まれません。
プロジェクトを作成する
curl https://typemark.dev/api/v1/projects \
-H "Authorization: Bearer $TYPEMARK_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "name": "Acme Docs", "slug": "acme-docs" }'
ダッシュボードのNew projectと同じく、あなたが所有するプロジェクトを作成します。typemark.jsonと数ページのスターターページが作られ、パブリッシュするまでサイトはオフラインのままです。slugは省略可能です。省略した場合は名前から生成されます。成功すると201とプロジェクトが返ります。形式はGET /projects/{slug}と同じです。
| Status | Code | Meaning |
|---|---|---|
403 | project_limit | プランでプロジェクトを追加できる上限に達しています。エラーにはupgrade_urlが含まれます。 |
403 | unconfirmed | 先にメールアドレスを確認してください |
422 | slug_taken | 別のプロジェクトがそのslugを使用しています |
422 | invalid | 名前が空である、またはslugが小文字の英字、数字、ハイフン以外を含む、または使用できない形式です。エラーにはfieldが含まれます。 |
rolestringプロジェクトでのあなたの役割:owner、editor、viewerのいずれか。チームメンバーを参照してください。
lockedbooleanオーナーのプランがプロジェクトをカバーしていないため、読み取り専用になっている場合はtrue。請求を参照してください。
repo_modestringTypemarkがリポジトリをホストしている場合はmanaged、GitHubと同期している場合はconnected。github_repoは接続されたプロジェクトで設定されます。
deploy_modestringautoまたはmanual。パブリッシュを参照してください。
deploy_statusstring最新のビルドの状態:pending、building、live、failedのいずれか。
site_statusstring読者がサイトを見られる場合はlive、非表示の場合はoffline。
urlstring読者がサイトにアクセスする先。カスタムドメインが確認済みならそのドメイン、そうでなければhttps://{slug}.typemark.dev。
has_unpublished_changesboolean手動デプロイモードで、まだパブリッシュされていない編集がある場合はtrue。
デプロイメント
サイトのパブリッシュはそれぞれデプロイメントになります。limitを渡すと取得件数を指定できます。デフォルトは20件、最大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、failedのいずれか。failedの場合、理由はerror_messageに示されます。
例:CIでパブリッシュの完了を待つ
ドキュメントの変更をGitHubにpushした後、Typemarkがパブリッシュするまで待ちます。
#!/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
エラー
エラーは、確認できるコードと表示できるメッセージを含むJSONで返されます。
{
"error": {
"code": "not_found",
"message": "Not found."
}
}
| Status | Code | Meaning |
|---|---|---|
400 | bad_request | 必須のパラメータがありません |
401 | unauthorized | トークンがない、誤っている、無効化されている、または期限切れです |
403 | forbidden | プロジェクトでの役割がこの操作を許可していません。例:viewerがpushしようとした場合 |
403 | plan_limit | プロジェクトのオーナーのプランにこの機能が含まれていません。エラーにはfeatureとupgrade_urlが含まれます。 |
403 | project_limit | プロジェクト作成時:プランでプロジェクトを追加できる上限に達しています。エラーにはupgrade_urlが含まれます。 |
403 | unconfirmed | プロジェクト作成時:先にメールアドレスを確認してください |
404 | not_found | プロジェクトまたはデプロイメントが存在しない、またはあなたがそのプロジェクトのメンバーではありません |
409 | conflict | pushが、base_sha以降にTypemarkでも変更されたファイルを変更しています。エラーはconflictsにそれらを一覧表示します。 |
409 | stale_base | pushの基になっているコミットをTypemarkが保持していません。プロジェクトを再度pullしてからpushしてください。 |
409 | connected_repo | プロジェクトはGitHubと同期しているため、代わりにGitHubへpushしてください |
409 | busy | プロジェクトへの別の変更が保存中です。少し待ってから再試行してください。 |
413 | too_large | pushが上限を超えています:500ファイル、ファイルあたり10 MB、1回のpushあたり50 MB、プロジェクトあたり100 MB。10 MBを超えるOpenAPI仕様も含みます。 |
422 | slug_taken, invalid | プロジェクト作成時:slugが使用済みか、名前またはslugが無効です(fieldがどちらかを示します) |
422 | invalid_spec | 解析できないOpenAPI仕様です。メッセージに場所が示されます。 |
422 | invalid_path | pushが、Typemarkが書き込めないパスを指定しています。空、/で始まる、バックスラッシュを含む、.または..を含む、.git/または.typemark/内にある、のいずれかです。 |
422 | not_mintlify, not_gitbook, not_readme | 移行時:ファイルがMintlifyの設定、GitBookのスペース、ReadMeプロジェクトのいずれにも見えません |
426 | cli_outdated | Typemark CLIがAPIに対して古すぎます。hintに更新方法が示されます。CLIのバージョンを指定したリクエストにのみ返されます。 |
429 | リクエストが多すぎます。Retry-Afterヘッダーに示された秒数だけ待ってください。 | |
503 | git_error | プロジェクトのリポジトリを読み書きできませんでした。少し待ってから再試行してください。 |
制限
各IPアドレスは1分あたり300回までAPIリクエストを送信できます。内訳は、pushが最大30回、アーカイブのダウンロードが最大30回、OpenAPI仕様が最大30回を含みます。