Skip to content

Visão Geral da API

Referência da API HTTP do Potato — endpoints administrativos para gerenciar anotadores, acionar exportações, consultar estatísticas de progresso e integrar com pipelines externos.

O Potato fornece endpoints de API HTTP para integração com frontends personalizados, scripts de automação ou sistemas externos.

Visão Geral

URL Base

text
http://localhost:8000

Autenticação

A maioria dos endpoints exige uma sessão ativa, estabelecida pelos endpoints de login e mantida por cookies.

Para acesso programático:

  1. Use cookies de sessão de um navegador
  2. Use o modo de depuração com criação automática de usuário
  3. Implemente o fluxo de login programaticamente

Formato da Resposta

Todos os endpoints da API retornam respostas em JSON. As respostas de erro incluem um campo error.

Gerenciamento de Sessão

Login

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

Verificar Sessão

http
GET /api/current_instance

Resposta:

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

Logout

http
POST /logout

Endpoints de Anotação

Obter Instância Atual

http
GET /api/current_instance

Retorna informações sobre a instância de anotação atual do usuário.

Obter Conteúdo da Instância

http
GET /api/spans/{instance_id}

Retorna o conteúdo de texto e as anotações de span existentes.

Resposta:

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

Obter Anotações

http
GET /get_annotations?instance_id={instance_id}

Retorna todas as anotações de uma instância específica.

Enviar Anotação

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

Resposta (Sucesso):

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

Resposta (Com Controle de Qualidade):

json
{
  "status": "success",
  "qc_result": {
    "type": "gold_standard",
    "correct": false,
    "gold_label": {"sentiment": "positive"}
  }
}

Navegar até uma Instância

http
POST /go_to
Content-Type: application/json
 
{"go_to": "item_005"}

Ou por ação:

json
{"action": "next_instance"}

Informações de Esquema

Obter Esquemas de Anotação

http
GET /api/schemas

Obter Cores dos Rótulos

http
GET /api/colors

Obter Destaques de Palavras-Chave

http
GET /api/keyword_highlights/{instance_id}

Endpoints da API de Administração

Os endpoints de administração exigem privilégios de administrador.

Verificação de Saúde

http
GET /admin/health

Visão Geral do Painel

http
GET /admin/api/overview

Resposta:

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

Obter Anotadores

http
GET /admin/api/annotators

Obter Instâncias

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

Obter Configuração

http
GET /admin/api/config

Atualizar Configuração

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

API de Controle de Qualidade

Métricas de Controle de Qualidade

http
GET /admin/api/quality_control

Retorna estatísticas de verificações de atenção e padrões de referência.

Métricas de Concordância

http
GET /admin/api/agreement

Retorna o alfa de Krippendorff por esquema.

API do Assistente de IA

Obter Sugestão de IA

http
GET /get_ai_suggestion?instance_id={instance_id}

Obter Ajuda do Assistente de IA

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

Exemplo: Fluxo Completo de Anotação

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

Exemplo: Monitoramento Administrativo

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

Respostas de Erro

Todos os endpoints podem retornar respostas de erro:

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

Códigos de status HTTP comuns:

  • 400 - Requisição Inválida (parâmetros inválidos)
  • 401 - Não Autorizado (sem sessão)
  • 403 - Proibido (permissões insuficientes)
  • 404 - Não Encontrado
  • 500 - Erro Interno do Servidor

Leitura Complementar

Para detalhes de implementação, consulte a documentação de origem.