Typemark Documentation

Typemark API

APIトークンを作成し、スクリプトやCIからプロジェクトとパブリッシュを操作します。

2026年11月19日更新2分で読めます

Typemark APIを使うと、スクリプトやCIからプロジェクトとそのパブリッシュを読み取れます。たとえば、リリースを出す前にパブリッシュの完了を待つといった用途に使えます。すべてのプランで利用できます。

ターミナルやCIからドキュメントをダウンロード、編集、パブリッシュするには、Typemark CLIを使ってください。CLIはこのAPIの上に構築されており、同期や競合の処理を代わりに行います。

APIトークンを作成する

  1. アカウントを開く

    ダッシュボードのサイドバー下部にある自分の名前をクリックし、Accountを選択します。

  2. トークンに名前を付ける

    API tokensの下で、トークンの用途がわかる名前を入力します。例:GitHub Actions

  3. 有効期限を選ぶ

    30日、90日、1年、無期限から選択します。トークンが期限切れになると、それを使ったリクエストは動かなくなります。

  4. コピーする

    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では以前のプラン名を維持しています。

エンドポイント

MethodPathReturns
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/mintlifyMintlifyのdocs.jsonまたはmint.jsonをtypemark.jsonに変換します。typemark migrateで使用します。
POST/migrate/gitbook, /migrate/readmeGitBookのスペースまたはReadMeプロジェクトを、Typemarkのページとtypemark.jsonに変換します。typemark migrateで使用します。
POST/openapi/pagesOpenAPI仕様から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}と同じです。

StatusCodeMeaning
403project_limitプランでプロジェクトを追加できる上限に達しています。エラーにはupgrade_urlが含まれます。
403unconfirmed先にメールアドレスを確認してください
422slug_taken別のプロジェクトがそのslugを使用しています
422invalid名前が空である、またはslugが小文字の英字、数字、ハイフン以外を含む、または使用できない形式です。エラーにはfieldが含まれます。
rolestring

プロジェクトでのあなたの役割:owner、editor、viewerのいずれか。チームメンバーを参照してください。

lockedboolean

オーナーのプランがプロジェクトをカバーしていないため、読み取り専用になっている場合はtrue。請求を参照してください。

repo_modestring

Typemarkがリポジトリをホストしている場合はmanaged、GitHubと同期している場合はconnected。github_repoは接続されたプロジェクトで設定されます。

deploy_modestring

autoまたは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"
    }
  ]
}
statusstring

pending、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."
  }
}
StatusCodeMeaning
400bad_request必須のパラメータがありません
401unauthorizedトークンがない、誤っている、無効化されている、または期限切れです
403forbiddenプロジェクトでの役割がこの操作を許可していません。例:viewerがpushしようとした場合
403plan_limitプロジェクトのオーナーのプランにこの機能が含まれていません。エラーにはfeatureとupgrade_urlが含まれます。
403project_limitプロジェクト作成時:プランでプロジェクトを追加できる上限に達しています。エラーにはupgrade_urlが含まれます。
403unconfirmedプロジェクト作成時:先にメールアドレスを確認してください
404not_foundプロジェクトまたはデプロイメントが存在しない、またはあなたがそのプロジェクトのメンバーではありません
409conflictpushが、base_sha以降にTypemarkでも変更されたファイルを変更しています。エラーはconflictsにそれらを一覧表示します。
409stale_basepushの基になっているコミットをTypemarkが保持していません。プロジェクトを再度pullしてからpushしてください。
409connected_repoプロジェクトはGitHubと同期しているため、代わりにGitHubへpushしてください
409busyプロジェクトへの別の変更が保存中です。少し待ってから再試行してください。
413too_largepushが上限を超えています:500ファイル、ファイルあたり10 MB、1回のpushあたり50 MB、プロジェクトあたり100 MB。10 MBを超えるOpenAPI仕様も含みます。
422slug_taken, invalidプロジェクト作成時:slugが使用済みか、名前またはslugが無効です(fieldがどちらかを示します)
422invalid_spec解析できないOpenAPI仕様です。メッセージに場所が示されます。
422invalid_pathpushが、Typemarkが書き込めないパスを指定しています。空、/で始まる、バックスラッシュを含む、.または..を含む、.git/または.typemark/内にある、のいずれかです。
422not_mintlify, not_gitbook, not_readme移行時:ファイルがMintlifyの設定、GitBookのスペース、ReadMeプロジェクトのいずれにも見えません
426cli_outdatedTypemark CLIがAPIに対して古すぎます。hintに更新方法が示されます。CLIのバージョンを指定したリクエストにのみ返されます。
429リクエストが多すぎます。Retry-Afterヘッダーに示された秒数だけ待ってください。
503git_errorプロジェクトのリポジトリを読み書きできませんでした。少し待ってから再試行してください。

制限

各IPアドレスは1分あたり300回までAPIリクエストを送信できます。内訳は、pushが最大30回、アーカイブのダウンロードが最大30回、OpenAPI仕様が最大30回を含みます。