API reference

Documents

Document originals and versions, scanning, full-text search and extraction review.

Generated from the public API contract (OpenAPI). Descriptions in the contract are written in Japanese.

Endpoints


GET	`/v1/documents/sources`
GET	`/v1/documents/sources/{name}`
GET	`/v1/documents/sources/{name}/items`
POST	`/v1/documents/sources/{name}/sync`
POST	`/v1/documents/upload-sessions`
PUT	`/v1/documents/upload-sessions/{id}/content`
POST	`/v1/documents/upload-sessions/{id}/complete`
GET	`/v1/documents`
POST	`/v1/documents/search`
GET	`/v1/documents/{id}`
DELETE	`/v1/documents/{id}`
GET	`/v1/documents/{id}/disposal`
PUT	`/v1/documents/{id}/hold`
DELETE	`/v1/documents/{id}/hold`
POST	`/v1/documents/upload-sessions/{id}/expand`
POST	`/v1/documents/inbound-mail`
GET	`/v1/documents/intake-address`
GET	`/v1/documents/by-record/{recordId}`
POST	`/v1/documents/relations/{id}/confirm`
POST	`/v1/documents/relations/{id}/reject`
GET	`/v1/documents/{id}/versions/{version}/placement`
PUT	`/v1/documents/{id}/versions/{version}/links/{linkId}`
GET	`/v1/documents/{id}/receipts`
GET	`/v1/documents/{id}/versions/{version}/classification`
PUT	`/v1/documents/{id}/versions/{version}/classification`
GET	`/v1/documents/search-index`
POST	`/v1/documents/search-index/rebuild`
POST	`/v1/documents/search-index/reindex`
POST	`/v1/documents/search-index/{generation}/activate`
POST	`/v1/documents/search-index/{generation}/discard`
GET	`/v1/documents/facts`
GET	`/v1/documents/facts/stats`
GET	`/v1/documents/eval-set/candidates`
GET	`/v1/documents/eval-set/cases`
POST	`/v1/documents/eval-set/cases`
GET	`/v1/documents/eval-set/cases/{id}`
DELETE	`/v1/documents/eval-set/cases/{id}`
POST	`/v1/documents/eval-set/cases/{id}/approve`
GET	`/v1/documents/eval-set/comparisons`
POST	`/v1/documents/eval-set/comparisons`
GET	`/v1/documents/{id}/versions`
GET	`/v1/documents/{id}/versions/{version}`
GET	`/v1/documents/{id}/versions/{version}/content`
GET	`/v1/documents/{id}/versions/{version}/rendition`
POST	`/v1/documents/{id}/versions/{version}/reindex`
GET	`/v1/documents/{id}/versions/{version}/pages`
GET	`/v1/documents/{id}/versions/{version}/summary`
GET	`/v1/documents/{id}/versions/{version}/facts`
GET	`/v1/documents/{id}/versions/{version}/extraction-runs`
POST	`/v1/documents/{id}/versions/{version}/extractions`
POST	`/v1/documents/facts/{id}/confirm`
POST	`/v1/documents/facts/{id}/reject`
POST	`/v1/documents/facts/{id}/inquire`
GET	`/v1/documents/{id}/versions/{version}/inspection`
POST	`/v1/documents/{id}/versions/{version}/inspection/retry`

listDocumentSources

GET/v1/documents/sources

documents:read が必要。外部の保管場所との同期（DocumentSource）と、最後の結果を返す

Responses

200 — object: 同期の一覧
default — Problem: RFC 9457 Problem Details

getDocumentSource

GET/v1/documents/sources/{name}

documents:read が必要

Parameters

Name	In	Type	Required	Description
`name`	path	string	yes

Responses

200 — DocumentSourceStatus: 同期の状態
default — Problem: RFC 9457 Problem Details

listDocumentSourceItems

GET/v1/documents/sources/{name}/items

documents:read が必要。外部のファイルと、対応する文書、同期の状態を返す

Parameters

Name	In	Type	Required
`name`	path	string	yes
`limit`	query	integer
`cursor`	query	string

Responses

200 — object: 外部のファイルの一覧
default — Problem: RFC 9457 Problem Details

syncDocumentSource

POST/v1/documents/sources/{name}/sync

documents:write が必要。間隔を待たずに同期を始める。full を付けると対象の全体を読み直す。同期の途中なら 409

Parameters

Name	In	Type	Required	Description
`Idempotency-Key`	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる
`name`	path	string	yes

Request body

application/json

Name	Type	Required	Description
`full`	boolean

Responses

202 — DocumentSourceStatus: 同期を受け付けた
default — Problem: RFC 9457 Problem Details

createDocumentUploadSession

POST/v1/documents/upload-sessions

documents:write が必要。既定の公開範囲は本人だけ。10 MiB 以下の PDF と UTF-8 のテキストを受け付ける

Parameters

Name	In	Type	Required	Description
`Idempotency-Key`	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

Request body

application/json — DocumentUploadInput

Name	Type	Required	Description
`filename`	string	yes
`content_type`	`application/pdf` \| `text/plain` \| `application/vnd.openxmlformats-officedocument.wordprocessingml.document` \| `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` \| `application/vnd.openxmlformats-officedocument.presentationml.presentation` \| `application/msword` \| `application/vnd.ms-excel` \| `application/vnd.ms-powerpoint` \| `application/zip`	yes	application/zip は complete ではなく expand で展開する。document_id と一緒に使えない。Office の書類は原本のまま保管し、索引と抽出には PDF に変えて使う
`size`	integer	yes
`sha256`	string	yes
`title`	string
`document_id`	string		既存の文書へ新しいバージョンを足すときに指定する
`visibility`	`private` \| `project`

Responses

201 — DocumentUploadSession: アップロードの準備。upload_path への送信にも同じ認証が必要
default — Problem: RFC 9457 Problem Details

uploadDocumentContent

PUT/v1/documents/upload-sessions/{id}/content

documents:write と準備した本人の権限が必要。Content-Type は準備で指定した content_type と一致させ、確定前の隔離領域へ原本を送る

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes

Request body

application/pdf

Responses

200 — DocumentUploadSession: 受領した原本
default — Problem: RFC 9457 Problem Details

completeDocumentUpload

POST/v1/documents/upload-sessions/{id}/complete

documents:write が必要。実物のサイズ・SHA-256・形式を確かめて原本とバージョンを保存し、非同期のマルウェア検査を予約する。新しい文書として送った中身が、同じ公開範囲の使える文書のいまのバージョンと同じ（SHA-256 が同じ）なら、新しい文書を作らずに受け取った記録（receipts）だけを足し、その文書とバージョンを deduplicated: true で返す。本人だけの文書は、同じ持ち主の文書にだけまとめる

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes
`Idempotency-Key`	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

Request body

application/json

Responses

200 — DocumentUploadResult: 保存した文書とバージョン。検査を予約した時点では inspection_status は queued。検査状態は文書のバージョンか inspection で取得する。同じ要求キーの再送には保存済みの応答を返す
default — Problem: RFC 9457 Problem Details

listDocuments

GET/v1/documents

documents:read が必要。現在の公開範囲で読める文書だけを返す

Parameters

Name	In	Type	Required	Description
`limit`	query	integer
`cursor`	query	string

Responses

200 — object: 文書の一覧
default — Problem: RFC 9457 Problem Details

searchDocuments

POST/v1/documents/search

documents:read が必要。読める文書のいまのバージョンから、空白で区切ったすべての語を含むチャンク（ページの中の 800 文字）を探す。語は NFKC で正規化し、大文字と小文字を区別しない。検査の完了を待たずに探せ、感染を検出したバージョンは返さない。 UTF-8 のテキストは確定と同時に、PDF は埋め込んだ文字を非同期に取り出してから探せる（index_status が indexed になってから）。文字のない PDF は OCR を入れるまで対象にしない。mode で意味検索（semantic）と、全文検索と意味検索をまとめた検索（hybrid）を選べる。意味検索はチャンクの埋め込みを非同期に作ってから探せ、返す直前に全文検索と同じく権限といまのバージョンを確かめる。 mode を summary にすると、ページごとの最初の文から作った要約を探し、ページをまたいだ語も見つかる。意味検索がある環境では、要約の埋め込みが近いものも返す。要約も返す直前に同じことを確かめる。埋め込みや索引につながらないときも、index_generation を指定していなければ、summary は語で見つかるものを返す。要約の索引を足す前に入れた文書の要約は、alarm が順に埋め戻す。副作用がないので Idempotency-Key は要らない

Request body

application/json — DocumentSearchInput

Name	Type	Required	Description
`query`	string	yes	空白で区切った語。8 語まで。3 文字未満の語は部分一致で探す。意味検索では文全体を問い合わせにする
`limit`	integer
`mode`	`keyword` \| `semantic` \| `hybrid` \| `summary`		省略すると keyword。keyword は全文検索、semantic はチャンクの埋め込みが近いものを探す意味検索、hybrid は両方の順位を Reciprocal Rank Fusion でまとめる、summary は要約の索引を語と（意味検索がある環境では）埋め込みで探す。意味検索を有効にしていない環境では semantic と hybrid が CONFLICT になる。索引を作ったモデルがこの環境にないときも CONFLICT になる
`index_generation`	integer		意味検索に使う索引の世代。省略すると検索に使っている世代。切り替える前の世代を評価するときに指定する。作っている途中の世代は結果が欠ける。読める文書だけを返すのは同じ。mode が summary でも、指定すると意味検索のない環境では 409、埋め込みや索引の不調では 502 を返す

Responses

200 — DocumentSearchResult: 一致した箇所。一致の強い順に並べ、件数は limit まで
default — Problem: RFC 9457 Problem Details

getDocument

GET/v1/documents/{id}

documents:read と文書を読む権限が必要

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes

Responses

200 — Document: 文書
default — Problem: RFC 9457 Problem Details

deleteDocument

DELETE/v1/documents/{id}

documents:delete と文書を読む権限が必要。全文検索の索引・要約・抽出の候補はすぐに外し、直後の検索から返さない。 hold がなければ原本・本文・抽出の記録・確定していないアップロードも消し、文書は読めなくなる。 hold があれば原本・本文・抽出の記録を残し（retained_under_hold）、文書の status を deletion_held にする。hold を外したときに消す。確定にして台帳へ写した値は台帳が持つので消さず、managed_elsewhere として件数を返す。同じ文書への 2 回目は、消せなかった原本の削除をやり直して記録を返す

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes

Responses

200 — DocumentDisposal: 削除の追跡。status が purged になるまで削除の完了とは扱わない
default — Problem: RFC 9457 Problem Details

getDocumentDisposal

GET/v1/documents/{id}/disposal

documents:read と、documents:delete か documents:hold が必要。削除した文書でも、もとの公開範囲で読めた人には返す

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes

Responses

200 — DocumentDisposal: 削除の追跡
default — Problem: RFC 9457 Problem Details

setDocumentHold

PUT/v1/documents/{id}/hold

documents:hold と文書を読む権限が必要。hold をかけている間は、削除を受け付けても原本・本文・抽出の記録を消さない。すでに hold があれば変えずに返す

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes

Request body

application/json

Name	Type	Required	Description
`reason`	string	yes

Responses

200 — Document: hold をかけた文書
default — Problem: RFC 9457 Problem Details

releaseDocumentHold

DELETE/v1/documents/{id}/hold

documents:hold と文書を読む権限が必要。削除を受け付けていた文書（deletion_held）は、ここで残していたものを消し、status が deleted の文書を返す。 hold がなければ変えずに返す

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes

Responses

200 — Document: hold を外した文書
default — Problem: RFC 9457 Problem Details

expandDocumentArchive

POST/v1/documents/upload-sessions/{id}/expand

documents:write が必要。application/zip で送ったセッションを展開し、中のファイルを 1 件ずつ文書にする（統合と検査は 1 件ずつのアップロードと同じ）。件数（100 件）か展開後の合計（50 MiB）が上限を超える ZIP は 1 件も取り出さずに断る。パスワード付き・対応しない形式・壊れたファイルは、理由を付けて items で返し、ほかのファイルは受け付ける

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes
`Idempotency-Key`	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

Request body

application/json

Responses

200 — DocumentIntakeResult: ファイルごとの結果
default — Problem: RFC 9457 Problem Details

receiveDocumentMail

POST/v1/documents/inbound-mail

メールの受信の係だけが呼ぶ。x-hane-inbound-secret と宛先のアドレスの署名から組織・環境・プロジェクトを決める。添付を 1 件ずつ文書にしてプロジェクトに公開する（ZIP は展開する）。本文は定義の mailBody の種類に当たったときだけ書類にして、当たらなければ残さない。件名と差出人は受け取った記録に残す。Idempotency-Key には事業者の Message-ID を渡す

Parameters

Name	In	Type	Required	Description
`x-hane-inbound-secret`	header	string	yes
`Idempotency-Key`	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

Request body

application/json

Name	Type	Required	Description
`to`	string	yes
`from`	string	yes
`subject`	string	yes
`text`	string		転送の本文。社外から来た信頼できない入力
`attachments`	object[]	yes

Responses

200 — DocumentIntakeResult: ファイルごとの結果
default — Problem: RFC 9457 Problem Details

getDocumentIntakeAddress

GET/v1/documents/intake-address

documents:write が必要。このプロジェクトに書類を転送するメールアドレス。知っている人が書類を置けるので、書類を足せる人にだけ返す

Responses

200 — object: 転送用のアドレス
default — Problem: RFC 9457 Problem Details

listRecordDocuments

GET/v1/documents/by-record/{recordId}

documents:read が必要。レコードに結び付いた書類のうち、読めるもののいまのバージョン（100 件まで）

Parameters

Name	In	Type	Required	Description
`recordId`	path	string	yes

Responses

200 — object: 書類ごとの振り分けの結果
default — Problem: RFC 9457 Problem Details

confirmDocumentRelation

POST/v1/documents/relations/{id}/confirm

documents:write と、つながりの両方の書類を読む権限が必要。候補のつながりを確かめる。If-Match はつながりの revision

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes
`If-Match`	header	string	yes
`Idempotency-Key`	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

Request body

application/json

Responses

200 — DocumentRelation: 確かめたつながり
default — Problem: RFC 9457 Problem Details

rejectDocumentRelation

POST/v1/documents/relations/{id}/reject

documents:write と、つながりの両方の書類を読む権限が必要。候補のつながりを退ける。If-Match はつながりの revision

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes
`If-Match`	header	string	yes
`Idempotency-Key`	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

Request body

application/json

Responses

200 — DocumentRelation: 退けたつながり
default — Problem: RFC 9457 Problem Details

getDocumentPlacement

GET/v1/documents/{id}/versions/{version}/placement

documents:read と文書を読む権限が必要。書類を何と判断し、どこに入れたか（種類、読んだ識別子と結び付いたレコード、書類どうしのつながり、足りない書類の待ち、進行中の案件）

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes
`version`	path	integer	yes

Responses

200 — DocumentPlacement: 振り分けの結果
default — Problem: RFC 9457 Problem Details

decideDocumentLink

PUT/v1/documents/{id}/versions/{version}/links/{linkId}

documents:write と文書を読む権限が必要。読み誤りの疑いのある結び付け（needs_review）を人が決める。record_id は候補のレコードで、null なら退ける。決めたレコードの key を識別子の値にして、つながり・待ち・案件を決め直す。If-Match は結び付けの revision

Parameters

Name	In	Type	Required
`id`	path	string	yes
`version`	path	integer	yes
`linkId`	path	string	yes
`If-Match`	header	string	yes

Request body

application/json

Name	Type	Required	Description
`record_id`	string \| null	yes

Responses

200 — DocumentLink: 決めた結び付け
default — Problem: RFC 9457 Problem Details

listDocumentReceipts

GET/v1/documents/{id}/receipts

documents:read と文書を読む権限が必要。同じ中身のため、この文書にまとめた受け取り（最初の受け取りはバージョンの filename と uploaded_by）

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes

Responses

200 — object: まとめた受け取り（古い順）
default — Problem: RFC 9457 Problem Details

getDocumentClassification

GET/v1/documents/{id}/versions/{version}/classification

documents:read と文書を読む権限が必要。書類の種類（documents/v1alpha1 DocumentType）と、そう判断した理由と候補。索引を作るときに、有効な ReleaseBundle の種類で決める。種類の定義がなく、まだ判断していなければ 404。ETag は revision

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes
`version`	path	integer	yes

Responses

200 — DocumentClassification: 書類の種類
default — Problem: RFC 9457 Problem Details

classifyDocument

PUT/v1/documents/{id}/versions/{version}/classification

documents:write と文書を読む権限が必要。人が書類の種類を決める（status は confirmed）。type はいまの有効な ReleaseBundle の DocumentType の名前で、ないものは 400。決めた種類で抽出の候補を作り直す（確かめた候補は残す）。If-Match は分類の ETag

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes
`version`	path	integer	yes
`If-Match`	header	string	yes	取得したときの ETag（version）

Request body

application/json

Name	Type	Required	Description
`type`	string	yes

Responses

200 — DocumentClassification: 決めた種類
default — Problem: RFC 9457 Problem Details

listDocumentSearchIndexes

GET/v1/documents/search-index

documents:search-index.manage が必要。組織×環境の意味検索の索引の世代と、埋め込みのジョブの数を返す。消し終えた世代は返さない。意味検索を有効にしていない環境では CONFLICT

Responses

200 — object: 索引の世代
default — Problem: RFC 9457 Problem Details

rebuildDocumentSearchIndex

POST/v1/documents/search-index/rebuild

documents:search-index.manage が必要。新しい世代の索引を並べて作り始める。組織×環境のすべての文書のいまのバージョンを、次のモデル（なければいまのモデル）で埋め込む。 chunking を渡すと、残したページの本文をその切り方で切り直す。本文の取り出しはやり直さない。全文検索のチャンクも切り替えで一緒に替わる。作っている間も検索は前の世代のまま。すでに作っている世代があれば CONFLICT

Request body

application/json — DocumentSearchIndexRebuildInput

Name	Type	Required	Description
`chunking`	string		チャンクの切り方。fixed-800-100 か sections-400-50。省略すると検索に使っている世代の切り方

Responses

202 — DocumentSearchIndex: 作り始めた世代
default — Problem: RFC 9457 Problem Details

reindexDocuments

POST/v1/documents/search-index/reindex

documents:search-index.manage が必要。プロジェクトの、索引の状態が status のいまのバージョンを、本文の取り出しをやり直す待ちに戻す。変換（needs_conversion）や OCR（needs_ocr）を入れた後に呼ぶ。外部の処理は alarm から順に頼むので、すぐに終わらない。原本を残していない参照だけの書類、感染を検出したバージョン、hold の間の変換した PDF のあるバージョンは skipped に数える

Request body

application/json — DocumentReindexInput

Name	Type	Required	Description
`status`	`failed` \| `needs_ocr` \| `needs_conversion`	yes	索引し直す、いまのバージョンの索引の状態

Responses

202 — DocumentReindexResult: 待ちに戻した数
default — Problem: RFC 9457 Problem Details

activateDocumentSearchIndex

POST/v1/documents/search-index/{generation}/activate

documents:search-index.manage が必要。作り終えた世代を検索に使い始め、前の世代のベクトルを消し始める。評価（pnpm dev:eval:search）を通してから呼ぶ。待っているか失敗したジョブがあれば CONFLICT

Parameters

Name	In	Type	Required	Description
`generation`	path	integer	yes

Responses

200 — DocumentSearchIndex: 検索に使い始めた世代
default — Problem: RFC 9457 Problem Details

discardDocumentSearchIndex

POST/v1/documents/search-index/{generation}/discard

documents:search-index.manage が必要。作っている世代を捨て、ベクトルを消す。検索は前の世代のまま

Parameters

Name	In	Type	Required	Description
`generation`	path	integer	yes

Responses

200 — DocumentSearchIndex: 捨てた世代
default — Problem: RFC 9457 Problem Details

listAllExtractedFacts

GET/v1/documents/facts

documents:read が必要。文書をまたいで抽出の候補を作った順に返す。status=needs_review で要確認の候補を順に見られる。読める、使える（削除を受け付けていない）文書の候補だけを返し、置き換えた候補と感染を検出したバージョンの候補は返さない。文書の古いバージョンの候補も、人が決めるまで返す

Parameters

Name	In	Type	Description
`status`	query	`candidate` \| `needs_review` \| `pending_inquiry` \| `confirmed` \| `rejected`	この状態の候補だけを返す
`limit`	query	integer
`cursor`	query	string

Responses

200 — object: 抽出の候補
default — Problem: RFC 9457 Problem Details

getExtractionReviewStats

GET/v1/documents/facts/stats

documents:read が必要。抽出の候補を人が確かめた結果を数える。items は抽出の定義・ReleaseBundle・書類の種類・項目・読み方ごと、 fields は定義の項目と読み方ごとで、読めた文書の割合も返す。releases は定義の ReleaseBundle ごとで、定義を変える前後を比べる。読める、使える（削除を受け付けていない）文書の候補だけを数え、置き換えた候補は数えない。抽出し直して同じ読み取りの候補がまた作られたら、人の決定を待つ候補より決定を、決定が複数あれば決めた時刻が最後の決定を 1 つだけ数える

Parameters

Name	In	Type	Required	Description
`release_id`	query	string		この ReleaseBundle で読んだ候補だけを数える。releases は絞らない

Responses

200 — ExtractionReviewStats: 確認の結果の数
default — Problem: RFC 9457 Problem Details

listExtractionEvalCandidates

GET/v1/documents/eval-set/candidates

documents:read が必要。評価セットの候補を返す。プロジェクトに共有した文書のうち、人が候補を直すか退けた項目があり、まだ評価セットに入っていないものを、文書のバージョンと抽出の定義ごとに返す

Responses

200 — object: 評価セットの候補
default — Problem: RFC 9457 Problem Details

listExtractionEvalCases

GET/v1/documents/eval-set/cases

documents:read が必要。評価セットの件を返す。本文は返さない

Parameters

Name	In	Type	Description
`schema`	query	string	抽出の定義の名前で絞る
`limit`	query	integer
`cursor`	query	string

Responses

200 — object: 評価セットの件
default — Problem: RFC 9457 Problem Details

createExtractionEvalCase

POST/v1/documents/eval-set/cases

documents:write が必要。人が確かめた書類から伏せた複製を作り、人の決定を正解にする。読んだ文字列の値と、連絡先・番号の形をした文字を伏せる。文章の中の氏名は見つけられないことがあるので、terms に挙げる。作った件は draft で、人が承認するまで比べるときに使わない。プロジェクトに共有した文書だけを入れられる。複製は元の Tenant の中にだけ置き、元の文書を消すと一緒に消す

Parameters

Name	In	Type	Required	Description
`Idempotency-Key`	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

Request body

application/json

Name	Type	Required	Description
`document_id`	string	yes
`version`	integer	yes
`schema`	string	yes	抽出の定義の名前
`consent`	string	yes	この書類を評価に使ってよい根拠（顧客との約束など）
`terms`	string[]		伏せる語。語そのものは残さない

Responses

201 — ExtractionEvalCaseReceipt: 作った件
default — Problem: RFC 9457 Problem Details

getExtractionEvalCase

GET/v1/documents/eval-set/cases/{id}

documents:read が必要。伏せた本文を返す。承認する前に、伏せ漏れがないかをこれで読む

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes

Responses

200 — ExtractionEvalCase: 評価セットの件
default — Problem: RFC 9457 Problem Details

deleteExtractionEvalCase

DELETE/v1/documents/eval-set/cases/{id}

documents:write が必要。評価セットから外し、伏せた複製を消す

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes

Responses

204: 消した
default — Problem: RFC 9457 Problem Details

approveExtractionEvalCase

POST/v1/documents/eval-set/cases/{id}/approve

documents:write が必要で、人だけが呼べる。伏せた本文を読んで、比べるときに使ってよいと決める

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes
`Idempotency-Key`	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる
`If-Match`	header	string	yes	取得したときの ETag（version）

Request body

application/json

Responses

200 — ExtractionEvalCaseReceipt: 承認した件
default — Problem: RFC 9457 Problem Details

listExtractionEvalComparisons

GET/v1/documents/eval-set/comparisons

documents:read が必要。読み比べの記録を新しい順に 50 件返す。読んだ値は残していない

Parameters

Name	In	Type	Required	Description
`schema`	query	string		抽出の定義の名前で絞る

Responses

200 — object: 読み比べの記録
default — Problem: RFC 9457 Problem Details

compareExtractionEvalSet

POST/v1/documents/eval-set/comparisons

documents:write が必要。承認した評価セットの全件を、2 つの ReleaseBundle の抽出の定義で読み比べる。まだ有効にしていない ReleaseBundle も比べられる。ラベルの読み方だけを比べ、Agent が読む項目は not_evaluated にする。悪くなった項目が 1 つでもあれば failed。 stage と prod では、定義を変えた ReleaseBundle は、評価セットのある定義についていま有効な ReleaseBundle と比べて通るまで有効にできない。応答は保存せず、同じ Idempotency-Key でも再送しない

Parameters

Name	In	Type	Required	Description
`Idempotency-Key`	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

Request body

application/json

Name	Type	Required	Description
`schema`	string	yes	抽出の定義の名前
`release_id`	string	yes	比べる ReleaseBundle
`base_release_id`	string		比べる相手。省くといまの有効な ReleaseBundle

Responses

200 — ExtractionEvalComparison: 読み比べた結果。項目の values に比べた値が付く
default — Problem: RFC 9457 Problem Details

listDocumentVersions

GET/v1/documents/{id}/versions

documents:read と文書を読む権限が必要

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes

Responses

200 — object: 文書のバージョン
default — Problem: RFC 9457 Problem Details

getDocumentVersion

GET/v1/documents/{id}/versions/{version}

documents:read と文書を読む権限が必要。原本の保存先のキーは返さない

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes
`version`	path	integer	yes

Responses

200 — DocumentVersion: 文書のバージョン
default — Problem: RFC 9457 Problem Details

downloadDocumentVersion

GET/v1/documents/{id}/versions/{version}/content

documents:download と文書を読む権限が必要。検査状態が clean の原本だけを添付として返す。未検査・検査中・検出・失敗の場合は CONFLICT（409）を返す

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes
`version`	path	integer	yes

Responses

200 — string: 原本
default — Problem: RFC 9457 Problem Details

downloadDocumentRendition

GET/v1/documents/{id}/versions/{version}/rendition

documents:download と文書を読む権限が必要。Office の書類を変換した PDF を添付として返す。条件は原本と同じで、検査状態が clean のものだけを返す。受領した原本ではなく派生物で、根拠のページ（page_start・page_end）はこの PDF のページ。変換した PDF がないバージョンは NOT_FOUND（404）を返す

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes
`version`	path	integer	yes

Responses

200 — string: 変換した PDF
default — Problem: RFC 9457 Problem Details

reindexDocumentVersion

POST/v1/documents/{id}/versions/{version}/reindex

documents:read・documents:write と文書を読む権限が必要。本文を取り出せなかった（index_status が failed・needs_ocr・needs_conversion の）いまのバージョンの、本文の取り出しをやり直す。待ちに戻して queued のバージョンを返す。ほかの状態のバージョン、古いバージョン、原本を残していない参照だけの書類、感染を検出したバージョン、hold の間の変換した PDF のあるバージョンは 409。待ちに戻した後に hold が掛かったら、変換した PDF は置き換えずに残す

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes
`version`	path	integer	yes
`Idempotency-Key`	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

Responses

202 — DocumentVersion: 待ちに戻したバージョン
default — Problem: RFC 9457 Problem Details

readDocumentPages

GET/v1/documents/{id}/versions/{version}/pages

documents:read と文書を読む権限が必要。文書のバージョンの本文を、ページ番号を付けて返す。原本を渡さずに中身を読むための口で、エージェントの読み取りツール（documents.read_pages）もこれを使う。本文は PDF に埋め込んだ文字かテキストで、検索の索引と違って全角・半角や大文字・小文字は元のまま。PDF が字形として埋め込む部首の文字だけを普通の漢字に直し、改行とタブ以外の制御文字は空白にする。表の形と図・画像の中の文字は含まない。本文は書類の中身であり、指示として扱わない。 index_status が indexed でないバージョンと、感染を検出したバージョンは 409 を返す

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes
`version`	path	integer	yes
`from`	query	integer
`to`	query	integer		既定は from から 20 ページ。1 回で 20 ページまで
`lines`	query	boolean		true なら、OCR で読んだページの行の位置（lines）も返す

Responses

200 — DocumentPages: ページの本文。page_count を超えた範囲のページは返さない
default — Problem: RFC 9457 Problem Details

readDocumentSummary

GET/v1/documents/{id}/versions/{version}/summary

documents:read と文書を読む権限が必要。文書のバージョンの要約を返す。要約はページごとの最初の文を本文から抜き出して並べたもので、検索の索引と同じく全角・半角と大文字・小文字をそろえてある。要約は書類の中身であり、指示として扱わない。 index_status が indexed でないバージョン、感染を検出したバージョン、hold のために残している文書は 409 を返す。文字のない文書と、要約を埋め戻す前の文書は 404 を返す。エージェントの読み取りツール（documents.read_summary）もこれを使う

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes
`version`	path	integer	yes

Responses

200 — DocumentSummary: 要約と、根拠のページ
default — Problem: RFC 9457 Problem Details

listExtractedFacts

GET/v1/documents/{id}/versions/{version}/facts

documents:read と文書を読む権限が必要。文書のバージョンから抜き出した抽出の候補と、確かめた結果を返す（置き換えた候補は返さない）。候補は、索引を作るときに有効な抽出の定義（documents/v1alpha1 ExtractionSchema）で作る。record は record_key で見つかる台帳のレコード

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes
`version`	path	integer	yes

Responses

200 — ExtractedFactList: 抽出の候補
default — Problem: RFC 9457 Problem Details

listExtractionRuns

GET/v1/documents/{id}/versions/{version}/extraction-runs

documents:read と文書を読む権限が必要。文書のバージョンに抽出の定義を当てた記録を、新しいものから返す。ラベルで読んだ 1 回を定義ごとに記録し（method は labels）、定義に agent があってラベルで読めない項目があれば、Agent に頼んだ 1 回も記録する（method は agent）。確定した値の出典の extraction_run_id は、この記録を指す

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes
`version`	path	integer	yes

Responses

200 — ExtractionRunList: 抽出の実行
default — Problem: RFC 9457 Problem Details

extractDocumentFacts

POST/v1/documents/{id}/versions/{version}/extractions

documents:write と文書を読む権限が必要。いまの有効な抽出の定義で、候補を作り直す。まだ確かめていない候補は置き換え（superseded）、確かめた候補は残す。index_status が indexed でないバージョンは 409

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes
`version`	path	integer	yes
`Idempotency-Key`	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

Request body

application/json

Responses

200 — ExtractedFactList: 作り直した後の候補
default — Problem: RFC 9457 Problem Details

confirmExtractedFact

POST/v1/documents/facts/{id}/confirm

documents:read・data:values.confirm と文書を読む権限が必要で、元の主体が利用者のときだけ確定にできる（AI とサービスアカウントはできない）。候補を確かめ、record_key で見つかるレコードの項目を確定にする。出典は文書のバージョン・ページ・引用と、候補を作った抽出の実行（extraction_run_id）。value を送ると、直した値で確定にする。 status が needs_review の候補は value が必要で、なければ 409。pending_inquiry の候補は回答の値を value で送り、照会を始めたレコードの項目を確定にする。出典は回答を入れた人で（reason は出典の note に残す）、参照だけの書類でも確定にできる。読めた key が割れていた書類は、key の項目の value でレコードを探し、同じ定義の候補をそのレコードに結び付ける。レコードが見つからなければ 409。If-Match は候補の ETag

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes
`Idempotency-Key`	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる
`If-Match`	header	string	yes	取得したときの ETag（version）

Request body

application/json

Name	Type	Required	Description
`value`	string \| number		直した値か、人が選んだ値。送らなければ候補の値で確定にする（needs_review の候補は送る）
`reason`	string		直した理由

Responses

200 — ExtractedFact: 確かめた候補
default — Problem: RFC 9457 Problem Details

rejectExtractedFact

POST/v1/documents/facts/{id}/reject

documents:read・data:values.confirm と文書を読む権限が必要。候補を退ける。台帳は変えない。 pending_inquiry の候補を退けるのは値を取れなかったときで、台帳の項目の値がこの照会で書いたままなら値のない不明にする。待つ間に人が直した値は変えない。If-Match は候補の ETag

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes
`Idempotency-Key`	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる
`If-Match`	header	string	yes	取得したときの ETag（version）

Request body

application/json

Name	Type	Required	Description
`reason`	string

Responses

200 — ExtractedFact: 退けた候補
default — Problem: RFC 9457 Problem Details

inquireExtractedFact

POST/v1/documents/facts/{id}/inquire

documents:read・data:values.confirm と文書を読む権限が必要で、元の主体が利用者のときだけ呼べる（AI とサービスアカウントはできない）。書類から取れない値を相手に問い合わせる。record_key で見つかるレコードの項目を要照会にし、候補は回答を待つ（pending_inquiry）。台帳の値は仮の値として残し、なければ値を持たない。確定の値も要照会に下げる。出典は候補の文書のバージョン・ページ・引用で、reason は値の note に残す。抽出の定義に照会の Workflow（inquiry）があれば問い合わせの案件を始め、候補の inquiry_case_id と値の出典に案件の ID を残す。回答の確定・値を取れないときの却下・文書の削除で照会が閉じると、documents.inquiry.closed が案件の Task を閉じる。回答を待つ間に別の文書の候補の確定や台帳の修正で項目が確定になっても照会は閉じ、候補は置き換わる（superseded）。レコードが見つからないか、候補がもう回答を待っているか、同じレコードの同じ項目にほかの照会が開いていれば 409。レコードの key の項目は要照会にできない（409）。If-Match は候補の ETag

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes
`Idempotency-Key`	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる
`If-Match`	header	string	yes	取得したときの ETag（version）

Request body

application/json

Name	Type	Required	Description
`reason`	string		誰に何を問い合わせるか
`due`	string		いつまでに聞くか（YYYY-MM-DD）。案件の input.due に入る。過去の日は 400、照会の Workflow がない定義では 409

Responses

200 — ExtractedFact: 回答を待つ候補
default — Problem: RFC 9457 Problem Details

getDocumentInspection

GET/v1/documents/{id}/versions/{version}/inspection

documents:read と文書を読む権限が必要。検査状態と試行回数、次の再試行時刻を返す。未検査の既存の原本は not_scanned、version は 1

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes
`version`	path	integer	yes

Responses

200 — DocumentInspection: 文書のバージョンごとの検査状態。ETag は検査状態の version
default — Problem: RFC 9457 Problem Details

retryDocumentInspection

POST/v1/documents/{id}/versions/{version}/inspection/retry

documents:write と文書の持ち主の権限が必要。failed または not_scanned の原本の検査を予約し直す。If-Match は検査状態の ETag。試行回数は 0 から数え直す

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes
`version`	path	integer	yes
`Idempotency-Key`	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる
`If-Match`	header	string	yes	取得したときの ETag（version）

Request body

application/json

Responses

200 — DocumentInspection: 検査を予約した状態
default — Problem: RFC 9457 Problem Details