Iniciar sesiónRegistrarse gratis

Referencia de API

Descripción general

Esta página documenta el contrato actual de agente de IA externo para Flashcards.

Comience desde el punto de entrada del descubrimiento canónico:

GET https://api.flashcards-open-source-app.com/v1/

La misma carga útil de descubrimiento también está disponible en GET /v1/agent, pero /v1/ es el punto de entrada público principal.

La respuesta de descubrimiento le dice al agente cómo:

  • iniciar sesión OTP por correo electrónico
  • intercambiar la OTP por una clave API de larga duración
  • cargar el contexto de la cuenta
  • crear o seleccionar un espacio de trabajo
  • continuar a través de la superficie SQL publicada

Especificaciones publicadas

URL de especificaciones principales para la superficie del agente externo:

  • https://api.flashcards-open-source-app.com/v1/agent/openapi.json
  • https://api.flashcards-open-source-app.com/v1/agent/swagger.json

También existen alias de raíz equivalentes:

  • https://api.flashcards-open-source-app.com/v1/openapi.json
  • https://api.flashcards-open-source-app.com/v1/swagger.json

Arranque de autenticación

El arranque OTP se ejecuta en el servicio de autenticación:

  • POST https://auth.flashcards-open-source-app.com/api/agent/send-code
  • POST https://auth.flashcards-open-source-app.com/api/agent/verify-code

El flujo es:

  1. Llama a GET /v1/.
  2. Envíe el correo electrónico del usuario a send-code.
  3. Lea otpSessionToken de la respuesta.
  4. Solicite al usuario el último código de correo electrónico de 8 dígitos.
  5. Llame a verify-code con code, otpSessionToken y label.
  6. Conserve la clave API devuelta fuera de la memoria del chat.

Variable de entorno recomendada:

export FLASHCARDS_OPEN_SOURCE_API_KEY="fca_ABCDEFGH_0123456789ABCDEFGHJKMNPQRS"

Las solicitudes autenticadas utilizan:

Authorization: ApiKey <key>

Secuencia de arranque de ejemplo:

curl https://api.flashcards-open-source-app.com/v1/

curl -X POST https://auth.flashcards-open-source-app.com/api/agent/send-code \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'

curl -X POST https://auth.flashcards-open-source-app.com/api/agent/verify-code \
  -H "Content-Type: application/json" \
  -d '{
    "code":"12345678",
    "otpSessionToken":"...",
    "label":"Codex on MacBook"
  }'

Superficie del agente posterior al inicio de sesión

Después de la verificación, la superficie actual del agente es:

  • GET /v1/agent/me
  • GET /v1/agent/workspaces
  • POST /v1/agent/workspaces
  • POST /v1/agent/workspaces/{workspaceId}/select
  • POST /v1/agent/sql/query (solo lectura)
  • POST /v1/agent/sql/execute (escritura)

El bootstrap típico se ve así:

  1. GET /v1/agent/me
  2. GET /v1/agent/workspaces?limit=100
  3. Si es necesario, POST /v1/agent/workspaces con {"name":"Personal"}
  4. Si es necesario, POST /v1/agent/workspaces/{workspaceId}/select
  5. Utilice POST /v1/agent/sql/query para lecturas y POST /v1/agent/sql/execute para escrituras

La selección del espacio de trabajo es explícita por conexión de clave API. Los agentes deben seguir el texto instructions devuelto y el campo docs.openapiUrl de cada sobre en lugar de adivinar el siguiente paso.

Superficie SQL

POST /v1/agent/sql/query es la superficie estrictamente de solo lectura (SHOW TABLES, DESCRIBE, SELECT) y POST /v1/agent/sql/execute es la superficie de escritura (INSERT, UPDATE, DELETE); una sola llamada debe ser totalmente de lectura o totalmente de escritura.

Está intencionalmente limitado y no es PostgreSQL completo. Esta documentación cubre solo el dialecto compatible, no una referencia de compatibilidad con PostgreSQL.

Ninguna ruta de lectura repara datos, recalcula la programación ni cambia el estado de las tarjetas. Use POST /v1/agent/sql/execute para toda escritura.

Familias de declaraciones actuales:

  • SHOW TABLES
  • DESCRIBE <resource>
  • SELECT
  • INSERT
  • UPDATE
  • DELETE

Los recursos lógicos publicados actualmente incluyen:

  • workspace
  • cards
  • decks
  • review_events

Notas:

  • LIMIT por defecto es 100 y tiene un límite de 100
  • use ORDER BY cuando necesite una paginación estable
  • utilice SHOW TABLES o DESCRIBE cards para el descubrimiento de esquemas
  • el contrato de agente externo tiene un alcance de espacio de trabajo después de la selección

Solicitud de ejemplo:

curl -X POST https://api.flashcards-open-source-app.com/v1/agent/sql/query \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey $FLASHCARDS_OPEN_SOURCE_API_KEY" \
  -d '{"sql":"SHOW TABLES"}'

Ejemplo de consulta de tarjeta:

curl -X POST https://api.flashcards-open-source-app.com/v1/agent/sql/query \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey $FLASHCARDS_OPEN_SOURCE_API_KEY" \
  -d '{
    "sql":"SELECT card_id, front_text, back_text, tags FROM cards ORDER BY updated_at DESC LIMIT 20 OFFSET 0"
  }'

Mutación de ejemplo:

curl -X POST https://api.flashcards-open-source-app.com/v1/agent/sql/execute \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey $FLASHCARDS_OPEN_SOURCE_API_KEY" \
  -d '{
    "sql":"UPDATE cards SET back_text = '\''Updated answer'\'' WHERE card_id = '\''50b5b928-7f04-4cc8-878d-6cd0e8b98474'\''"
  }'

También hay disponible un servidor MCP remoto en https://mcp.flashcards-open-source-app.com/mcp que usa OAuth 2.1 (Dynamic Client Registration + PKCE). Expone la misma división como dos herramientas, sql_query (estrictamente de solo lectura) y sql_execute (escritura), además de list_workspaces, estrictamente de solo lectura.

Seguridad y alcance

La superficie SQL es un dialecto contenido y validado por el analizador, no PostgreSQL en bruto. Las protecciones son:

  • Lista de instrucciones cerrada: solo SHOW TABLES, DESCRIBE, SHOW COLUMNS y SELECT para lecturas, e INSERT, UPDATE y DELETE para escrituras. Cualquier otra cosa se rechaza en el análisis.
  • Recursos limitados: las instrucciones solo pueden tocar los recursos workspace, cards, decks y review_events.
  • Alcance por espacio de trabajo: cada instrucción tiene el alcance de su espacio de trabajo seleccionado, sin acceso entre inquilinos.
  • Límites: hasta 100 filas por instrucción, hasta 50 instrucciones por lote y un límite de resultados de aproximadamente 12k tokens. Los lotes de mutación se aplican de forma atómica.
  • División de lectura/escritura: sql_query y list_workspaces son estrictamente de solo lectura (readOnlyHint) y nunca reparan datos, recalculan la programación ni cambian el estado de las tarjetas. sql_execute es la única herramienta de escritura y realiza escrituras (destructiveHint); una sola llamada debe ser totalmente de lectura o totalmente de escritura.

API humanas y de sincronización

Flashcards también incluye API independientes para clientes humanos y sincronización sin conexión, pero no son el contrato principal para agentes externos:

  • los flujos del navegador utilizan cookies de dominio compartido más protección CSRF
  • Los primeros clientes sin conexión utilizan rutas de sincronización implementadas en /v1/workspaces/{workspaceId}/sync/push y /v1/workspaces/{workspaceId}/sync/pull
  • las rutas de sincronización están intencionalmente fuera de la superficie OpenAPI del agente externo