コンテンツへスキップ
KUKANKUKAN

REST API

ベースパス: /api/v1

認証列の記号:

  • 公開 — 認証不要
  • 認証 — ログインまたは API トークンが必要
  • 組織 — 組織の member / editor / admin のいずれか
  • sysadmin — システム管理者のみ

リクエスト本文は 1 MiB までです。超えると、本文を解釈する前に 413（PAYLOAD_TOO_LARGE）で断ります。 ファイルのアップロード（POST /resources/{id}/upload）だけは別で、ファイルの上限が適用されます。

データセット (packages)

Section titled “データセット (packages)”
Method Path 説明 認証
GET /packages データセット一覧（検索・絞り込み対応） 公開
POST /packages データセット作成（resources 配列でリソース同時作成可。各項目は POST /packages/{id}/resources と同じ検証で、1 件でも拒否されれば何も作られない） 組織 editor
POST /packages/drafts 下書き作成（全フィールド任意） 認証
POST /packages/highlights 本文ハイライトの遅延取得（{ q, chunks }、閲覧可能な範囲のみ） 公開
GET /packages/{nameOrId} データセット詳細 公開
PUT /packages/{nameOrId} データセット更新（active は全置換 / draft は部分更新、resources は対象外） 組織 editor
DELETE /packages/{nameOrId} データセット削除（active は論理削除 / draft は即時完全削除） 組織 editor
POST /packages/{nameOrId}/publish 下書きを公開（draft → active） 組織 editor
POST /packages/{nameOrId}/suggest-metadata AI によるメタデータ提案（保存はしない。使えない場合は 503） 組織 editor
POST /packages/{nameOrId}/restore 論理削除済みを復元（本文 { private: true } で非公開のまま復元） 組織 admin
POST /packages/{nameOrId}/purge 論理削除済みを完全削除 組織 admin
GET /packages/{id}/resources リソース一覧 公開
POST /packages/{id}/resources リソース追加 組織 editor
PUT /packages/{id}/resources/reorder リソース順序変更 組織 editor

主なクエリパラメータ（GET /packages）

Section titled “主なクエリパラメータ（GET /packages）”
パラメータ 説明
q 検索クエリ（キーワードまたは自然文。ハイブリッド検索。最大 500 文字）
name データセット名の前方一致
semantic false でキーワード一致のみ（デフォルト: true）
match relaxed で、q のすべての語を持つデータセットが無いとき、語の少ない一致に緩める（デフォルト: all。後述）
offset / limit ページネーション（limit は最大 100。offset + limit は最大 10,000、my_org=true と state=draft を除く）
organization[] 組織で絞り込み
groups[] カテゴリーで絞り込み
tags[] タグで絞り込み
res_format[] リソース形式で絞り込み（例: CSV）
license_id[] ライセンスで絞り込み
extras_<key> データセットの extras で、キー <key> の値が一致するもの（後述）
res_extras_<key> いずれかのリソースの extras で、キー <key> の値が一致するもの（後述）
creator_user_id 作成者のユーザー ID で絞り込み
state active / deleted / draft（draft は要認証・後述。deleted は my_org=true かつ認証時のみ有効で、それ以外は active）
my_org 自分が editor 以上の組織に限定
private true で非公開のみ、false で公開のみに絞り込み（省略時は閲覧可能なすべて）
sort_by updated / created / name
sort_order asc / desc
include_facets ファセット情報を含める

extras で絞り込む

Section titled “extras で絞り込む”

extras_<key>=<value> はデータセットの extras、res_extras_<key>=<value> はリソースの extras で 絞り込みます。キーはパラメータ名の側に URL エンコードして書くので、日本語や .・: を含むキーも そのまま指定できます。

ターミナルウィンドウ
curl -G "https://your-kukan-site/api/v1/packages" \
  --data-urlencode "extras_%E6%95%B4%E5%82%99%E5%8D%98%E4%BD%8D=市町村" \
  --data-urlencode "res_extras_lang=ja"

--data-urlencode が符号化するのは = の右側だけです。日本語などを含むキーは、上の extras_%E6%95%B4%E5%82%99%E5%8D%98%E4%BD%8D（extras_整備単位）のように自分でパーセントエンコードしてください。

  • 値は完全一致で比べます。大文字小文字の同一視、前後の空白の除去、全角・半角の正規化はしません
  • 数値は指数を使わない十進表記、真偽値は true / false で比べます（extras_n=5 は数値の 5 にも 文字列の "5" にも一致。数値の 1e-7 は extras_n=0.0000001 で引きます）。 値が配列なら、要素のどれかが一致すれば当たります。オブジェクトと null の値には一致しません
  • 条件はすべて AND です。同じパラメータを繰り返しても AND になります
  • res_extras_* は、条件ごとに「どれか 1 つのリソースが満たす」ものです。複数の条件を同じリソースが 満たす必要はありません（res_format[] と同じ）
  • キーが空（extras_=）のものと、1 リクエストで 20 を超える条件は 400 です

語の一致を緩める（match=relaxed）

Section titled “語の一致を緩める（match=relaxed）”

語の一致では、q を空白で区切ったすべての語を持つデータセットが一致します。match=relaxed を 指定すると、すべての語を持つデータセットが 1 件も無いときに限り、1 語少ない数、半分、1 語の順に 緩めて検索し直します。緩めたときは、応答に minWords（一致に求めた語の数）が付き、各データセットに 持たない語が missingWords として付きます（意味だけで一致したデータセットには付きません）。すべての語で見つかったとき、minWords は付きません。

例: データセット検索

Section titled “例: データセット検索”
ターミナルウィンドウ
curl "https://your-kukan-site/api/v1/packages?q=人口&organization[]=stat-bureau&limit=10"

下書き（draft）

Section titled “下書き（draft）”

データセットは下書きとして作成し、公開条件を満たしてから公開できます。 下書きは公開されるまで検索・一覧（CKAN 互換 API 含む）に一切現れません。

作成 — POST /packages/drafts（要認証）:

全フィールド任意です。name を省略すると untitled-xxxxxxxx 形式のプレースホルダーが 自動生成されます（プレースホルダーのままでは公開できません）。作成時に ownerOrg を 指定する場合は、その組織の editor 権限が必要です。

ターミナルウィンドウ
curl -X POST https://your-kukan-site/api/v1/packages/drafts \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"title": "作業中のデータセット"}'

公開 — POST /packages/{nameOrId}/publish:

draft → active の一方向遷移です（公開後に下書きへ戻す操作はありません）。 以下の 3 つが未設定の場合は 400 を返します。

  • name が明示的に設定済み（自動生成プレースホルダーのままは不可）
  • ownerOrg が設定済み
  • licenseId が設定済み

権限はデータセット更新権限と同一で、ownerOrg の組織の editor 権限が公開時点で 再検証されます。公開済み（active）への再実行は許可され、公開時の検索インデックス 同期を再実行します（同期が失敗した場合のリトライ入口として冪等）。

一覧 — GET /packages?state=draft（要認証）:

自分が作成した下書きと、所属組織（editor 以上）の下書きのみが返ります。 対応フィルタは q / name / organization[] / private / sort_by / sort_order / offset / limit。tags[] / groups[] / res_format[] / license_id[] / extras_<key> / res_extras_<key> / creator_user_id / my_org / include_facets を 指定すると 400 になります。 削除が途中で失敗した行（削除未完了）も一覧に含まれます。

取得・更新・削除:

  • 詳細取得は GET /packages/{id}?state=draft（要認証・下書きの閲覧権限が必要）
  • draft への PUT は部分更新です。リクエストに含めたキーのみ適用され、明示的な null はそのフィールドをクリアします。name: null はプレースホルダーを再生成して 「名前未設定」に戻し、ownerOrg: null は組織をクリアします（いずれも公開が再び ブロックされます）。active への PUT は従来どおり全置換です
  • draft への DELETE はゴミ箱を経由せず即時完全削除します（復元不可）。削除が 途中で失敗した場合は、同じ DELETE の再実行が完全削除を完了します

リソース (resources)

Section titled “リソース (resources)”
Method Path 説明 認証
GET /resources/count アクティブなリソース数（my_org=true で自分が editor 以上の組織に限定） 公開
GET /resources/formats 閲覧可能なリソースのフォーマット一覧 公開
GET /resources/{id} リソース詳細 公開
GET /resources/{id}/text テキストコンテンツ取得（プレビューサイズ制限） 公開
GET /resources/{id}/json JSON/GeoJSON を最小化して返す（JSON 以外は 415、上限超過は 413） 公開
GET /resources/{id}/download ファイルダウンロード（外部 URL は 302 リダイレクト） 公開
GET /resources/{id}/preview サーバー経由プレビュー（Range 対応） 公開
GET /resources/{id}/pipeline-status パイプライン処理状態 公開
GET /resources/{id}/schema 列スキーマ（列名・型・行数・数値統計）。表形式のみ 公開
POST /resources/{id}/query サーバーサイド DuckDB クエリ（SELECT 限定）。表形式のみ 公開
POST /resources/{id}/upload-url プリサインドアップロード URL 発行 組織 editor
POST /resources/{id}/upload サーバー経由アップロード（multipart file、ストリーム処理、上限超過は 413、ファイル名が upload-url と同じ規則（1〜500 文字）に合わなければ 400） 組織 editor
POST /resources/{id}/upload-complete アップロード完了通知・パイプライン投入 組織 editor
POST /resources/{id}/run-pipeline パイプライン手動実行 組織 editor
POST /resources/{id}/cancel-pipeline 実行中の処理を中止（内容はそのまま） 組織 editor
POST /resources/{id}/revert 処理を中止し、内容を指定の版へ戻す 組織 editor
GET /resources/{id}/column-settings 確定済みの列情報と、確定に使える列 組織 editor
POST /resources/{id}/column-settings/check この主キーで行を同定できるか 組織 editor
PUT /resources/{id}/column-settings 主キーを確定する 組織 editor
GET /resources/{id}/column-roles 列の役割と、規則がそう判定した根拠 組織 editor
PUT /resources/{id}/summary AI による説明を非表示にする / 戻す（{ hidden }） 組織 editor
PUT /resources/{id} リソース更新（全フィールド置換。section だけは省略で保持） 組織 editor
DELETE /resources/{id} リソース削除 組織 editor

セクション (section)

Section titled “セクション (section)”

リソースは section フィールド（文字列、省略時 null）を持ちます。データセットページの リソース一覧で見出しを立てるための表示上の区切りで、公開範囲や権限には影響しません。

見出しは「同じ section が連続している区間」ごとに立ちます。間に別のセクションや section なしのリソースが挟まると、同じ名前でも改めて見出しが立ちます。並び順は position が唯一の正で、section は並びに関与しません。

  • POST /packages/{id}/resources と PUT /resources/{id} で指定できます。PUT で省略した 場合は保持され、null を渡すと解除されます
  • 値は保存時に正規化されます（/ で分割し、各セグメントの前後空白を除去、空セグメントを 捨てて / で再結合。結果が空なら null）。/ は将来の階層表示のために予約されています
  • 同じ名前は連続した 1 区間にしか付けられません。離れた 2 箇所に同じ名前を置く指定 （reorder の sections、作成・更新の section）は 400 になります。並び順だけの reorder や null での解除が区間を分断する場合も同様です
  • PUT /packages/{id}/resources/reorder は任意の sections を受け付け、並び順と同じ トランザクションでラベルを更新します。リソース更新と違いパイプラインを再実行しないため、 並べ替えでラベルが変わる場合はこちらを使います。指定する場合は全アクティブリソースを 1 回ずつ挙げます（後の保存が丸ごと勝ちます）。省略すればラベルは変わりません
{
  "resourceIds": ["<id-1>", "<id-2>"],
  "sections": [
    { "resourceId": "<id-1>", "section": "関連資料" },
    { "resourceId": "<id-2>", "section": null }
  ]
}

カスタムフィールド (extras)

Section titled “カスタムフィールド (extras)”

リソースは、利用者が自由に付けられるキーと値（extras、オブジェクト）を持ちます。データセットの extras と同じく、値には任意の JSON を置けます。

  • POST /packages/{id}/resources と PUT /resources/{id} で指定できます。PUT では丸ごと置き換わり、 省略すると空（{}）になります。データセットの PUT や CKAN の resource_update と同じ扱いです
  • 次のキーは予約されていて、使うと 400 になります（details.issues[].path が ["extras", "<キー>"]）
    • CKAN がリソースに定める項目名（id、package_id、url、url_type、name、description、 format、mimetype、size、hash、created、last_modified、metadata_modified、position、 state、resource_type など）。CKAN 互換 API は extras をリソースのトップレベルに 展開するため、同じ名前だと標準の項目と区別できません
    • section。CKAN 互換 API では、リソースのセクションを同じトップレベルに載せるため
    • 以前のヘルスチェックが使っていたキー（healthEtag、healthLastModified、healthError、 healthHttpStatus、healthLastFullFetchAt）
{ "name": "人口統計", "url": "https://example.com/population.csv", "extras": { "単位": "人" } }

バージョン (versions)

Section titled “バージョン (versions)”
Method Path 説明 認証
GET /resources/{id}/versions 版の一覧（新しい順。削除済みも記録として残る） 公開
GET /resources/{id}/versions/{v} 版の詳細 公開
GET /resources/{id}/versions/{v}/diff 直前の版との行差分。表形式のみ 組織 editor
GET /resources/{id}/versions/{v}/download その版のファイルをダウンロード 公開
POST /resources/{id}/versions/{v}/purge 版の内容を完全削除（法的削除） sysadmin

公開エンドポイントの可視性判定はダウンロード・プレビューと同じです（非公開データセットは 権限が必要）。

文書の本文

Section titled “文書の本文”

PDF・Word・PowerPoint・Excel・一太郎・Markdown のリソースは、パイプラインが抽出した本文を、ページ・スライド・シートと 見出しの位置付きで読めます。MCP の get_document_outline / get_document_section と同じ読み出しです。

Method Path 説明 認証
GET /resources/{id}/document-text 本文のブロックを先頭から一括で取得（プレビューサイズ制限） 公開
GET /resources/{id}/document-outline 見出し（シート）と、それぞれのページ範囲・読めないページ 公開
GET /resources/{id}/document-section ページ範囲・見出しを指定して本文を読む（カーソルで続きから） 公開
  • document-outline：from / to でページ（スライド・シート）を絞れます。units（ページ等の種類と最初・最後）、 entries（見出しごとの depth・title・units、シートは rows）、unreadable（スキャン等で本文の読めないページ）、 partlyUnreadable（一部の文字が読めないページ）を返します。
  • document-section：from / to（ページ・スライド・シート、1 始まり）、heading（見出しの一部か A > B のパス、 シート名の一部。大文字小文字・全半角・空白は区別しない）、max_chars（デフォルト: 8,000、最大: 32,000）。 parts は document-text のブロックと同じ形で、text は切った範囲、offset はブロックの本文の中の開始位置です。 シートのブロックの loc.rows は、切った範囲が持つ行に絞られます。続きがあるときは next にカーソルが入るので、 cursor に渡して続きを読みます。カーソルは範囲と見出しを持つので、そのとき from / to / heading は読みません。 何も一致しないときは、parts が空で、unmatched.units に文書のページ等の範囲が入ります。
  • カーソルが壊れているときは 400、別の文書や、抽出し直す前の本文のカーソルのときは 409 を返します。後者は カーソルなしで読み直してください。

3 つとも、版（latestVersion が今のファイルの版、sourceVersion が本文の抽出元の版、describesLiveContent）を返します。 describesLiveContent が false のときは、ファイルが差し替えられて本文の抽出が追いついていないので、引用には sourceVersion を使ってください。

スキーマとデータクエリ

Section titled “スキーマとデータクエリ”

表形式のリソース（CSV/TSV と、レコードの一覧として読める JSON/GeoJSON。パイプラインでプレビュー Parquet を生成済み・≤100MB）は、列スキーマの取得と 読み取り専用 SQL クエリができます。AI エージェント向けには MCP の get_resource_schema / query_resource ツールも同等の機能を提供します。

スキーマ取得 — GET /resources/{id}/schema:

{
  "id": "…",
  "queryable": true,
  "primaryKey": null,
  "odataRefusal": null,
  "odataWideRows": false,
  "odataKey": { "names": ["RowId"], "synthetic": true, "fallback": "not-designated" },
  "schema": {
    "rowCount": 1688,
    "columns": [
      { "name": "市区町村（発生地）", "type": "string", "nullable": true, "nullCount": 3 },
      {
        "name": "重量制限",
        "type": "integer",
        "nullable": false,
        "nullCount": 0,
        "stats": { "min": "600", "max": "1350" }
      }
    ]
  },
  "columnRoles": [{ "role": "category" }, { "role": "measure" }]
}

odataRefusal・odataWideRows・odataKey は OData フィード（後述）のためのものです。odataRefusal はフィードが 出せない理由（not-public / unsupported-columns / duplicate-columns）と該当する見出し、 odataWideRows は行が広すぎてフィードの 1 ページが読めない恐れがあるか（拒否ではなく注意）、 odataKey はフィードが行を同定するキーです。フィードが無いリソースでは odataKey が、表そのものが無いリソースでは odataRefusal も null になります。

クエリ不可のリソース（非対応フォーマット・未処理）は queryable: false, schema: null を返します。 スキーマはあるがクエリの実体が無い場合（プレビューが削除済み・列ゼロのスキーマ・ 内容差し替え後にプレビューが未再生成）は、queryable: false のまま schema を返します。 primaryKey はリソースに確定された主キーの列名リスト（複合キーは指定順)で、未設定なら null です。 type は integer / float / boolean / string / date / timestamp。stats は数値列のみで、 整数の min/max は値の大きさによらず常に十進文字列、小数の min/max は数値です（範囲が 2^53 を超えても桁を 失わないように、型を列の type だけで決めています。/query の行の値は、2^53 未満の整数が数値になる点が違います）。 columnRoles は schema の列と同じ位置に並ぶ各列の役割（measure / numeric-text / identifier / free-text / name / category / empty）で、役割を判定する前に解釈された表では null です。 規則がそう判定した根拠は返しません — 根拠は GET /resources/{id}/column-roles（editor 限定）で読めます。

droppedRows は、この表の行ではないファイル内の行数です — 短く書かれた注記はリーダーが 受け付けず、列数まで空セルで埋められた注記は表の側で取り除かれます。どちらも数えます。受け付けないことが、そうした 1 行のためにファイル全体の 列を失わないための仕組みです。79 列のファイルに 2 列の行が 1 つあるだけで、CSV スニファーは 区切り文字の判定を諦め、ファイル全体を 1 列のテキストとして読んでしまいます。値が無い場合は 「該当なし」か、この数値ができる前に書かれたスキーマです。

droppedLines は受け付けなかった行の位置を先頭から順に返します。番号は CSV リーダーの 数え方で、ファイル先頭から 1 基準（見出しと読み飛ばしたタイトル行も含む）。引用符内に改行を持つ レコードは 1 行として数えます。表の側で取り除かれた注記には返せる行番号がありません — その時点では空行は消え、引用符内改行はレコードを 1 行に畳んでいるためです。したがってこの配列は droppedRows より短いことも、件数があるのに空のこともあります。上限も付いています。

受け付けなかった行を注記と推定したかどうかが、表を作るかどうかを決めます。 注記と推定した行は 落として表を返し、それ以外の受け付けなかった行があれば表を作りません — schema.columns は空、 noTableReason は ragged-rows、droppedLines が見るべき行を指します。

どちらであるかは推定で、材料は行の形だけです。値をいくつ持つかと、表が列をいくつ持つかの 関係を見ます。31 列の表に値 2 つの行は、29 フィールドを失った行というより注記と読みます。3 列の表に 値 2 つは、行が壊れるごく普通の形なので拒否します。値の数はパーサーが数えるので、区切り文字を含む 引用セルは 1 つと数えます。位置も型も見ません — 切れたデータ行は注記と まったく同じ位置に現れ、値が壊れた行は散文と同じくどの cast にも失敗するからです。

これは推定であって保証ではありません。 6 列のうち 3 セルまで書かれて切れた行は、この規則では 注記と読まれて落ちます。ファイル内にこの 2 つを区別する材料は無いので、droppedRows / droppedLines がその推定を利用者の目に触れさせるためにあります。拒否されたファイルも保存されダウンロードでき、修正後の再実行で表ができます。

データクエリ — POST /resources/{id}/query:

ターミナルウィンドウ
curl -X POST https://your-kukan-site/api/v1/resources/{id}/query \
  -H 'Content-Type: application/json' \
  -d '{"sql": "SELECT \"市区町村（発生地）\" AS city, count(*) AS n FROM data GROUP BY 1 ORDER BY n DESC LIMIT 3"}'
{
  "id": "…",
  "columns": ["city", "n"],
  "rows": [
    { "city": "足立区", "n": 117 },
    { "city": "江戸川区", "n": 110 },
    { "city": "大田区", "n": 86 }
  ],
  "rowCount": 3,
  "truncated": false,
  "elapsedMs": 31
}

クエリのルール:

  • データは data という名前のテーブルとして参照します。列名に空白や非 ASCII を含む場合は二重引用符で囲みます。
  • 単一の SELECT / WITH 文のみ。INSERT / UPDATE / DELETE / CREATE / DROP / ATTACH / COPY / PRAGMA 等の書き込み・DDL は拒否されます。
  • PIVOT には、列にする値を IN (…) で明示してください（PIVOT data ON col IN ('a', 'b') USING sum(v)）。省くと DuckDB がクエリの前に型を作る文を足すため、2 文目として拒否されます。
  • 使い捨ての in-memory DuckDB 上で実行され、ファイル・URL・拡張ロード等の外部アクセスは全面的に禁止されます。
  • 整数は数値で返します。ただし、倍精度の浮動小数点数で正確に表せない値（絶対値が 2^53 以上）は、その値だけ文字列で返します。同じ列に数値と文字列が混ざりうるので、受け取る側は両方を扱えるようにしてください。DECIMAL は精度を保つため文字列、日付・時刻も文字列です。

制限とエラー:

項目 値
最大行数 10,000（超過時は truncated: true）
最大結果サイズ 5 MB
実行タイムアウト 15 秒（408）
同時実行 1 つのサーバーで 1 つずつ順に実行。呼び出し元ごとに、実行中と待ち行列を合わせて匿名は 4（送信元アドレスごと、IPv6 は /64 単位）、サインイン済みは 2 まで（超過時 429）
エラー 状況
400 SQL 不正・非 SELECT・長さ超過・クエリ不可リソース
404 リソース不存在 / 非公開で権限なし
408 実行タイムアウト
429 呼び出し元ごとの上限を超えた、または待ち行列が満杯。Retry-After の秒数を待って再試行する

OData フィード（BI ツール向け）

Section titled “OData フィード（BI ツール向け）”

表形式リソースは OData v4 の読み取り専用フィードとしても配信されます。URL を Tableau・ Power BI・Excel などの OData コネクタに貼ると、そのまま表として開けます。/api/v1 の下では なく、独立した URL 空間です。

メソッド パス 内容
GET /odata/v1/resources/{id} サービス文書（エンティティセット一覧）
GET /odata/v1/resources/{id}/$metadata CSDL（列名と型、キーの宣言）
GET /odata/v1/resources/{id}/Rows 表本体（ページング）
GET /odata/v1/resources/{id}/Rows/$count 行数（プレーンテキスト）
ターミナルウィンドウ
curl 'https://your-kukan-site/odata/v1/resources/{id}/Rows?$top=2'
  • 公開リソースのみ・認証不要です。非公開リソースは所有者にも 404 を返します
  • ページングは @odata.nextLink で続きます。1 ページの大きさは一定ではなく、 65,536 行・8MB・プレビューの行グループ境界のいずれか先に来たところで区切られます （行グループは読み出しの最小単位で、跨ぐと展開量が倍になるため）。次リンクには 版の指紋が付き、抽出の途中でファイルが差し替わると古い指紋のページは 410 Gone になります（版が混ざった表を返さないため）
  • $select / $filter / $orderby / $apply / $search / $expand は未対応で、 指定すると 501 を返します。黙って無視すると、利用者は絞り込んだつもりの全件を 受け取ることになるためです
  • 行の同定は、公開者が指定した主キーが OData の条件を満たせばその列、満たさなければ 行の位置を持つ RowId 列が足されます。どちらになったかは /schema の odataKey に出ます
  • 見出しが EDM 識別子にならないリソース（括弧・空白・記号などを含む見出し）は 501 を返します。 理由は /schema の odataRefusal で確認できます
  • $metadata は毎回再検証されます（public, no-cache）。列の宣言が古いまま新しい行と 組み合わされるのを防ぐためです
  • 同時に読めるページは送信元アドレスごと（IPv6 は /64 単位）に 4 まで（実行中と待ち行列を合わせる）。超えると 429 を返すので、Retry-After の秒数を待って再試行する

バージョンと差分

Section titled “バージョンと差分”

リソースのファイルが差し替わると、差し替え前の内容が版として保存されます。内容が変わらない 限り版は増えません。

版の一覧 — GET /resources/{id}/versions（新しい順）:

{
  "id": "…",
  "versions": [
    {
      "version": 2,
      "origin": "upload",
      "state": "active",
      "isLive": true,
      "purgeFallsBackTo": 1,
      "format": "CSV",
      "size": 20481,
      "hash": "…",
      "schema": { "rowCount": 1688, "columns": [] },
      "noTableReason": null,
      "keyColumns": ["注文番号", "明細番号"],
      "created": "2026-08-01T09:12:44.000Z",
      "purgedAt": null
    }
  ]
}
フィールド 説明
origin upload（明示的な差し替え） / fetch（外部 URL の取得時点）
state active / superseded（旧方式の巻き戻しが残した行のみ。新しく書かれることはない） / purging / purged
isLive そのリソースが今配信している版か。version や state からは決まりません
purgeFallsBackTo この版をパージしたとき配信が戻る版。isLive の版だけに入ります（他の版のパージでは配信が動かないため）
format その版が確定した時点のフォーマット。リソースのラベルを変えても変わりません
schema その版の列スキーマ（表形式のみ）。版ごとに凍結されます
noTableReason 表が作れなかった理由（no-columns / too-many-columns / too-large / out-of-memory / timed-out / ragged-rows / not-records）
keyColumns その版の行を同定した主キー列。主キーなしで読まれた版は null。リソースの現在の設定は「次の版が何で読まれるか」なので別物です

完全削除済み（purged）の版は記録として残りますが、size / hash / schema / keyColumns は null になり、 purgedAt が入ります。ダウンロードは 404 を返します。keyColumns を伏せるのは、主キーが内容の 持つ列にしか設定できず、その名前が伏せた schema の部分集合になるためです（format は閉じた語彙 なので残ります）。パージの理由は返しません — 消した内容についての自由記述であり、この エンドポイントはリソースと同じ範囲で読めるためです。誰が何をいつどんな理由でパージしたかは監査 ログにあります。

差分 — GET /resources/{id}/versions/{v}/diff?from={v'}（既定の from は直前の版）:

対象データセットの editor 権限が必要です（両方のスナップショットを全走査するため、公開 エンドポイントにはしていません）。

{
  "available": true,
  "from": 1,
  "to": 2,
  "schemaChanged": false,
  "keyed": false,
  "addedRows": 42,
  "removedRows": 3,
  "sampleAdded": [{ "市区町村": "足立区", "件数": 117 }],
  "sampleRemoved": []
}
  • keyed は両端が同じ主キーで読まれたときだけ true になり、そのとき changedRows と sampleChangedAfter / sampleChangedBefore が加わります（2 つの見本は位置で対応し、変更前の側は 実際に値が変わった列だけを持ちます — 主キーは一致しているので両側にあり、値が動かなかった列は 含まれません。見本のセルは表示用に切り詰められるため、両者を比べても変わったかどうかは判定できません。 列が変更前の側にあるかどうかが答えです）。主キーが指定されていない・両端で違う場合は false で、 1 行の書き換えは追加 1 行 + 削除 1 行として現れます（行を同定できないため）
  • 見本の値は POST /resources/{id}/query と同じ規則で返します（整数は数値、絶対値が 2^53 以上の値だけ文字列）
  • 列構成が変わった版どうしは {"schemaChanged": true, "schemaDiff": {"added": [], "removed": [], "retyped": []}} を返し、行差分は行いません
  • 差分を出せない場合は {"available": false, "reason": "…", "from": …, "to": …, "reasonVersion": …} を返します。 reason は no-previous-version / not-ingested / purged / key-missing / key-null / key-not-unique / ingest-failed。key-* の 3 つは指定した主キーがその版の行を同定できず 取り込まれなかったことを、ingest-failed は取り込みを繰り返し試みて断念したことを 意味します。not-ingested は原因ではありません — 片端に行レベルのスナップショットが 無く、主キー由来の理由も無い、というだけで、版の作成から取り込みが走るまでの通常の待ち時間も 含みます。原因が版側に記録されていてもこの理由になります — 解釈が決める 4 つは noTableReason にあり、そちらが答えます
  • reasonVersion は その理由がどちらの版についてのものかです。開いた版とは限りません — 主キーを直した次の版を開けば断られたのは直前の版ですし、not-ingested も片端の性質です。 比較対象が無い（no-previous-version）場合と、どちらの端が墓標でも同じく比較が成立しない パージの場合だけ null になります
  • SQL はサーバーが版番号だけから組み立てます。POST /resources/{id}/query のサンドボックスとは 別経路で、利用者の SQL がこの領域に到達することはありません
  • 応答は Cache-Control: private, max-age=60, must-revalidate。取得できなかった応答は キャッシュされません
エラー 状況
401 未認証
403 対象データセットの editor 権限が無い
404 リソースまたは版が存在しない
408 差分の実行タイムアウト
429 呼び出し元ごとの上限を超えた、または待ち行列が満杯（クエリと共用）。Retry-After の秒数を待って再試行する

版の完全削除 — POST /resources/{id}/versions/{v}/purge（sysadmin 限定）:

理由が必須で、監査ログに記録されます。版を確保して 202 を返し、実際の消去はワーカーが 非同期に行います。同じ版への再実行は冪等です。

ターミナルウィンドウ
curl -X POST https://your-kukan-site/api/v1/resources/{id}/versions/2/purge \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"reason": "個人情報の混入"}'

巻き戻し — POST /resources/{id}/revert:

処理を中止し、リソースの内容を指定の版へ戻します。

{ "restoreTo": 2, "ifLiveRevision": "018f…-…-…" }
  • restoreTo は戻し先の版番号です（何段戻すかではありません）。null はリソースを ファイルの無い状態にします
  • ifLiveRevision は GET /resources/{id}/pipeline-status が返す live_revision です。 これにより、応答を組み立てている間に別のアップロードが入った場合、その内容を巻き戻して しまうことがありません
  • 同じ pipeline-status が revert_target（戻し先の既定値）も返します

巻き戻した後、プレビューと検索索引が古いままになることがあります。その場合は POST /resources/{id}/run-pipeline に {"rebuildOnly": true} を付けて再構築します （外部 URL からの再取得は行われません）。

列設定

Section titled “列設定”

そのリソースの行を同定する主キー。指定すると版差分が変更行を数えるようになります（keyed: true。 指定が無ければ 1 行の書き換えは追加 1 行 + 削除 1 行として現れます）。3 つとも editor 権限が 必要です — これはデータの説明ではなく、人が列について確定した決定だからです。

読み取り — GET /resources/{id}/column-settings:

{
  "id": "…",
  "primaryKey": ["注文番号"],
  "carried": false,
  "schema": {
    "rowCount": 1688,
    "columns": [{ "name": "注文番号", "type": "string", "nullCount": 0, "unique": true }]
  }
}
  • schema は live 版が凍結した解釈です — PUT が検証に使うのと同じ列なので、この一覧から 選んだ主キーが「その列は無い」で断られることはありません
  • unique は単独で行を同定できる列を示します。その列を選ぶなら確認は不要です。組み合わせに ついては何も言いません — 複合キーは実データを読まないと分かりません
  • carried は、最新の生きている版がまだ primaryKey で読まれていない間 false です。 主キーを確定してから再構築が着くまでの通常の状態であって、異常ではありません

確認 — POST /resources/{id}/column-settings/check、ボディ {"primaryKey": [...]}:

{ "id": "…", "checked": true, "primaryKey": ["注文番号"], "fault": "key-not-unique" }
  • fault は通る場合 null、断られる場合は key-missing / key-null / key-not-unique
  • {"checked": false, "reason": "no-preview" | "preview-stale"} は確かめられなかったという 意味です（読める解釈が無い）。エラーではありません — PUT は内容を一切読まないので、 この状態でも主キーは確定できます
  • 単一列キーは版が凍結した列ごとの数から、複合キーは解釈の Parquet を読んで答えます

確定 — PUT /resources/{id}/column-settings、ボディ {"primaryKey": [...] | null}:

{ "id": "…", "primaryKey": ["注文番号"], "queued": true }
  • [] と null はどちらも「主キーなし」です。ボディの側で 1 つの綴りに正規化されます
  • 列は指定した順序で保持されます。ただし行の照合は順序によりません — キーを使う操作は いずれも列を AND で並べるためです。それでも順序は記録されるキーの一部なので、同じ列を別の順序で 指定すると別のキーとして扱われ、版が 1 つ作られます
  • 主キーの確定は版を作ります。 版とは「このバイト列を、この読み方で」であり、主キーは読み方の 一部だからです。バイト列は動かないので、新しい版は同じ内容の複製を所有します。queued はその版を 発行する再構築が投入されたことを示し、null は再構築が不要だったことを示します。false は 設定は保存できたが再構築を投入できなかったことを示します — 書き込みと投入は別々に判断されるので、 同じボディを再送すれば修復できます。設定と最新版の食い違いを掃除する仕組みは無いため、false を 無視すると、どの版もその主キーで読まれないまま残ります
  • 既に層 2 に入っている版を新しい主キーで読み直すことはしません。 境界は版そのものであり、 それをまたぐ差分は行全体の比較に縮退します

列の役割

Section titled “列の役割”

列の役割は、その列の値を検索でどう扱うかと、公開ページのフィールド一覧の表示を決めます。名称と カテゴリの列は値の一覧として、自由記述の列は行の文脈を添えた文として索引され、それ以外は検索に使われません。 役割は列の値と項目名から自動で判定されます。

GET /resources/{id}/column-roles（editor 権限が必要）は、各列の役割と、そう判定した根拠を返します:

{
  "columns": [
    {
      "name": "定員",
      "type": "string",
      "role": "numeric-text",
      "roleBasis": { "rule": "number-shape", "share": 0.92, "examples": ["-", "1,000"] }
    },
    { "name": "区分", "type": "string", "role": "category", "roleBasis": { "rule": "other" } }
  ]
}
  • roleBasis.rule は判定した規則、share はその規則が数えた値の割合です
  • numeric-text の examples は、数値として読めない値（公開する人が直す対象）です
  • 役割がまだ判定されていない表では columns が null です
  • 今のバージョンでは読み取りのみです。役割の上書きは将来のバージョンで対応する予定です

AI による説明の非表示

Section titled “AI による説明の非表示”

PUT /resources/{id}/summary、本文 {"hidden": true} で、AI による説明をページから外します。{"hidden": false} で戻します。

  • 本文は消えません。 戻したときに同じ文が出ます
  • 非表示にすると、表示だけでなく検索インデックスと埋め込みからも外れます — 取り下げた文が検索に答え続けることがないようにするためです
  • 非表示のものはパイプラインが再生成しません

組織 (organizations)

Section titled “組織 (organizations)”
Method Path 説明 認証
GET /organizations 組織一覧 公開
POST /organizations 組織作成 sysadmin
GET /organizations/{nameOrId} 組織詳細 公開
PUT /organizations/{nameOrId} 組織更新（全フィールド置換） 組織 admin
DELETE /organizations/{nameOrId} 組織論理削除 組織 admin
POST /organizations/{nameOrId}/restore 論理削除済みを復元 sysadmin
POST /organizations/{nameOrId}/purge 論理削除済みを完全削除（ジョブキュー経由、非同期） sysadmin
GET /organizations/{nameOrId}/members メンバー一覧 組織 member
POST /organizations/{nameOrId}/members メンバー追加・ロール変更 組織 admin
DELETE /organizations/{nameOrId}/members/{userId} メンバー削除 組織 admin

メンバーのロールは admin / editor / member のいずれか。

カテゴリー (groups)

Section titled “カテゴリー (groups)”
Method Path 説明 認証
GET /groups カテゴリー一覧 公開
POST /groups カテゴリー作成 sysadmin
GET /groups/{nameOrId} カテゴリー詳細 公開
PUT /groups/{nameOrId} カテゴリー更新（全フィールド置換） カテゴリー admin
DELETE /groups/{nameOrId} カテゴリー削除 カテゴリー admin
POST /groups/{nameOrId}/restore 論理削除済みを復元 sysadmin
POST /groups/{nameOrId}/purge 論理削除済みを完全削除 sysadmin
GET /groups/{nameOrId}/members メンバー一覧 カテゴリー member
POST /groups/{nameOrId}/members メンバー追加・ロール変更 カテゴリー admin
DELETE /groups/{nameOrId}/members/{userId} メンバー削除 カテゴリー admin

本文の箇所 (passages)

Section titled “本文の箇所 (passages)”
Method Path 説明 認証
GET /passages 文書の本文から検索語に一致する箇所を、出典とページ付きで取得（閲覧可能な範囲のみ） 公開

MCP の search_passages と同じ検索です。パラメータは q（必須、500 字まで）、organization、tags[]（tags でも可）、 k（デフォルト: 5、最大: 20）、per_resource（デフォルト: 2）、max_chars（デフォルト: 8,000、最大: 32,000）、 semantic（false でキーワード一致のみ）。すべての語を持つデータセットが無いときは、語の少ない一致に 緩めて文書を探し、応答に minWords（一致に求めた語の数）を付けます。各箇所は、リソースとデータセット、位置（first / last のページ・ スライド・シート、headings）、一致した語（words）、本文（text）、その箇所の ページの先頭（長いブロックでは箇所そのもの）から続きを読むためのカーソル（cursor、/resources/{id}/document-section に渡す）と開始位置（readFrom）、版（latestVersion が今のファイルの版、sourceVersion が本文の抽出元の版）を持ちます。 describesLiveContent が false のときは、ファイルが差し替えられて本文の抽出が追いついていないので、引用には sourceVersion を使ってください。

タグ (tags)

Section titled “タグ (tags)”
Method Path 説明 認証
GET /tags タグ一覧 公開
GET /tags/{id} タグ詳細 公開

GET /tags のパラメータは q（名前の部分一致）、offset、limit（既定 100、上限 100）、 orderBy（name＝名前順〈既定〉、datasetCount＝データセット数の多い順）です。 並び順が決まっているので、offset でページを送っても重複・抜けは起きません。

ユーザー (users)

Section titled “ユーザー (users)”
Method Path 説明 認証
GET /users/me 自分の情報 認証
GET /users/me/organizations 所属組織一覧 認証
GET /users/me/groups 所属カテゴリー一覧 認証
GET /users ユーザー検索（メンバー管理用） 認証

API トークン (api-tokens)

Section titled “API トークン (api-tokens)”
Method Path 説明 認証
POST /api-tokens トークン発行 認証
GET /api-tokens 自分のトークン一覧 認証
DELETE /api-tokens/{id} トークン失効 認証

お知らせ (announcements)

Section titled “お知らせ (announcements)”
Method Path 説明 認証
GET /announcements お知らせ一覧（公開済みのみ。sysadmin は publishedOnly=false で未公開も含む） 公開
GET /announcements/{id} お知らせ詳細（未公開は sysadmin のみ） 公開
POST /announcements お知らせ作成 sysadmin
PUT /announcements/{id} お知らせ更新（全フィールド置換） sysadmin
DELETE /announcements/{id} お知らせ削除 sysadmin

管理 (admin)

Section titled “管理 (admin)”

すべて sysadmin 限定。

Method Path 説明
GET /admin/search/stats 検索インデックス統計（件数・サイズ・DB カウント）
GET /admin/search/doc/{index}/{id} インデックスドキュメント取得（index: packages / resources / contents）
GET /admin/search/browse/{index} インデックスドキュメント一覧（ページング・検索対応）
GET /admin/search/chunks/{resourceId} リソースの本文チャンク一覧
POST /admin/reindex-metadata 検索インデックスの再構築（{ includeContent: true } で全リソースを保存済みファイルから再処理する。進行中なら 409。{ reindexContent: true } で本文の索引だけを保存済みの解釈から作り直す。両方は指定できない。ジョブキュー経由、非同期）
POST /admin/reindex-embeddings 全リソースの埋め込みベクトルを作り直す（本文とモデルが変わっていないものは再計算しない。ジョブキュー経由、非同期）
GET /admin/embedding-status 意味検索から届かないリソース数（埋め込みベクトル未作成・モデル不一致、{ missing }）
GET /admin/search/analysis-status 日本語解析の設定が更新され再解析が要るか（{ stale }）
POST /admin/search/reanalyse 新しい解析設定でインデックスを作り直す（ジョブキュー経由、非同期）
GET /admin/search/chunk-status 以前の大きな単位で本文が索引されているリソース数（{ resources }）
GET /admin/summary-estimate AI による説明の一括生成の対象件数・推定トークン・推定費用
POST /admin/generate-summaries AI による説明の一括生成（{ refresh } で書き直しも含む。ジョブキュー経由、非同期）
GET /admin/version-backfill-status 移行作業の残件数（層1: 版なし / 層2: 差分未取り込み / 旧方式の巻き戻しの未変換）
POST /admin/backfill-versions 一度きりの移行（版の補完・旧方式の巻き戻しの変換）を予約（ジョブキュー経由、非同期）
GET /admin/row-group-status 行グループ未記録のプレビュー数
POST /admin/record-row-groups プレビューの行グループ記録を予約（ジョブキュー経由、非同期）
POST /admin/jobs/enqueue-all 全リソースのパイプライン一括予約（再処理が進行中なら 409）
GET /admin/jobs/stats リソースの処理状況の集計（reprocessPending: 全リソースの再処理が進行中か）
GET /admin/jobs リソースの処理状況一覧（status はカンマ区切り）
GET /admin/queue/counts 種類と状態ごとのジョブの件数（予約・待機・処理中・打ち切り）
GET /admin/queue/jobs ジョブ一覧（status と type で絞り込み、offset / limit）
POST /admin/queue/jobs/:id/retry 打ち切りのジョブを試行回数を戻して再投入
DELETE /admin/queue/jobs/:id 打ち切りのジョブを削除
GET /admin/settings ランタイム設定の一覧
PUT /admin/settings/{key} ランタイム設定を 1 件更新（{ value }）
GET /admin/settings/vector-search ベクトル検索の状態（モデル・しきい値）
GET /admin/settings/ai-suggest AI 提案の状態（プロバイダー・モデル）
POST /admin/settings/ai-suggest/test AI 提案モデルの接続テスト
DELETE /admin/data 全データ削除（ユーザー除く）
GET /admin/health/stats ヘルスチェック統計
GET /admin/health ヘルスチェック結果一覧
GET /admin/users/stats ユーザー統計
GET /admin/users ユーザー一覧
POST /admin/users ユーザー作成
PATCH /admin/users/{userId} ユーザー更新
DELETE /admin/users/{userId} ユーザー論理削除（セッション・トークン即時失効）
POST /admin/users/{userId}/restore ユーザー復元
POST /admin/users/{userId}/purge ユーザー完全削除
GET /admin/analytics/{report} アクセス統計（GA4。report は dataset-views / resource-views / downloads / search-terms、startDate / endDate で期間指定、GA4 未設定なら 404）

その他

Section titled “その他”
Method Path 説明 認証
GET /api/health ヘルスチェック 公開
GET /api/v1/site/settings サイト設定（登録可否・サイトのメタデータ等） 公開