Overview 1 分で読めます

開発者向け PaperOffice API：完全ガイド

仕様の所在

エンドポイント仕様は API カタログからリアルタイムで生成されます。記事からエンドポイントリストをコピーするのではなく、以下のファイルを使用してください：

  • AI クライアント用コンパクトインデックス：https://api.paperoffice.ai/latest/docs/llms.txt
  • 完全リファレンス：https://api.paperoffice.ai/latest/docs/llms-full.txt
  • OpenAPI 3.1：https://api.paperoffice.ai/latest/docs/openapi.json
  • エージェントスキル：https://api.paperoffice.ai/latest/docs/skill.md
  • Postman コレクション：https://api.paperoffice.ai/latest/docs/postman

ドキュメントルートは公開されており、トークンは不要です。Postman URL を Postman、VS Code、または Bruno にインポートし、ドキュメントのリリースが変更された際に再度ダウンロードしてください。本番環境のベースアドレスは https://api.paperoffice.ai/latest です。/dev は開発環境でのみ使用してください。

AI コーディングアシスタントとのクイックスタート：llms-full.txt のアドレスをアシスタントに渡し、画像を送信して認識されたテキストを返す関数など、必要な機能について説明します。

認証とトークンの種類

ほとんどの製品エンドポイントでは、Authorization ヘッダーにベアラートークンが必要です。トークンは PaperOffice アプリの アカウント → API で作成します。

  • システムキー (po_sk_)：フル API アクセスを持つサーバー間統合用。ブラウザで使用しないでください。
  • ユーザートークン (po_ut_)：単一ユーザーのスコープ（例：MCP 用）。権限はユーザーとライセンスに従います。
  • グループトークン (po_gt_)：ユーザーグループの権限とワークスペースホワイトリストを継承します。
  • 公開可能キー (po_pk_)：ブラウザでの使用用。すべてのリクエストには、キー所有者が入力したオリジンが必要です。ライフタイム予算で消費を制限し、削除、アカウント管理、キー管理、支払い変更はブロックされます。MCP では許可されていません。

トークンがない場合、仕様、ヘルスチェック、接続テストなどのインフラストラクチャエンドポイントのみが利用可能です。トークンなしの製品リクエストには HTTP 403 とコード TIER_RESTRICTED が返され、HTTP 401 は返されません。

ジョブ：待機、ポーリング、結果

処理はジョブとして実行されます。ジョブパスは handler___command のパターン（アンダースコア3つ）を使用します。例：テキスト認識用 POST /job/add/paperoffice_aiocr___generate。ドット表記は JOB_CONFIG_INVALID で拒否されます。

  • デフォルトでは、リクエストは一定時間接続を保持します。ジョブが時間内に完了すれば、結果が直接返されます。そうでない場合は、ジョブ ID とポーリングアドレスを含む HTTP 202 が返され、ジョブは実行を続けます。
  • HTTP 202 はエラーではなく成功です。ステータスが完了するまで GET /job/get/{job_id} を 5〜10 秒ごとにポーリングしてください。結果は job_result に格納されます。
  • client_wait=false を指定すると、すぐにジョブ ID が返され、最初からポーリングできます。
  • すべてのレスポンスは JSON です。クライアントはローカライズされたメッセージテキストではなく、安定したコードフィールドを読み取るべきです。

アカウント → API → ジョブキュー で、キューイング中、実行中、完了した API ジョブを確認できます。エラーコードの完全なリストは仕様書に記載されています。一般的なケースには、不足または無効なパラメータ（400）、不足または無効なトークン（401）、Credits の不足（402）、禁止されたアクション（403）、およびリクエスト過多（429、Retry-After を尊重）があります。

開始 SLA：ジョブの開始タイミング

オプションフィールド processing_lane は、ジョブが完了するタイミングではなく、キューでいつ開始されるかを制御します。client_wait は接続が結果を待機するかどうかを制御し、この2つのフィールドは独立しています。

processing_lane を指定しない場合、ワークスペースのデフォルトが適用され、それ以外はベストエフォートとなります。すべてのプランに追加料金なしでベストエフォートが含まれています。より高速な開始レーンはオプションであり、追加料金がかかります。現在のレーンとその価格は API 価格リストを通じてリアルタイムで利用可能です。詳細は API ドキュメントをご覧ください。

Webhook

Webhook エンドポイントはジョブおよびアカウントイベント（例：job.completed、job.failed、job.progress、ドキュメント/ワークスペース/タスクのイベント）を受け取ります。残高ゼロのウォレットやキーの取り消しなどのアカウント通知は Webhook イベントではありません。

  • ペイロードは、X-Paperoffice-Signatureヘッダー内でHMAC-SHA256を使用して署名されます。Webhookシークレットを使用して生リクエストボディに対して署名を計算し、一致しない場合はリクエストを拒否してください。
  • Webhookの登録、一覧表示、更新、テスト、削除はAPIを通じて行われます。

請求と使用状況

API呼び出しは、アプリケーションと同じ共有プールからCreditsを消費します。一部のステータスやヘルスチェックのクエリには課金されません。詳細はAPIドキュメントをご覧ください。無効な入力により拒否された呼び出しも課金対象となりますが、レート制限により拒否された呼び出しは課金されません。

API & 開発者 → API 使用状況で、Creditsを含む呼び出しを確認できます：ライブログには各リクエストが表示され、履歴には日付、ハンドラー、アクション別の使用状況が表示されます。Creditsが枯渇すると、残高のチャージまたは自動補充が行われるまで呼び出しは拒否されます。レート制限はプランによって異なります。現在の制限とレスポンスヘッダーについてはAPIドキュメントをご覧ください。Creditsの詳細: PaperOffice AIにおける請求とCredits。

MCP: AIアシスタントの接続

MCPは、Claude、ChatGPT、Grok、およびCursorなどのAIアシスタントをPaperOfficeに直接接続します。認証にはOAuth 2.1またはユーザー/グループトークンを使用します。システムキーや公開可能キーはMCPではブロックされます。本番環境のホストはhttps://mcp.paperoffice.aiで、/claude、/chatgpt、/grok、/cursor、/dmsなどのプロファイルがあります。セットアップ、権限、データフローについては: Claude、ChatGPT、Grok、およびCursorでPaperOfficeを使用する。

よくある質問

  • すべてのエンドポイントはどこにありますか？llms.txt、llms-full.txt、およびOpenAPIファイルにあります。これらはリアルタイムで生成されます。
  • サーバーはどのトークンを使用すべきですか？システムキーです。ブラウザでは使用しないでください。ブラウザの場合は、オリジンと予算付きの公開可能キーを使用してください。
  • HTTP 202はエラーですか？いいえ。ジョブはまだ実行中ですので、結果をポーリングしてください。
  • 高速起動レーンは追加料金がかかりますか？はい。ベストエフォートには追加料金はかかりません。現在の価格はAPI価格表をご覧ください。
  • 拒否された呼び出しは課金されますか？無効な入力により拒否された呼び出しは課金対象となりますが、レート制限により拒否された呼び出しは課金されません。