Skip to content

Vue d'ensemble de l'API

Référence de l'API HTTP de Potato — endpoints d'administration pour gérer les annotateurs, déclencher des exports, interroger les statistiques d'avancement et s'intégrer à des pipelines externes.

Potato fournit des endpoints HTTP pour l'intégration avec des interfaces personnalisées, des scripts d'automatisation ou des systèmes externes.

Vue d'ensemble

URL de base

text
http://localhost:8000

Authentification

La plupart des endpoints exigent une session active, établie via les endpoints de connexion et maintenue par cookies.

Pour un accès programmatique :

  1. Utilisez les cookies de session d'un navigateur
  2. Utilisez le mode debug avec création automatique d'utilisateur
  3. Implémentez le flux de connexion par programme

Format de réponse

Tous les endpoints renvoient des réponses JSON. Les réponses d'erreur contiennent un champ error.

Gestion des sessions

Connexion

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

Vérifier la session

http
GET /api/current_instance

Réponse :

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

Déconnexion

http
POST /logout

Endpoints d'annotation

Obtenir l'instance courante

http
GET /api/current_instance

Renvoie des informations sur l'instance d'annotation courante de l'utilisateur.

Obtenir le contenu de l'instance

http
GET /api/spans/{instance_id}

Renvoie le contenu textuel et les annotations de spans existantes.

Réponse :

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

Obtenir les annotations

http
GET /get_annotations?instance_id={instance_id}

Renvoie toutes les annotations d'une instance donnée.

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

Réponse (succès) :

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

Réponse (avec contrôle qualité) :

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

Ou par action :

json
{"action": "next_instance"}

Informations sur les schémas

Obtenir les schémas d'annotation

http
GET /api/schemas

Obtenir les couleurs d'étiquettes

http
GET /api/colors

Obtenir les surlignages de mots-clés

http
GET /api/keyword_highlights/{instance_id}

Endpoints d'administration

Les endpoints d'administration exigent des privilèges d'administrateur.

Contrôle de santé

http
GET /admin/health

Vue d'ensemble du tableau de bord

http
GET /admin/api/overview

Réponse :

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

Obtenir les annotateurs

http
GET /admin/api/annotators

Obtenir les instances

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

Obtenir la configuration

http
GET /admin/api/config

Mettre à jour la configuration

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

API de contrôle qualité

Métriques de contrôle qualité

http
GET /admin/api/quality_control

Renvoie les statistiques des contrôles d'attention et des étalons de référence.

Métriques d'accord

http
GET /admin/api/agreement

Renvoie l'alpha de Krippendorff par schéma.

API de l'assistant IA

Obtenir une suggestion IA

http
GET /get_ai_suggestion?instance_id={instance_id}

Obtenir l'aide de l'assistant IA

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

Exemple : flux d'annotation complet

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

Exemple : supervision administrateur

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

Réponses d'erreur

Tous les endpoints peuvent renvoyer des réponses d'erreur :

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

Codes de statut HTTP courants :

  • 400 - Requête incorrecte (paramètres invalides)
  • 401 - Non authentifié (aucune session)
  • 403 - Interdit (permissions insuffisantes)
  • 404 - Introuvable
  • 500 - Erreur interne du serveur

Pour aller plus loin

Pour les détails d'implémentation, voir la documentation source.