API リファレンス

Zapier 連携と自前の OAuth クライアント向けの API リファレンスです。 このページのリクエストには HTTPS と OAuth 2.0 アクセストークンによる Bearer 認証を使います。

認証（OAuth 2.0 + PKCE）#

認可コードフロー（Authorization Code Grant）に PKCE（S256）を組み合わせます。 取得したアクセストークンを各 API へ Authorization: Bearer <access_token> ヘッダーで送信します。

• GET /oauth/authorize — 認可リクエスト（同意画面へ誘導）
• POST /api/oauth/token — トークン取得・更新（application/x-www-form-urlencoded）
• GET /api/oauth/me — 接続テスト / 認証中ユーザーの確認
• POST /api/oauth/revoke — トークン失効

1. 認可リクエスト

GET https://typolish.com/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://your-app.example.com/callback
  &scope=projects:read proofs:read proofs:create webhooks:subscribe guest-links:reissue
  &state=RANDOM_STATE
  &code_challenge=BASE64URL_SHA256_OF_VERIFIER
  &code_challenge_method=S256

2. トークン取得

同意後にリダイレクトで受け取った code を、PKCE の code_verifier とともに交換します。クライアント認証は Basic 認証またはボディの client_id / client_secret の両対応です。

POST https://typolish.com/api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&redirect_uri=https://your-app.example.com/callback
&code_verifier=PKCE_CODE_VERIFIER

--- 200 OK ---
{
  "access_token": "toauth_xxxxxxxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "trefresh_xxxxxxxx",
  "scope": "projects:read proofs:read proofs:create webhooks:subscribe guest-links:reissue"
}

3. トークン更新

アクセストークンの有効期限は 3600 秒（1 時間）です。失効後は refresh_token で再取得します。

POST https://typolish.com/api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=trefresh_xxxxxxxx
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

スコープ#

必要最小限のスコープのみを要求してください。

• projects:read — プロジェクトの検索・読み取り
• proofs:read — プルーフの検索・読み取り
• proofs:create — プルーフの作成
• proofs:status — ステータス参照（将来のポーリング用・予約）
• webhooks:subscribe — Webhook（REST Hook）の購読・解除
• guest-links:reissue — ゲスト共有リンクの再発行

共通仕様#

• 認証: 全エンドポイントで Authorization: Bearer <access_token> 必須
• レートリミット: 成功応答に X-RateLimit-* ヘッダー。超過時は 429
• エラー形式: { "error", "error_description" } または { "error", "code" }
• 日時: createdAt 等は Unix ミリ秒、ゲストリンク期限は ISO 8601 文字列

エンドポイント#

プロジェクト検索

GET /api/v1/integrations/projects/search — scope projects:read。クエリ query（任意・名称の部分一致）。 認証ユーザーがメンバーのプロジェクトのみ返します。

GET https://typolish.com/api/v1/integrations/projects/search?query=brand
Authorization: Bearer toauth_xxxxxxxx

--- 200 OK ---
{
  "projects": [
    {
      "id": "proj_xyz789",
      "name": "Brand Site Renewal",
      "description": null,
      "ownerUid": "user_111",
      "createdAt": 1748736000000
    }
  ],
  "total": 1
}

プルーフ検索

GET /api/v1/integrations/proofs/search — scope proofs:read。クエリ projectId（任意・省略時は 参加プロジェクト横断で最新を取得）と query（任意・タイトル部分一致）。

GET https://typolish.com/api/v1/integrations/proofs/search?projectId=proj_xyz789&query=hero
Authorization: Bearer toauth_xxxxxxxx

--- 200 OK ---
{
  "proofs": [
    {
      "id": "proof_abc123",
      "title": "Hero banner v2",
      "projectId": "proj_xyz789",
      "type": "image",
      "approvalStatus": "pending",
      "currentVersionId": "ver_001",
      "createdBy": "user_111",
      "createdAt": 1748736000000,
      "updatedAt": 1748822400000
    }
  ],
  "total": 1
}

プルーフ作成

POST /api/v1/integrations/proofs — scope proofs:create。sourceUrl は公開アクセス可能な HTTPS URL（画像 / TIFF / PDF / Office / PSD / AI / HTML / 動画。ZIP は非対応）。ファイル転送は非同期のため 202 と status: "transferring" を返します。 作成者は対象プロジェクトの owner / editor である必要があります。暗号化プロジェクト（E2E）は 外部連携からプルーフを受け取れません。

POST https://typolish.com/api/v1/integrations/proofs
Authorization: Bearer toauth_xxxxxxxx
Content-Type: application/json

{
  "projectId": "proj_xyz789",
  "title": "Hero banner v2",
  "sourceUrl": "https://files.example.com/hero-v2.png"
}

--- 202 Accepted ---
{
  "proofId": "proof_abc123",
  "proofUrl": "https://typolish.com/projects/proj_xyz789/proofs/proof_abc123",
  "guestShareUrl": "https://typolish.com/g/123e4567-e89b-12d3-a456-426614174000",
  "guestShareExpiresAt": "2026-06-05T10:00:00.000Z",
  "status": "transferring",
  "proofs": [ { "proofId": "proof_abc123", "...": "..." } ]
}

ゲスト共有リンク再発行

POST /api/v1/integrations/reissue-guest-link — scope guest-links:reissue。指定プルーフのゲストリンクを再発行します （新リンクは 72 時間有効）。対象プロジェクトの現在の owner / editor のみ利用できます。 旧リンクは無効になります。閲覧者・非メンバーには 404、 暗号化プロジェクト（E2E）には 403 を返します。

POST https://typolish.com/api/v1/integrations/reissue-guest-link
Authorization: Bearer toauth_xxxxxxxx
Content-Type: application/json

{ "proofId": "proof_abc123" }

--- 200 OK ---
{
  "guestShareUrl": "https://typolish.com/g/223e4567-e89b-12d3-a456-426614174111",
  "guestShareExpiresAt": "2026-06-05T10:00:00.000Z"
}

Webhook 購読（REST Hook）

POST /api/v1/integrations/hooks — scope webhooks:subscribe。targetUrl は HTTPS 必須。 現在配信される event は proof.completed です。 返却された id が解除時のパスになります。

POST https://typolish.com/api/v1/integrations/hooks
Authorization: Bearer toauth_xxxxxxxx
Content-Type: application/json

{
  "targetUrl": "https://hooks.zapier.com/hooks/standard/...",
  "event": "proof.completed"
}

--- 201 Created ---
{
  "id": "hook_abc123",
  "event": "proof.completed",
  "targetUrl": "https://hooks.zapier.com/hooks/standard/...",
  "createdAt": 1748736000000
}

通知は、接続した本人が配信時にもメンバーである通常プロジェクトに限られます。 任意の eventFilter: { "projectId": "proj_xyz789" } を加えると、 指定した1プロジェクトだけを購読できます。省略または空オブジェクトは参加中の全通常プロジェクトが対象です。 指定先の権限がない場合や E2E の場合、購読登録は 403 になります。

Webhook 解除

DELETE /api/v1/integrations/hooks/{hookId} — scope webhooks:subscribe。冪等で、存在しない場合も 204 を返します。

DELETE https://typolish.com/api/v1/integrations/hooks/hook_abc123
Authorization: Bearer toauth_xxxxxxxx

--- 204 No Content ---

Webhook ペイロード#

proof.completed（承認 / 差し戻しの確定）の配信例です。 購読時の targetUrl へ POST されます。

POST <your targetUrl>
Content-Type: application/json

{
  "eventType": "proof.completed",
  "result": "approved",
  "proofId": "proof_abc123",
  "proofTitle": "Hero banner v2",
  "projectId": "proj_xyz789",
  "proofUrl": "https://typolish.com/projects/proj_xyz789/proofs/proof_abc123",
  "completedBy": "user_111",
  "completedByEmail": "reviewer@example.com",
  "completedAt": "2026-06-04T10:00:00.000Z",
  "rejectionReason": null
}

エラー#

• 400 — リクエスト不正（必須パラメータ欠落・URL 不正 等）
• 401 — アクセストークンが無効 / 期限切れ
• 403 — 権限なし（プロジェクト非メンバー・owner/editor 以外 等）
• 404 — 対象が存在しない
• 413 — 形式別のファイルサイズ上限超過（HTML 10MB、画像 / TIFF / Office 50MB、PDF / PSD / AI 100MB、動画 200MB）
• 422 — 上限到達（Webhook 購読数 等）
• 429 — レートリミット超過
• 500 — サーバーエラー