# API Overview

Source: https://www.potatoannotator.com/docs/api/overview

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:
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

- [Admin Dashboard](/docs/features/admin-dashboard) - Web-based admin interface
- [Quality Control](/docs/features/quality-control) - Quality metrics API
- [Behavioral Tracking](/docs/features/behavioral-tracking) - Interaction tracking API

For implementation details, see the [source documentation](https://github.com/davidjurgens/potato/blob/main/docs/api_reference.md).