Referencia de la API de FluoTest
La API pública de FluoTest se sirve a través de su endpoint MCP, una API JSON-RPC 2.0 sobre HTTPS normal que funciona con curl o cualquier cliente HTTP, sin necesidad de una biblioteca MCP. Te autenticas con una clave API personal.
Última actualización
¿Cómo llamo a la API de FluoTest?
Genera una clave API en Ajustes → Seguridad → Claves API y envía solicitudes JSON-RPC por POST a https://fluotest.com/api/mcp con la clave en una cabecera "Authorization: Bearer". Hoy hay once herramientas disponibles: list_quizzes, create_quiz, import_quiz, get_quiz_questions, get_quiz_settings, update_quiz, publish_quiz, unpublish_quiz, duplicate_quiz, get_results y delete_quiz.
Obtener una clave API#
Las claves API son personales: cada solicitud hecha con una clave actúa como tu cuenta de usuario, con los mismos permisos que tienes en la app.
- Abre Ajustes → Seguridad → Claves API en tu panel de FluoTest.
- Escribe un nombre que indique dónde se usará la clave (por ejemplo, "Script de Zapier").
- Haz clic en Generar clave y copia el valor fluo_… inmediatamente.
- Guárdala en un lugar seguro: un gestor de contraseñas o el almacén de secretos de tu herramienta.
- Se muestra una vez: Solo se guarda un hash SHA-256 de la clave. Si la pierdes, revócala y genera una nueva.
- Hasta 10 claves: Crea claves distintas para cada herramienta o script, así puedes revocar una sin romper las demás.
- Revocables en cualquier momento: Revocar una clave tiene efecto inmediato en la siguiente solicitud.
- Seguimiento del uso: Cada clave muestra cuándo se usó por última vez, así es fácil detectar y eliminar las claves obsoletas.
Autenticación#
Envía la clave en cada solicitud en la cabecera Authorization:
Authorization: Bearer fluo_YOUR_API_KEY
¿Vas a conectar un asistente de IA en lugar de escribir código? Consulta la guía del servidor MCP →
Formato de las solicitudes#
El endpoint es https://fluotest.com/api/mcp. Envía solicitudes POST con "Content-Type: application/json", una cabecera Accept de "application/json, text/event-stream" y un cuerpo JSON-RPC 2.0. No hace falta el handshake initialize: puedes llamar directamente a tools/list y tools/call.
Las respuestas llegan como un cuerpo de server-sent events: el resultado JSON-RPC está en la línea "data:" y el payload de cada herramienta es una cadena JSON dentro de result.content[0].text:
event: message
data: {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"{\n \"quiz_id\": \"…\",\n \"status\": \"draft\", …}"}]}}Ejemplos#
Listar las herramientas disponibles
curl -X POST https://fluotest.com/api/mcp \
-H "Authorization: Bearer fluo_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'Listar tus quizzes
curl -X POST https://fluotest.com/api/mcp \
-H "Authorization: Bearer fluo_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": { "name": "list_quizzes", "arguments": {} }
}'Crear un quiz en borrador
curl -X POST https://fluotest.com/api/mcp \
-H "Authorization: Bearer fluo_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "create_quiz",
"arguments": {
"title": "Customer readiness check",
"questions": [
{ "text": "Do you have a budget?", "type": "yes_no", "points": 2 },
{
"text": "Company size?",
"type": "multiple_choice",
"options": [
{ "label": "1-10", "score": 1 },
{ "label": "11-50", "score": 2 },
{ "label": "50+", "score": 3 }
]
}
]
}
}
}'Obtener las preguntas de un quiz
curl -X POST https://fluotest.com/api/mcp \
-H "Authorization: Bearer fluo_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "get_quiz_questions",
"arguments": { "quiz_id": "Customer readiness check" }
}
}'Obtener la configuración de un quiz
curl -X POST https://fluotest.com/api/mcp \
-H "Authorization: Bearer fluo_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 8,
"method": "tools/call",
"params": {
"name": "get_quiz_settings",
"arguments": { "quiz_id": "Customer readiness check" }
}
}'Editar un quiz
curl -X POST https://fluotest.com/api/mcp \
-H "Authorization: Bearer fluo_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 5,
"method": "tools/call",
"params": {
"name": "update_quiz",
"arguments": {
"quiz_id": "Customer readiness check",
"questions": [
{ "text": "Do you have a budget?", "type": "yes_no", "points": 2 },
{ "text": "What's your budget range?", "type": "multiple_choice",
"options": [
{ "label": "Under $1k", "score": 1 },
{ "label": "$1k-$10k", "score": 2 },
{ "label": "$10k+", "score": 3 }
]
}
]
}
}
}'Publicar un quiz en borrador
curl -X POST https://fluotest.com/api/mcp \
-H "Authorization: Bearer fluo_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 6,
"method": "tools/call",
"params": {
"name": "publish_quiz",
"arguments": { "quiz_id": "Customer readiness check" }
}
}'Obtener los resultados de un quiz
curl -X POST https://fluotest.com/api/mcp \
-H "Authorization: Bearer fluo_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "get_results",
"arguments": { "quiz_id": "Customer readiness check" }
}
}'Eliminar un quiz (con confirmación)
curl -X POST https://fluotest.com/api/mcp \
-H "Authorization: Bearer fluo_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 7,
"method": "tools/call",
"params": {
"name": "delete_quiz",
"arguments": { "quiz_id": "Customer readiness check", "confirm": true }
}
}'Errores#
Los problemas de autenticación usan códigos de estado HTTP con un cuerpo de error OAuth (RFC 6750) y una cabecera WWW-Authenticate. Los demás errores HTTP (endpoint desconocido, límite de solicitudes) devuelven application/problem+json (RFC 9457) con un código estable y una pista. Los problemas dentro de una llamada a una herramienta llegan como una respuesta JSON-RPC normal con isError activado y la explicación en el texto del contenido.
| Estado | Significado |
|---|---|
| 401 | Clave API ausente, no válida o revocada. Revisa la cabecera Authorization y que la clave siga existiendo en Ajustes. |
| 400 | Cuerpo JSON-RPC mal formado. Revisa los campos jsonrpc, id, method y params. |
| 404 | No hay ningún endpoint en esa ruta. El cuerpo es application/problem+json con el código not_found. |
| 429 | Se superó el límite de solicitudes. El cuerpo es application/problem+json con el código rate_limited; espera el número de segundos indicado en Retry-After. |
| 200 + isError | La propia llamada a la herramienta falló, por ejemplo un nombre o ID de quiz que no es tuyo, un nombre de quiz que coincide con más de uno de tus quizzes, editar un quiz publicado sin confirm_edit_published: true, eliminar un quiz sin confirm: true, o una pregunta multiple_choice con menos de 2 opciones. El texto del contenido explica qué corregir. |
Códigos de error (application/problem+json)
Todo cuerpo de problema tiene type, title, status, code y normalmente detail y hint. La URI de type enlaza a la entrada correspondiente de abajo.
- not_found
- La ruta no es un endpoint de la API. Consulta /openapi.json para ver los endpoints documentados.
- rate_limited
- Demasiadas solicitudes en la ventana actual. Espera los segundos de Retry-After y vuelve a intentarlo.
Límites de solicitudes y versiones#
Cada clave API o token OAuth puede enviar 120 solicitudes por minuto a /api/mcp (las solicitudes sin credencial se cuentan por dirección IP). Cada respuesta incluye RateLimit-Policy y RateLimit (formato del borrador del IETF), además de RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset, para que puedas reducir el ritmo antes de llegar al límite. Si lo superas, recibes un 429 con Retry-After.
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
RateLimit-Policy: "default";q=120;w=60
RateLimit: "default";r=0;t=17
Retry-After: 17
{"type":"https://fluotest.com/en/docs/api-reference#error-rate_limited","title":"Too Many Requests","status":429,"code":"rate_limited","hint":"Wait 17 seconds (Retry-After) before retrying."}El transporte se versiona con la cabecera de solicitud MCP-Protocol-Version, negociada durante initialize. Las herramientas siguen el versionado semántico (el campo version de /openapi.json): las herramientas nuevas y los argumentos opcionales nuevos se añaden sin romper nunca las llamadas existentes.
Un cambio incompatible se publica con un nombre de herramienta nuevo. La herramienta antigua sigue funcionando durante al menos 90 días; las respuestas que la usan llevan una cabecera Deprecation y una cabecera Sunset con la fecha de retirada, y el cambio se anuncia en el registro de cambios.
Preguntas frecuentes#
¿Hay un límite de solicitudes?
Sí: 120 solicitudes por minuto por clave API o token OAuth en /api/mcp. Cada respuesta incluye cabeceras RateLimit con lo que te queda disponible, y una respuesta 429 te indica cuánto esperar en Retry-After.
¿Puedo usar OAuth en lugar de una clave API?
Sí, OAuth es la forma recomendada de conectar asistentes de IA como Claude, donde el usuario aprueba el acceso en una pantalla de consentimiento. Las claves API son la opción más sencilla para scripts y clientes que solo envían cabeceras. Consulta la guía del servidor MCP para configurar OAuth.
¿Qué puede hacer la API hoy?
Ocho operaciones: list_quizzes, create_quiz, get_quiz_questions, get_quiz_settings, update_quiz (con un paso de confirmación para editar quizzes publicados), publish_quiz, get_results y delete_quiz (con un paso de confirmación). Cada argumento que hace referencia a un quiz acepta un título, un slug o un ID. Hay más operaciones previstas. Cuéntanos qué necesitas mediante el formulario de comentarios del panel.