{"openapi":"3.1.0","info":{"title":"Pixelbook · API de creadores","version":"2026-10","description":"Crear niveles de Pixelbook, el juego educativo gratuito para adolescentes, con la IA de cada uno. Sin credenciales se empieza un borrador; su token pbd_ sirve para escribir, validar, ver la vista previa, probar y enviar como anónimo, sin cuenta ni confirmación humana. Asociar la autoría a una cuenta es opcional. Elige el circuito según tus herramientas en https://pixelbook.videolibros.app/crear/rutas.md. Guía: https://pixelbook.videolibros.app/crear/guia-ia.md"},"servers":[{"url":"https://admin-api.videolibros.app/api/external/pixelbook/creator"}],"components":{"securitySchemes":{"seriesToken":{"type":"apiKey","in":"header","name":"X-Pixelbook-Series-Token","description":"Capacidad privada pbs_ generada al preparar una serie sin registro."},"draftToken":{"type":"http","scheme":"bearer","bearerFormat":"pbd_","description":"El token de un borrador (POST /drafts), en Authorization: Bearer pbd_… o en X-API-Key."},"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"La clave de un equipo, con el permiso service:pixelbook:create."}},"schemas":{"SeriesVariable":{"type":"object","additionalProperties":false,"required":["id","type","default","scope"],"properties":{"id":{"type":"string","pattern":"^[a-z0-9-]{1,24}$"},"type":{"enum":["int","bool","enum","set"]},"scope":{"enum":["story","collection"]},"min":{"type":"integer"},"max":{"type":"integer"},"values":{"type":"array","maxItems":12,"uniqueItems":true,"items":{"type":"string","pattern":"^[a-z0-9-]{1,24}$"}},"default":{}}},"SeriesPlan":{"type":"object","properties":{"key":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"seriesId":{"type":"integer"},"action":{"enum":["read","save","accept","reject","order"]},"collaboration":{"enum":["closed","open"]},"progression":{"enum":["ordered","free"]},"schemaVersion":{"type":"integer","minimum":1},"variables":{"type":"array","maxItems":32,"items":{"$ref":"#/components/schemas/SeriesVariable"}}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","docs"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"docs":{"type":"string"},"details":{"type":"array","items":{"type":"object"}}}}}}}},"paths":{"/playback/{kind}/{value}":{"get":{"operationId":"pixelbookPlayback","summary":"Consultar prueba o publicación sin llave de edición ni consumir aperturas.","tags":["cartuchos"],"security":[],"parameters":[{"name":"kind","in":"path","required":true,"schema":{"type":"string"}},{"name":"value","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/series/{id}/manage":{"post":{"operationId":"manageSeries","summary":"Gestionar una serie sin registro con X-Pixelbook-Series-Token.","description":"Token pbs_ privado obtenido al preparar la serie. Body: action read, save, accept, reject u order; cartridgeId o cartridgeIds según la acción. save admite variables y schemaVersion; read devuelve ambas propiedades.","tags":["cartuchos"],"security":[{"seriesToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeriesPlan"}}}},"responses":{"200":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/commissions-page/":{"get":{"operationId":"commissionsPage","summary":"Página HTML de encargos públicos, legible sin JavaScript.","tags":["cartuchos"],"security":[],"responses":{"200":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/commissions-page/{code}":{"get":{"operationId":"commissionPage","summary":"Ficha HTML de un encargo público, legible sin JavaScript.","tags":["cartuchos"],"security":[],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cartridges/{slug}/association":{"post":{"operationId":"prepareAssociation","summary":"Pedir la asociación de un cartucho anónimo a una cuenta.","description":"Requiere la llave del borrador. Devuelve confirm.url para que una persona autenticada acepte la asociación. No reenvía, publica ni cambia la revisión del cartucho.","tags":["cartuchos"],"security":[{"draftToken":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cartridges/{slug}/confirmation":{"post":{"operationId":"prepareConfirmation","summary":"Preparar un enlace corto con el cartucho completo para confirmar su envío.","description":"JSON {} usa el espacio guardado; {files} o text/plain con PIXELBOOK-PAQUETE 1 guarda una copia fija. Valida antes de preparar. Devuelve received:false y confirmation.url. Entrega ese enlace; abrirlo no envía nada. No compartas el token pbd_. Para un borrador independiente sin dueño. Para enviar sin intervención usa /submit.","tags":["cartuchos"],"security":[{"draftToken":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"files":{"type":"object","additionalProperties":{"type":"string"}}}}},"text/plain":{"schema":{"type":"string"}}}},"responses":{"200":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/confirmations/{code}":{"get":{"operationId":"readConfirmation","summary":"Abrir la copia fija de un enlace de confirmación, sin enviar nada.","description":"El código solo permite ver y confirmar esa versión hasta expiresAt; no permite editar ni revela el token del borrador. Incluye título, descripción, files, termsVersion y received. Tras el envío sirve de seguimiento hasta su caducidad.","tags":["cartuchos"],"security":[],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"confirmAnonymous","summary":"Confirmar explícitamente el envío anónimo de la copia preparada.","description":"Body {accept:true, termsVersion}. Sin login. Idempotente: una repetición devuelve el mismo recibo sin duplicar cuotas ni trabajos. Para autoría con cuenta, abre registeredUrl y sigue su vinculación.","tags":["cartuchos"],"security":[],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accept","termsVersion"],"properties":{"accept":{"const":true},"termsVersion":{"type":"string"}}}}}},"responses":{"202":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/series":{"get":{"operationId":"seriesCatalog","summary":"Series públicas y sus capítulos. Con ?purpose=create, series abiertas aprobadas, incluidas las vacías.","tags":["cartuchos"],"security":[],"responses":{"200":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cartridges/{slug}/series-plan":{"get":{"operationId":"readSeriesPlan","summary":"Propuesta de serie de este borrador.","tags":["cartuchos"],"security":[{"draftToken":[]},{"apiKey":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"prepareSeriesPlan","summary":"Preparar una serie o la incorporación a una serie existente. Requiere confirmación humana.","description":"Body: {seriesId} o {key, title, description?, collaboration: closed|open, progression: ordered|free, schemaVersion: 1, variables: [{id,type,min?,max?,values?,default,scope}]}. Todos los capítulos de una serie nueva comparten key. Un token de borrador nunca administra series publicadas.","tags":["cartuchos"],"security":[{"draftToken":[]},{"apiKey":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeriesPlan"}}}},"responses":{"200":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/":{"get":{"operationId":"index","summary":"Índice: sin credenciales, qué es y cómo empezar; con token de borrador, el estado de tu borrador; con clave, tus encargos y envíos.","tags":["inicio"],"security":[{},{"draftToken":[]},{"apiKey":[]}],"responses":{"200":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/docs":{"get":{"operationId":"docs","summary":"Estas rutas, con quién puede llamarlas.","tags":["inicio"],"security":[{},{"draftToken":[]},{"apiKey":[]}],"parameters":[{"name":"format","in":"query","required":false,"description":"md para leerlas en Markdown.","schema":{"type":"string"}}],"responses":{"200":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/openapi.json":{"get":{"operationId":"openapi","summary":"Esta API en OpenAPI 3.1, con la seguridad de cada ruta.","tags":["inicio"],"security":[{},{"draftToken":[]},{"apiKey":[]}],"responses":{"200":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/drafts":{"post":{"operationId":"createDraft","summary":"Empezar un nivel sin clave: devuelve el token pbd_ del borrador, su id (slug), su prefijo y la plantilla.","description":"Body: {\"title\", \"idea\"?, \"area\"?, \"cast\"?, \"slug\"?, \"idPrefix\"?, \"strict\"?, \"commissionCode\"?}. Con commissionCode, responde a un encargo público sin reserva ni registro. Sin area ni encargo, el nivel es de temática libre (area: \"libre\"): no va a ninguna asignatura, sale en «Hechos por jugadores» y su serie es la primera de la consola si no se pide cast. Con area, es un área de la consola (otra cosa es 400 unknown_area). El slug y el prefijo propuestos se respetan si están libres; si no, se eligen otros y la respuesta dice renamed: true (con strict: true, 409 slug_taken o prefix_taken con details.suggestions). Guarda el token: es la única vez que se ve.","tags":["borradores"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string","minLength":3,"maxLength":80},"idea":{"type":"string","maxLength":2000},"commissionCode":{"type":"string","pattern":"^enc-[0-9]{4}$","description":"Encargo público al que responde este cartucho independiente. No se reserva."},"area":{"type":"string","default":"libre","description":"libre (temática libre, el valor por defecto) o un área de la consola en vivo, como ciencias o geografia."},"cast":{"type":"string"},"slug":{"type":"string","pattern":"^[a-z][a-z0-9-]{2,39}$"},"idPrefix":{"type":"string","pattern":"^[a-z]{3}$"},"strict":{"type":"boolean"}}}}}},"responses":{"201":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/commissions":{"get":{"operationId":"listCommissions","summary":"Encargos públicos abiertos, sin cuenta ni clave. Admiten varias respuestas.","tags":["encargos"],"security":[{},{"draftToken":[]},{"apiKey":[]}],"parameters":[{"name":"status","in":"query","required":false,"description":"open por defecto, all incluye los encargos públicos cerrados.","schema":{"type":"string"}}],"responses":{"200":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/commissions/{code}":{"get":{"operationId":"getCommission","summary":"Un encargo con su ficha completa y descargas de los textos fuente.","description":"Si el encargo sale de un libro del catálogo, book trae también author, originalLanguage, publicDomainSince, chapters, words, catalogSlug y catalogUrl (la ficha pública, si está publicada). Si la unidad ya tiene voces fijadas, voices da la de cada personaje: {\"personaje\": {\"voice\", \"from\", \"cartridge\"?}}, con from unit (heredada de un cartucho publicado de la unidad) o commission (la fijó una persona). Respétalas en el voices de cart.json y no repitas ninguna voz.","tags":["encargos"],"security":[{},{"draftToken":[]},{"apiKey":[]}],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/commissions/{code}/sources":{"get":{"operationId":"getCommissionSources","summary":"Ediciones completas archivadas, con idioma, traductor, SHA-256 y descarga directa.","tags":["encargos"],"security":[{},{"draftToken":[]},{"apiKey":[]}],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/commissions/{code}/sources/{id}":{"get":{"operationId":"downloadCommissionSource","summary":"Archivo completo de referencia sin cambios. Conserva el aparato de la fuente.","tags":["encargos"],"security":[{},{"draftToken":[]},{"apiKey":[]}],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"offset","in":"query","required":false,"description":"Inicio del tramo, 0 por defecto; usa nextOffset para continuar.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Tamaño del tramo de texto, 20000 por defecto y 40000 como máximo. Sin estos parámetros se descarga el archivo íntegro.","schema":{"type":"string"}}],"responses":{"200":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/commissions/{code}/claim":{"post":{"operationId":"claimCommission","summary":"Compatibilidad histórica. Los encargos públicos no se reservan: POST /drafts con commissionCode.","tags":["encargos"],"security":[{"apiKey":[]}],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/commissions/{code}/release":{"post":{"operationId":"releaseCommission","summary":"Soltar un encargo sin versiones en curso.","tags":["encargos"],"security":[{"apiKey":[]}],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/proposals":{"get":{"operationId":"listProposals","summary":"Tus propuestas, de la más nueva a la más antigua.","tags":["encargos"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"propose","summary":"Proponer un nivel libre (title, pitchMarkdown, area, bookTitle, pages).","tags":["encargos"],"security":[],"responses":{"201":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/proposals/{id}/withdraw":{"post":{"operationId":"withdrawProposal","summary":"Retirar una propuesta que aún no está decidida.","tags":["encargos"],"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cartridges/{slug}":{"get":{"operationId":"getCartridge","summary":"Tu cartucho: versiones, pruebas y siguiente paso. Con token de borrador, también draft, workspace y previews.","description":"Con token de borrador, next sale del estado real del borrador (ficheros, validación, vista previa de esos ficheros y última versión) y, mientras una versión espera a su persona, confirm trae su enlace (confirm.url) y cuándo caduca.","tags":["cartuchos"],"security":[{"draftToken":[]},{"apiKey":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cartridges/{slug}/files":{"put":{"operationId":"putFiles","summary":"Guardar ficheros en el espacio de trabajo del borrador y validarlo.","description":"JSON {\"files\": {\"ruta\": \"texto\" | null}} (null borra) o un paquete de texto (Content-Type: text/plain): una línea «=== ruta ===» antes de cada fichero y «=== FIN ===» al final. Fusiona por ruta y devuelve el espacio de trabajo, changed (las rutas que cambiaron, borradas incluidas), removed (las borradas) y la validación.","tags":["borradores"],"security":[{"draftToken":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["files"],"properties":{"files":{"type":"object","additionalProperties":{"type":["string","null"]}}}}},"text/plain":{"schema":{"type":"string","description":"Un paquete PIXELBOOK-PAQUETE 1."}}}},"responses":{"200":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cartridges/{slug}/files/{path}":{"delete":{"operationId":"deleteFile","summary":"Borrar un fichero del espacio de trabajo.","tags":["borradores"],"security":[{"draftToken":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"path","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cartridges/{slug}/validate":{"post":{"operationId":"validate","summary":"Comprobar ficheros al momento, sin guardar nada. Sin files, un borrador valida su espacio de trabajo.","description":"Body: {\"files\": {\"ruta\": \"texto\"}, \"version\"?}. Devuelve los errores del servidor y del validador oficial.","tags":["cartuchos"],"security":[{"draftToken":[]},{"apiKey":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"files":{"type":"object","description":"Ficheros del cartucho, {\"ruta\": \"texto\"}. Con un token de borrador se puede omitir: entonces se usa el espacio de trabajo.","additionalProperties":{"type":"string"}},"version":{"type":"string","pattern":"^\\d+\\.\\d+\\.\\d+$"}}}}}},"responses":{"200":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cartridges/{slug}/previews":{"post":{"operationId":"createPreview","summary":"Vista previa instantánea: un enlace ?vista= para jugar el nivel ya, con voces estimadas.","description":"La empaqueta el validador oficial de la consola en vivo, sin ejecutar el código. Las vistas de un borrador caducan a los 7 días y admiten un número limitado de aperturas. El enlace es estable: el mismo en cada GET hasta que caduca (expiresAt). missing dice lo que el nivel usa y la vista no trae: receta, directo o ambientes; entonces missingHint lo dice en una frase y cómo oírlo antes de publicar: con una prueba completa, cuya vista sí lo trae. El body admite además series, un objeto de valores iniciales tipados declarados en seriesVars. Se conservan en el parámetro serie del enlace de prueba.","tags":["cartuchos"],"security":[{"draftToken":[]},{"apiKey":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"files":{"type":"object","description":"Ficheros del cartucho, {\"ruta\": \"texto\"}. Con un token de borrador se puede omitir: entonces se usa el espacio de trabajo.","additionalProperties":{"type":"string"}},"version":{"type":"string","pattern":"^\\d+\\.\\d+\\.\\d+$"}}}}}},"responses":{"201":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cartridges/{slug}/trials":{"post":{"operationId":"createTrial","summary":"Prueba completa: capturas, partida automática y una vista con el sonido de la cocina.","description":"La cocina prepara la música y los sonidos de la receta, el sonido de EN DIRECTO y los ambientes, y su vista (preview, cuando pasa) los trae; solo las voces siguen estimadas. Mientras espera turno en la cocina (status queued), la prueba dice cuánto lleva esperando (queuedForSeconds) y su puesto en la cola (queuePosition); next dice cuándo volver a mirarla, con los mismos segundos que pollAfterSeconds.","tags":["cartuchos"],"security":[{"draftToken":[]},{"apiKey":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"files":{"type":"object","description":"Ficheros del cartucho, {\"ruta\": \"texto\"}. Con un token de borrador se puede omitir: entonces se usa el espacio de trabajo.","additionalProperties":{"type":"string"}},"version":{"type":"string","pattern":"^\\d+\\.\\d+\\.\\d+$"}}}}}},"responses":{"201":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cartridges/{slug}/trials/{id}":{"get":{"operationId":"getTrial","summary":"Resultado de una prueba.","tags":["cartuchos"],"security":[{"draftToken":[]},{"apiKey":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cartridges/{slug}/submit":{"post":{"operationId":"submitAnonymous","summary":"Enviar un cartucho a revisión sin login. Anónimo por defecto.","description":"Authorization: Bearer pbd_…; Idempotency-Key recomendada. Sin cuerpo usa los ficheros guardados. Admite JSON {files?, notes?, submissionMode?: anonymous|registered} o el paquete completo como text/plain. Responde 202 con received:true, version y statusUrl; no exige interacción humana para anonymous. La revisión y publicación siguen sus comprobaciones habituales.","tags":["cartuchos"],"security":[{"draftToken":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"text/plain":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cartridges/{slug}/versions":{"post":{"operationId":"submitVersion","summary":"Enviar una versión a revisión (Idempotency-Key recomendada). La anonymous entra en revisión sin login; registered vincula la cuenta una vez.","description":"JSON: {submissionMode?, version?, files?, notes?, replacesVersion?}. Con borrador y submissionMode: anonymous entra directamente en revisión, sin cuenta ni confirmación. Con registered (por defecto en /versions), solo la primera vinculación devuelve confirm.url para entrar con cuenta. Los siguientes envíos de ese borrador vinculado no necesitan interacción. Con clave profesional, version y files son obligatorios. La versión crece siempre. La respuesta de un borrador incluye received, version y statusUrl; received no significa publicado.","tags":["cartuchos"],"security":[{"draftToken":[]},{"apiKey":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"submissionMode":{"type":"string","enum":["anonymous","registered"],"default":"registered"},"version":{"type":"string"},"files":{"type":"object","additionalProperties":{"type":"string"}},"notes":{"type":"string","maxLength":4000},"replacesVersion":{"type":"string"}}}}}},"responses":{"201":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cartridges/{slug}/versions/{version}":{"get":{"operationId":"getVersion","summary":"Estado, informe, comentarios y siguiente paso de una versión.","tags":["cartuchos"],"security":[{"draftToken":[]},{"apiKey":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cartridges/{slug}/versions/{version}/files":{"get":{"operationId":"getVersionFiles","summary":"Los ficheros de una versión.","tags":["cartuchos"],"security":[{"draftToken":[]},{"apiKey":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cartridges/{slug}/versions/{version}/withdraw":{"post":{"operationId":"withdrawVersion","summary":"Retirar tu versión mientras está en curso.","tags":["cartuchos"],"security":[{"draftToken":[]},{"apiKey":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/feedback":{"get":{"operationId":"feedback","summary":"Novedades para ti desde una fecha.","tags":["cartuchos"],"security":[{"draftToken":[]},{"apiKey":[]}],"parameters":[{"name":"since","in":"query","required":false,"description":"Fecha ISO 8601; por defecto, hace 7 días.","schema":{"type":"string"}}],"responses":{"200":{"description":"Respuesta correcta; next dice el siguiente paso.","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Error con código, pista y enlace a la guía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}