# KP Court 公開 API 參考

## Overview

Base URL：

- 本機：`http://127.0.0.1:8093`
- 公開：`https://dsfp2lltjlsc9.cloudfront.net`

這份公開 API 是唯讀、machine-first 的 court oral arguments 入口，目標是讓外部 AI、研究者與開發者能在不整包載入全文的前提下，按案號、庭期、人物、爭點與段落做查詢。

目前公開資料來自結構化 JSONL 輸出：

- `cases.jsonl`
- `sessions.jsonl`
- `segments.jsonl`
- `entities.jsonl`
- `events.jsonl`

## 給受限 AI 工具的建議探索路徑

如果你的工具只能抓少量頁面，建議不要一開始就暴力掃整站，而是沿著 `_links` 前進：

1. 先抓 `GET /cases/{case_id}`。
2. 讀取回應中的 `_links.sessions`，再進到該案的 sessions。
3. 在 session payload 中繼續讀 `_links.segments`，取得該庭期的段落清單。
4. 若已知 segment 或需要回看單筆內容，再跟著 `_links.self` 進一步抓取。

這種做法比直接猜 endpoint 更穩定，也更符合本公開層的 hypermedia 設計。

## 資料欄位說明

### Raw 與 canonical 欄位

部分欄位同時提供原始值與標準化值：

- `participants_raw`
- `participants`
- `legal_issues_raw`
- `legal_issues`

建議用法：

- `_raw` 欄位：保留原始擷取語意，適合 traceability、debug、citation context
- canonical 欄位：適合 search、aggregation、retrieval、AI query

### Filter semantics

API filter semantics 和本地 CLI 一致：

- 同一 filter type 內部是 **OR**
- 不同 filter type 之間是 **AND**

例如：

- `?participant=柯文哲&participant=沈慶京`
  - 代表任一 participant 命中即可
- `?participant=柯文哲&issue=工作簿/帳冊真實性`
  - 代表兩個條件都要成立

如果 `limit` 省略，HTTP API 預設會使用 `20`。

## 公開文件路由

API 也會直接提供文件本身，方便遠端 AI 抓取：

- `GET /public-docs`
- `GET /public-docs/README.md`
- `GET /public-docs/API.md`

## Endpoints

### `GET /public-docs`

列出可取得的公開文件。

範例：

```bash
curl -sS 'https://dsfp2lltjlsc9.cloudfront.net/public-docs'
```

典型回應：

```json
{
  "title": "公開文件",
  "docs": [
    {
      "name": "README.md",
      "url": "/public-docs/README.md"
    },
    {
      "name": "API.md",
      "url": "/public-docs/API.md"
    }
  ]
}
```

### `GET /public-docs/README.md`

回傳 public access 的導覽文件（Markdown）。

### `GET /public-docs/API.md`

回傳這份 API 參考文件（Markdown）。

### `GET /cases/{case_id}`

回傳單一案件的 case payload。

範例：

```bash
curl -sS 'https://dsfp2lltjlsc9.cloudfront.net/cases/113%E5%B9%B4%E5%BA%A6%E9%87%91%E8%A8%B4%E5%AD%97%E7%AC%AC51%E8%99%9F'
```

典型回應：

```json
{
  "case_id": "113年度金訴字第51號",
  "case_number": "113年度金訴字第51號",
  "phases": ["言詞辯論"],
  "record_type": "case",
  "session_count": 1,
  "session_ids": ["0KeURwJSR_Q"],
  "_links": {
    "self": "https://dsfp2lltjlsc9.cloudfront.net/cases/113年度金訴字第51號",
    "sessions": "https://dsfp2lltjlsc9.cloudfront.net/cases/113年度金訴字第51號/sessions",
    "entities": "https://dsfp2lltjlsc9.cloudfront.net/entities?case_id=113年度金訴字第51號",
    "events": "https://dsfp2lltjlsc9.cloudfront.net/events?case_id=113年度金訴字第51號",
    "search_segments": "https://dsfp2lltjlsc9.cloudfront.net/segments/search?case_id=113年度金訴字第51號"
  }
}
```

### `GET /cases/{case_id}/sessions`

回傳某案的所有 session metadata，順序穩定。

範例：

```bash
curl -sS 'https://dsfp2lltjlsc9.cloudfront.net/cases/113%E5%B9%B4%E5%BA%A6%E9%87%91%E8%A8%B4%E5%AD%97%E7%AC%AC51%E8%99%9F/sessions'
```

典型回應會帶有 `_links`，方便沿著 case -> session -> segment 的路徑前進：

```json
[
  {
    "session_id": "0KeURwJSR_Q",
    "case_id": "113年度金訴字第51號",
    "record_type": "session",
    "_links": {
      "self": "https://dsfp2lltjlsc9.cloudfront.net/sessions/0KeURwJSR_Q",
      "segments": "https://dsfp2lltjlsc9.cloudfront.net/sessions/0KeURwJSR_Q/segments",
      "search_segments": "https://dsfp2lltjlsc9.cloudfront.net/segments/search?session_id=0KeURwJSR_Q",
      "case": "https://dsfp2lltjlsc9.cloudfront.net/cases/113年度金訴字第51號"
    }
  }
]
```

### `GET /sessions/{session_id}`

回傳單一庭期 / 影片的 session payload。

範例：

```bash
curl -sS 'https://dsfp2lltjlsc9.cloudfront.net/sessions/0KeURwJSR_Q'
```

典型回應會把可探索的下一步都放進 `_links`：

```json
{
  "session_id": "0KeURwJSR_Q",
  "case_id": "113年度金訴字第51號",
  "record_type": "session",
  "_links": {
    "self": "https://dsfp2lltjlsc9.cloudfront.net/sessions/0KeURwJSR_Q",
    "case": "https://dsfp2lltjlsc9.cloudfront.net/cases/113年度金訴字第51號",
    "segments": "https://dsfp2lltjlsc9.cloudfront.net/sessions/0KeURwJSR_Q/segments",
    "search_segments": "https://dsfp2lltjlsc9.cloudfront.net/segments/search?session_id=0KeURwJSR_Q"
  }
}
```

### `GET /sessions/{session_id}/segments`

回傳某個 session 底下的 segment rows，順序與 `limit` 行為都與其他列表端點一致。

範例：

```bash
curl -sS 'https://dsfp2lltjlsc9.cloudfront.net/sessions/0KeURwJSR_Q/segments?limit=5'
```

### `GET /segments/{segment_id}`

回傳單一 segment payload，包含 raw 與 canonical annotation 欄位（如果該資料集有）。

範例：

```bash
curl -sS 'https://dsfp2lltjlsc9.cloudfront.net/segments/0KeURwJSR_Q%3Achunk_0002'
```

典型回應會提供 `_links`，讓受限 AI 只要跟著 link 就能往上或往旁邊探索：

```json
{
  "segment_id": "0KeURwJSR_Q:chunk_0002",
  "session_id": "0KeURwJSR_Q",
  "case_id": "113年度金訴字第51號",
  "_links": {
    "self": "https://dsfp2lltjlsc9.cloudfront.net/segments/0KeURwJSR_Q:chunk_0002",
    "session": "https://dsfp2lltjlsc9.cloudfront.net/sessions/0KeURwJSR_Q",
    "case": "https://dsfp2lltjlsc9.cloudfront.net/cases/113年度金訴字第51號"
  }
}
```

### `GET /segments/search`

這是主要的 query-first retrieval endpoint。

支援 query params：

- `case_id`
- `session_id`
- `participant`（可重複）
- `issue`（可重複）
- `keyword`（可重複）
- `limit`

範例：

```bash
curl -sS 'https://dsfp2lltjlsc9.cloudfront.net/segments/search?case_id=113%E5%B9%B4%E5%BA%A6%E9%87%91%E8%A8%B4%E5%AD%97%E7%AC%AC51%E8%99%9F&participant=%E6%9F%AF%E6%96%87%E5%93%B2&issue=%E5%B7%A5%E4%BD%9C%E7%B0%BF%2F%E5%B8%B3%E5%86%8A%E7%9C%9F%E5%AF%A6%E6%80%A7&limit=5'
```

重複 filter 範例：

```bash
curl -sS 'https://dsfp2lltjlsc9.cloudfront.net/segments/search?participant=%E6%9F%AF%E6%96%87%E5%93%B2&participant=%E6%B2%88%E6%85%B6%E4%BA%AC&limit=10'
```

### `GET /entities`

回傳 canonical entity rows。

支援 query params：

- `case_id`
- `q`
- `limit`

範例：

```bash
curl -sS 'https://dsfp2lltjlsc9.cloudfront.net/entities?case_id=113%E5%B9%B4%E5%BA%A6%E9%87%91%E8%A8%B4%E5%AD%97%E7%AC%AC51%E8%99%9F&q=%E6%9F%AF&limit=10'
```

### `GET /events`

回傳 canonical event rows。

支援 query params：

- `case_id`
- `event_type`
- `q`
- `limit`

範例：

```bash
curl -sS 'https://dsfp2lltjlsc9.cloudfront.net/events?case_id=113%E5%B9%B4%E5%BA%A6%E9%87%91%E8%A8%B4%E5%AD%97%E7%AC%AC51%E8%99%9F&event_type=legal_issue&q=%E5%B7%A5%E4%BD%9C%E7%B0%BF&limit=10'
```

### `GET /downloads/{table_name}.jsonl`

直接下載某一份公開 JSONL 表。

支援的 `table_name`：

- `cases`
- `sessions`
- `segments`
- `entities`
- `events`

範例：

```bash
curl -sS 'https://dsfp2lltjlsc9.cloudfront.net/downloads/segments.jsonl' | head
```

## Error behavior

常見錯誤：

- `404 case not found`
- `404 session not found`
- `404 segment not found`
- `404 table not found`
- `404 doc not found`

## MCP Access

公開 MCP server 會暴露相同的工具面：

- `get_case`
- `list_sessions`
- `get_session`
- `get_segment`
- `search_segments`
- `list_entities`
- `list_events`

目前公開 MCP endpoint：

- `https://dsfp2lltjlsc9.cloudfront.net/mcp`

這個 endpoint 使用 `streamable-http` transport。一般 `curl` 直接打會看到 `406 Not Acceptable`，這是正常的，代表 endpoint 活著，但你不是用 MCP client 在講。

## 建議的 AI 使用流程

對外部 AI 來說，最推薦的查詢順序是：

1. `get_case`
2. `list_sessions`
3. `list_entities` / `list_events`
4. `search_segments`
5. `get_segment`

這樣最省 token，也最符合 query-first 的設計目標，不需要一開始就把整個 oral-argument corpus 全部灌進 context。

如果工具本身支援 hypermedia，優先沿著 `_links.self`、`_links.sessions`、`_links.segments`、`_links.case` 前進，通常比自己硬拼 URL 更穩定。