Referencia de la API

Todo lo que tu IA —o tú— puede llamar: planes de estudio, el quiz, imágenes, PDF y un indicador de que sigue trabajando.

Cómo autenticarse

Las llamadas al quiz necesitan Authorization: Bearer más la clave del quiz. Envía If-Match con la versión actual para que dos guardados no se sobrescriban. Estas respuestas nunca se guardan en caché.

Abrir el esquema completo

URL base

https://quiz.ai/api/v1

Cómo autenticarse

Authorization: Bearer <quiz-scoped-key>

Mapa de la API

GET
/api/v1

Un mapa de la API y los enlaces que siguen.

Sin clave
GET
/api/v1/openapi.json

El esquema OpenAPI 3.1 completo: útil para las herramientas que sepan leerlo.

Sin clave

Planes de estudio

GET
/api/v1/curricula

Lista los planes de estudio que conocemos.

Sin clave
GET
/api/v1/curricula/{curriculumId}

Lee los detalles de un plan de estudios.

Sin clave
GET
/api/v1/curricula/{curriculumId}/objectives?subject=math&grade=5&limit=100&offset=0

Busca los objetivos de aprendizaje de un plan de estudios por materia y grado.

Sin clave

El quiz

GET
/api/v1/target

Mira a qué quiz puede escribir esta clave.

Clave del quiz
GET
/api/v1/quizzes/{quizId}

Lee el quiz actual y su número de versión.

Clave del quiz
PUT
/api/v1/quizzes/{quizId}

Sustituye el quiz entero de un guardado. Envía If-Match para no sobrescribir un trabajo más nuevo.

Clave del quiz
POST
/api/v1/quizzes/{quizId}/publish

Revisa el quiz y hazlo público. Envía If-Match para no sobrescribir un trabajo más nuevo.

Clave del quiz

Imágenes

POST
/api/v1/quizzes/{quizId}/images

Sube un PNG, JPEG, GIF o WebP. Guardamos un WebP estático y limpio.

Clave del quiz
POST
/api/v1/quizzes/{quizId}/images/templates

Dibuja la imagen de una pregunta a partir de una plantilla, o previsualízala en PNG o SVG.

Clave del quiz
GET
/api/v1/quizzes/{quizId}/images/{imageId}

Descarga una imagen guardada. Se admiten solicitudes Range.

Clave del quiz
DELETE
/api/v1/quizzes/{quizId}/images/{imageId}

Borra una imagen que ninguna pregunta esté usando.

Clave del quiz
Imágenes de pregunta

PDF y actividad

POST
/api/v1/quizzes/{quizId}/activity

Inicia, renueva o para la señal de “sigue trabajando” de 90 segundos.

Clave del quiz
GET
/api/v1/quizzes/{quizId}/sheet.pdf?names=Alice,Bob&class=5B&key=0

Descarga una hoja de respuestas para imprimir. Puedes agregar nombres, grupo y clave de respuestas.

Clave del quiz

Guardar el quiz entero

Tu IA envía el título, la descripción, el idioma y todas las preguntas de una vez. Enviar el mismo quiz válido dos veces es seguro.

HTTP
PUT /api/v1/quizzes/qz_7KF2M9qTx3aB
Authorization: Bearer <quiz-scoped-key>
Content-Type: application/json
If-Match: "0"

{
  "title": "A quick tour of the Solar System",
  "description": "Ten friendly questions for curious adults.",
  "language": "en-gb",
  "questions": [
    {
      "prompt": "Which planet has the shortest year?",
      "choices": ["Mercury", "Venus", "Earth", "Mars"],
      "correctChoiceIndex": 0,
      "explanation": "Mercury orbits the Sun in about 88 Earth days."
    }
  ]
}

Reglas de las preguntas

  • Cada pregunta necesita un enunciado claro y de dos a seis opciones no vacías.
  • Límites: título 140 caracteres, descripción 1,000, 1–100 preguntas, enunciado 500, cada opción 240, explicación 1,000.
  • correctChoiceIndex es el índice (desde cero) de la opción correcta.
  • El orden de las preguntas es el del array: la primera de la lista es la pregunta 1.
  • Envía el último número de versión en el encabezado If-Match para que dos guardados no se sobrescriban.

Publica cuando te convenza

Publicar vuelve a revisar el quiz y te da un enlace público estable. Si falta algo, corrígelo, guarda otra vez y publica.

HTTP
POST /api/v1/quizzes/qz_7KF2M9qTx3aB/publish
Authorization: Bearer <quiz-scoped-key>
If-Match: "1"