レンダリング API

ベース URL: https://composepdf.com

OpenAPI 仕様

このページのエンドポイントは OpenAPI 3.1 のドキュメントとして https://composepdf.com/v1/openapi.json で配信しています。キーは要りません。ジェネレータに読ませて型のついたクライアントを起こす、API ツールに取り込む、あるいは文章を読まずに API を叩くエージェントにそのまま渡す、といった使い方です。

仕様が記述するのは外枠 —— パス・認証・ヘッダ・エラーです。個々のテンプレートが data に何を求めるかは、テンプレートごとのデータスキーマが別に答えます。

認証

API キーを毎回のリクエストに載せます。どちらの形でも構いません。

-H "x-api-key: $COMPOSEPDF_API_KEY"        # 主
-H "Authorization: Bearer $COMPOSEPDF_API_KEY"  # こちらも受け付けます

キーは設定 → API キーで発行し、ワークスペースに限定できます。未知のキー・失効したキー・スコープ外のリソースは、すべて 404 を返します。 API はスコープの外に何が存在するかを明かしません。

エンドポイント

メソッド	パス	用途
`GET`	`/v1/openapi.json`	この面の OpenAPI 3.1 仕様(キー不要)
`GET`	`/v1/health`	死活確認
`GET`	`/v1/canvases`	キーのスコープ内で公開済みのキャンバス一覧
`POST`	`/v1/canvases/{canvasId}/pdf`	公開バージョンを PDF に描く
`GET`	`/v1/canvases/{canvasId}/schema`	テンプレートのデータスキーマ
`GET`	`/v1/renders`	直近のレンダリング一覧
`GET`	`/v1/renders/{renderId}`	レンダリングの状態(非同期ジョブを含む)
`GET`	`/v1/renders/{renderId}/pdf`	保存したレンダリングのダウンロード
`GET`	`/v1/usage`	キーが属する組織の当期の利用量

レンダリング

POST /v1/canvases/{canvasId}/pdf
content-type: application/json

{ "data": { … } }

公開バージョンが data とともに描かれ、応答の本体が PDF になります。レンダリングに使われるのは常に凍結された公開バージョンで、下書きに API から届くことはありません。

リクエストボディ

フィールド	型	備考
`data`	object	ペイロード。レイアウトの前にテンプレートの宣言変数と照合されます。
`dataList`	array	`data` と排他です。下を参照してください。
`options.store`	boolean	PDF を保存し、あとから `GET /v1/renders/{id}/pdf` でダウンロードできるようにします。
`options.password`	string	出力を暗号化します(暗号化ポリシーを宣言したテンプレートのみ)。パスワードは保存されません。
`options.createdAt`	string	文書の作成日。ISO 8601、UTC(`"2026-08-13T09:30:00Z"`)。省略すると 2000-01-01T00:00:00Z 固定になります — エンジンは時計を読まないので、同じ入力からは同じバイトが出ます。

多数のレコードを1ファイルに

綴じた複数文書の PDF を作る方法は2つあります。

dataList — ペイロードの配列(1リクエストにつき最大100件)。各要素がそれぞれ検証され、1つの文書として描かれ、まとめて1ファイルに綴じられます。スキーマ違反はレコードを名指しします: dataList[3].customer.name。
レコードテンプレート — レコード源を宣言したテンプレート(たとえば customers の1要素につき請求書1通)は、件数を自分で決めます。data オブジェクトを1つ POST すればテンプレート側が展開します。レコード件数は x-rspdf-records 応答ヘッダーで返ります。

ページ数はレンダリングごとにサーバー側で記録され、 GET /v1/renders/{renderId} の pages で読めます。月の枠 (GET /v1/usage)が数えるのはページではなくレコード数です — 100件の dataList は 100 消費します。

非同期レンダリング

同期リクエストには約25秒のレンダリング予算があります。重いジョブでは非同期処理を要求してください。

POST /v1/canvases/{canvasId}/pdf
Prefer: respond-async

ジョブ id つきの 202 Accepted が返ります。GET /v1/renders/{id} を状態が終端になるまでポーリングし、GET /v1/renders/{id}/pdf からダウンロードします。

Idempotency-Key ヘッダーを送ると再試行が安全になります。バイト列が既にあるキーを再送した場合は、その場で 200 が返ります。
再送かどうかを決めるのはキーだけで、data は判定に入りません。 バイト列が既にあるキーを、同じ canvas・同じ APIキーで送ると、本文を変えていてもそのバイト列が返ります (X-Rspdf-Replayed: 1)。409 になるのは、同じキーを別の canvas や別の APIキーで使い回した場合です。したがって「同じ帳票を値だけ直して刷り直す」には、値と一緒に変わるキーが要ります — ヘッダーを付けないか、刷るたびに変わるものからキーを作ってください。キーが向くのは「二度課金されたくない再試行」(発行レコード1件の再送など)であって、値を変えてまた実行する呼び出しではありません。
非同期ジョブでは options.password は拒否されます(400)。暗号化の秘密は保存しない方針で、非同期ジョブはそれを保存せざるを得ないためです。

エラー

ステータス	意味
`400`	ペイロードがデータスキーマに違反しています。本体に違反したパスが列挙されます。
`402`	組織のプランがこの呼び出しを許していません(たとえば Free プランには API がありません)。
`404`	未知のキャンバス、公開バージョンが無い、またはキーのスコープ外です。
`413`	プランの毎分予算に対してリクエストが大きすぎる、`dataList` が100件を超えた、または出力が上限を超えました。再試行しても通りません。
`429`	レート制限。`Retry-After` に従ってください。

レートと同時実行の上限は組織ごとで、プランに応じて上がります。実際の消費量は設定 → 使用状況と GET /v1/usage で見られます。