Zum Inhalt springen
Diese Seite ist in Ihrer Sprache noch nicht verfügbar. Englische Version wird angezeigt.

API Overview

HTTP API reference for Potato — admin endpoints for managing annotators, triggering exports, querying progress statistics, and integrating with external pipelines.

Potato provides HTTP API endpoints for integration with custom frontends, automation scripts, or external systems.

Overview

Base URL

text
http://localhost:8000

Authentication

Most endpoints require an active session established via the login endpoints and maintained via cookies.

For programmatic access:

  1. Use session cookies from a browser
  2. Use debug mode with automatic user creation
  3. Implement the login flow programmatically

Response Format

All API endpoints return JSON responses. Error responses include an error field.

Session Management

Login

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

Check Session

http
GET /api/current_instance

Response:

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

Logout

http
POST /logout

Annotation Endpoints

Get Current Instance

http
GET /api/current_instance

Returns information about the user's current annotation instance.

Get Instance Content

http
GET /api/spans/{instance_id}

Returns the text content and existing span annotations.

Response:

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"
    }
  ]
}

Get Annotations

http
GET /get_annotations?instance_id={instance_id}

Returns all annotations for a specific instance.

Submit Annotation

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"
    }
  ]
}

Response (Success):

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

Response (With Quality Control):

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"}

Or by action:

json
{"action": "next_instance"}

Schema Information

Get Annotation Schemas

http
GET /api/schemas

Get Label Colors

http
GET /api/colors

Get Keyword Highlights

http
GET /api/keyword_highlights/{instance_id}

Admin API Endpoints

Admin endpoints require admin privileges.

Health Check

http
GET /admin/health

Dashboard Overview

http
GET /admin/api/overview

Response:

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

Get Annotators

http
GET /admin/api/annotators

Get Instances

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

Get Configuration

http
GET /admin/api/config

Update Configuration

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

Quality Control API

Quality Control Metrics

http
GET /admin/api/quality_control

Returns attention check and gold standard statistics.

Agreement Metrics

http
GET /admin/api/agreement

Returns Krippendorff's alpha by schema.

AI Assistant API

Get AI Suggestion

http
GET /get_ai_suggestion?instance_id={instance_id}

Get AI Assistant Help

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

Model Training API

New in v2.14.0

With model_training.enabled: true, Potato registers 26 training operations, and the OpenAPI spec lists every one. The admin routes sit under /admin/training and need admin access, from an admin session or the X-API-Key header. POST and DELETE requests from a browser must come from the same origin.

RoutePurpose
GET /admin/trainingThe Training page
GET /admin/training/api/trainersEvery trainer, with the scheme kinds and media the trainer handles, the trainer's license, and whether the trainer is installed
GET /admin/training/api/schemasThe study's schemes and the trainers that fit each one
GET /admin/training/api/statusThe current or last run, with progress, metrics, warnings, the write-back report, and the queue
GET /admin/training/api/runsRun history (?limit=, default 50)
POST /admin/training/api/runsStart a run
POST /admin/training/api/runs/<run_id>/cancelCancel the run in progress or a waiting run
DELETE /admin/training/api/runs/<run_id>/predictionsWithdraw a run's pre-labels

Start a run with a trainer and a list of schemes:

bash
curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  http://localhost:8000/admin/training/api/runs \
  -d '{"trainer": "sklearn-text", "schemas": ["sentiment"]}'

The response is 200 when the run starts and 202 with queued: true when the run waits behind another one. A refused start returns 400, 409, or 429, with the reason in error. Remote training agents use a second set of routes under /api/training, authenticated with Authorization: Bearer <token>. Model training configuration lists every route with the route's request body and status codes.

Example: Complete Annotation Flow

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"})

Example: Admin Monitoring

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}")

Error Responses

All endpoints may return error responses:

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

Common HTTP status codes:

  • 400 - Bad Request (invalid parameters)
  • 401 - Unauthorized (no session)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Not Found
  • 500 - Internal Server Error

Further Reading

For implementation details, see the source documentation.