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
http://localhost:8000
Authentication
Most endpoints require an active session established via the login endpoints and maintained via cookies.
For programmatic access:
- Use session cookies from a browser
- Use debug mode with automatic user creation
- Implement the login flow programmatically
Response Format
All API endpoints return JSON responses. Error responses include an error field.
Session Management
Login
POST /auth
Content-Type: application/x-www-form-urlencoded
username=your_username&password=your_passwordCheck Session
GET /api/current_instanceResponse:
{
"instance_id": "item_001",
"current_index": 0,
"total_instances": 100
}Logout
POST /logoutAnnotation Endpoints
Get Current Instance
GET /api/current_instanceReturns information about the user's current annotation instance.
Get Instance Content
GET /api/spans/{instance_id}Returns the text content and existing span annotations.
Response:
{
"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
GET /get_annotations?instance_id={instance_id}Returns all annotations for a specific instance.
Submit Annotation
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):
{
"status": "success",
"processing_time_ms": 15
}Response (With Quality Control):
{
"status": "success",
"qc_result": {
"type": "gold_standard",
"correct": false,
"gold_label": {"sentiment": "positive"}
}
}Navigate to Instance
POST /go_to
Content-Type: application/json
{"go_to": "item_005"}Or by action:
{"action": "next_instance"}Schema Information
Get Annotation Schemas
GET /api/schemasGet Label Colors
GET /api/colorsGet Keyword Highlights
GET /api/keyword_highlights/{instance_id}Admin API Endpoints
Admin endpoints require admin privileges.
Health Check
GET /admin/healthDashboard Overview
GET /admin/api/overviewResponse:
{
"total_items": 1000,
"total_annotations": 5000,
"total_users": 25,
"completion_rate": 0.45
}Get Annotators
GET /admin/api/annotatorsGet Instances
GET /admin/api/instances?status=completed&limit=100Get Configuration
GET /admin/api/configUpdate Configuration
POST /admin/api/config
Content-Type: application/json
{"setting_name": "value"}Quality Control API
Quality Control Metrics
GET /admin/api/quality_controlReturns attention check and gold standard statistics.
Agreement Metrics
GET /admin/api/agreementReturns Krippendorff's alpha by schema.
AI Assistant API
Get AI Suggestion
GET /get_ai_suggestion?instance_id={instance_id}Get AI Assistant Help
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.
| Route | Purpose |
|---|---|
GET /admin/training | The Training page |
GET /admin/training/api/trainers | Every trainer, with the scheme kinds and media the trainer handles, the trainer's license, and whether the trainer is installed |
GET /admin/training/api/schemas | The study's schemes and the trainers that fit each one |
GET /admin/training/api/status | The current or last run, with progress, metrics, warnings, the write-back report, and the queue |
GET /admin/training/api/runs | Run history (?limit=, default 50) |
POST /admin/training/api/runs | Start a run |
POST /admin/training/api/runs/<run_id>/cancel | Cancel the run in progress or a waiting run |
DELETE /admin/training/api/runs/<run_id>/predictions | Withdraw a run's pre-labels |
Start a run with a trainer and a list of schemes:
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
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
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:
{"error": "Description of the error"}Common HTTP status codes:
400- Bad Request (invalid parameters)401- Unauthorized (no session)403- Forbidden (insufficient permissions)404- Not Found500- Internal Server Error
Further Reading
- Admin Dashboard - Web-based admin interface
- Quality Control - Quality metrics API
- Behavioral Tracking - Interaction tracking API
- Model Training Configuration - Training routes and the agent protocol
For implementation details, see the source documentation.