Skip to content

API 개요

Potato의 HTTP API 레퍼런스 — 어노테이터 관리, 내보내기 실행, 진행 통계 조회, 외부 파이프라인 연동을 위한 관리자 엔드포인트를 다룹니다.

Potato는 맞춤 프런트엔드, 자동화 스크립트, 외부 시스템과의 연동을 위한 HTTP API 엔드포인트를 제공합니다.

개요

기본 URL

text
http://localhost:8000

인증

대부분의 엔드포인트는 로그인 엔드포인트를 통해 설정되고 쿠키로 유지되는 활성 세션을 필요로 합니다.

프로그래밍 방식 접근의 경우:

  1. 브라우저의 세션 쿠키를 사용합니다
  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}

텍스트 콘텐츠와 기존 span 어노테이션을 반환합니다.

응답:

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 알파를 반환합니다.

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 - 내부 서버 오류

더 읽어보기

구현 세부 사항은 원본 문서를 참조하세요.