Skip to content

API 概述

用於與 Potato 進行程式設計整合的 HTTP API 參考文件。

Potato 提供 HTTP API 端點，用於與自定義前端、自動化指令碼或外部系統進行整合。

概述

基礎 URL

text
http://localhost:8000

認證

大多數端點需要通過登入端點建立活躍會話，並通過 cookie 維持。

對於程式設計訪問：

  1. 使用瀏覽器中的會話 cookie
  2. 使用除錯模式並自動建立使用者
  3. 以程式設計方式實現登入流程

響應格式

所有 API 端點返回 JSON 響應。錯誤響應包含一個 error 欄位。

會話管理

登入

http
POST /auth
Content-Type: application/x-www-form-urlencoded
 
username=your_username&password=your_password

檢查會話

http
GET /api/current_instance

響應：

json
{
  "instance_id": "item_001",
  "current_index": 0,
  "total_instances": 100
}

登出

http
POST /logout

標註端點

獲取當前實例

http
GET /api/current_instance

返回使用者當前標註實例的資訊。

獲取實例內容

http
GET /api/spans/{instance_id}

返回文本內容和現有的片段標註。

響應：

json
{
  "instance_id": "item_001",
  "text": "The quick brown fox jumps over the lazy dog.",
  "spans": [
    {
      "id": "span_123",
      "schema": "entities",
      "label": "ANIMAL",
      "start": 16,
      "end": 19,
      "text": "fox",
      "color": "#ff6b6b"
    }
  ]
}

獲取標註

http
GET /get_annotations?instance_id={instance_id}

返回特定實例的所有標註。

提交標註

http
POST /updateinstance
Content-Type: application/json
 
{
  "instance_id": "item_001",
  "annotations": {
    "sentiment:positive": "1"
  },
  "span_annotations": [
    {
      "schema": "entities",
      "name": "PERSON",
      "start": 0,
      "end": 5,
      "value": "true"
    }
  ]
}

響應（成功）：

json
{
  "status": "success",
  "processing_time_ms": 15
}

響應（含品質控制）：

json
{
  "status": "success",
  "qc_result": {
    "type": "gold_standard",
    "correct": false,
    "gold_label": {"sentiment": "positive"}
  }
}

跳轉到實例

http
POST /go_to
Content-Type: application/json
 
{"go_to": "item_005"}

或通過操作：

json
{"action": "next_instance"}

模式資訊

獲取標註模式

http
GET /api/schemas

獲取標籤顏色

http
GET /api/colors

獲取關鍵詞高亮

http
GET /api/keyword_highlights/{instance_id}

管理員 API 端點

管理員端點需要管理員許可權。

健康檢查

http
GET /admin/health

儀表板概覽

http
GET /admin/api/overview

響應：

json
{
  "total_items": 1000,
  "total_annotations": 5000,
  "total_users": 25,
  "completion_rate": 0.45
}

獲取標註者

http
GET /admin/api/annotators

獲取實例

http
GET /admin/api/instances?status=completed&limit=100

獲取配置

http
GET /admin/api/config

更新配置

http
POST /admin/api/config
Content-Type: application/json
 
{"setting_name": "value"}

品質控制 API

品質控制指標

http
GET /admin/api/quality_control

返回注意力檢查和金標準統計資料。

一致性指標

http
GET /admin/api/agreement

返回按模式分類的 Krippendorff's alpha 值。

AI 助手 API

獲取 AI 建議

http
GET /get_ai_suggestion?instance_id={instance_id}

獲取 AI 助手幫助

http
GET /api/ai_assistant?instance_id={instance_id}&schema={schema_name}

示例：完整標註流程

python
import requests
 
BASE_URL = "http://localhost:8000"
session = requests.Session()
 
# 1. Login
session.post(f"{BASE_URL}/auth", data={
    "username": "annotator1",
    "password": "password123"
})
 
# 2. Get current instance
response = session.get(f"{BASE_URL}/api/current_instance")
instance_id = response.json()["instance_id"]
 
# 3. Get instance content
response = session.get(f"{BASE_URL}/api/spans/{instance_id}")
print(f"Text: {response.json()['text']}")
 
# 4. Submit annotation
session.post(f"{BASE_URL}/updateinstance", json={
    "instance_id": instance_id,
    "annotations": {"sentiment:positive": "1"}
})
 
# 5. Navigate to next instance
session.post(f"{BASE_URL}/go_to", json={"action": "next_instance"})

示例：管理員監控

python
import requests
 
BASE_URL = "http://localhost:8000"
 
# Get overview
overview = requests.get(f"{BASE_URL}/admin/api/overview").json()
print(f"Progress: {overview['completion_rate']*100:.1f}%")
 
# Get agreement metrics
agreement = requests.get(f"{BASE_URL}/admin/api/agreement").json()
print(f"Agreement: alpha = {agreement['overall']['average_krippendorff_alpha']:.3f}")

錯誤響應

所有端點可能返回錯誤響應：

json
{"error": "Description of the error"}

常見 HTTP 狀態碼：

  • 400 - 請求錯誤（無效參數）
  • 401 - 未授權（無會話）
  • 403 - 禁止訪問（許可權不足）
  • 404 - 未找到
  • 500 - 內部伺服器錯誤

延伸閱讀

有關實現細節，請參閱原始碼文件。