Skip to content
Documentation
Docs/API Reference

API Overview

HTTP API reference for integrating with Potato programmatically.

API Reference

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

Navigate to Instance

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}

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.