API仕様

前提：このAPIを利用するには、先に API キーの発行 が必要です。以下の認証で使う ktk_... トークンは、その手順で取得します。

TOKIUM契約管理の公開APIは、すべて /api/v1 配下で提供されます。レスポンスは JSON です。

認証

すべてのリクエストに、発行した API キーを Bearer トークンとして付与します。

Authorization: Bearer ktk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json

• API キーは「ユーザー設定 > API キー」で発行します。
• 平文トークンは発行時に一度だけ表示され、サーバには SHA256 ハッシュのみが保存されます。
• キーは失効（revoke）・有効期限（expires_at）に対応しています。
• スコープは read（参照のみ）/ read_write（編集可）の2種類です。

権限の考え方 API キーは必ず発行ユーザーに紐づきます。API は画面と同一の権限ロジックを再利用するため、発行者が閲覧・編集できるフォルダの契約書だけが対象になります。権限のないフォルダ・他組織の契約書は、そもそもクエリに含まれません。

エンドポイント一覧

メソッド	パス	説明
GET	/api/v1/contracts	契約書の一覧・検索（絞り込み・ページネーション対応）
GET	/api/v1/contracts/:uuid	契約書を1件取得
PATCH	/api/v1/contracts/:uuid	契約書を編集（部分更新・編集権限が必要）
GET	/api/v1/folders	アクセス可能なフォルダ一覧（名前で部分一致絞り込み可）
GET	/api/v1/folders/search	フォルダ名の完全一致検索

契約書一覧・検索 — GET /api/v1/contracts

LLM/MCP は API が返した分しか見えないため、絞り込みはサーバ側で行います。目的の契約書に辿り着けるよう、以下のパラメータで件数を絞ってください。

パラメータ	型	説明
query	string	フリーテキスト検索（文書名・取引先名の部分一致）
status	enum	契約ステータスで絞り込み（下記参照）
folder_uuid	string	特定フォルダに限定（/folders で取得した uuid）
agreed_from	date	締結日の下限（YYYY-MM-DD）
agreed_to	date	締結日の上限（YYYY-MM-DD）
updated_since	datetime	この日時以降に更新された契約書のみ（ISO8601・増分取得向け）
page	integer	ページ番号（1始まり）
per_page	integer	1ページあたりの件数（最大 100・既定 50）

status に指定できる値

値	意味
uncontracted	未契約
pre_contracted	契約前
contracted	契約中
renewing	更新中
contract_ended	契約終了

リクエスト例

curl -H "Authorization: Bearer ktk_xxxx" \
     -H "Accept: application/json" \
     "https://contract.keihi.com/api/v1/contracts?query=業務委託&status=contracted&per_page=20"

契約書の取得 — GET /api/v1/contracts/:uuid

UUID を指定して契約書を1件取得します。権限のないフォルダの契約書は取得できません。

curl -H "Authorization: Bearer ktk_xxxx" \
     "https://contract.keihi.com/api/v1/contracts/3f2a...-uuid"

契約書の編集 — PATCH /api/v1/contracts/:uuid

指定したフィールドのみを部分更新します。対象フォルダの編集権限（read_write スコープ）が必要です。

フィールド	型	説明
document_name	string	書類名
other_party_name	string	取引先名
transaction_amount	number	取引金額
contract_start_date	date	契約開始日（YYYY-MM-DD）
contract_end_date	date	契約終了日（YYYY-MM-DD）
contract_agree_date	date	契約締結日（YYYY-MM-DD）

curl -X PATCH \
     -H "Authorization: Bearer ktk_xxxx" \
     -H "Content-Type: application/json" \
     -d '{"document_name":"業務委託契約書(改訂版)"}' \
     "https://contract.keihi.com/api/v1/contracts/3f2a...-uuid"

フォルダ一覧 — GET /api/v1/folders

アクセス可能なフォルダの uuid / name / folder_type / permission（editor / reader）を返します。契約書を絞り込む際の folder_uuid を決めるために使います。

パラメータ	型	説明
name	string	フォルダ名での部分一致絞り込み（任意）

返るのは発行者の権限スコープ内のフォルダのみで、権限のないフォルダは含まれません。

フォルダ検索 — GET /api/v1/folders/search

フォルダ名の完全一致で検索します。folder_uuid を正確に特定したいときに使います。同名フォルダが複数あれば複数返ります。

パラメータ	型	説明
name	string	フォルダ名（完全一致・必須）

エラー時のレスポンス

認証エラーや権限不足の場合、HTTP ステータスコード（401 / 403 / 404 など）とともにエラー内容が返ります。Bearer トークンが無い、もしくは失効・期限切れの場合は 401 になります。

契約書アップロード（PDF）は REST API（POST /api/v1/contracts）で提供されます。MCP 経由でのファイルアップロードは現時点で未対応です。