La línea de producción, programable
Todo lo que hace el workspace — subir, evaluar, mejorar, descargar — manejado desde tus propios sistemas con una API JSON simple.
El ciclo
La API refleja el workspace: cuatro pasos, repetidos por libro.
Subir
Declaras el archivo, haces PUT de los bytes a una URL prefirmada y registras la publicación. Los archivos nunca pasan por la API.
Correr
Inicias cualquier herramienta contra la versión de trabajo de la publicación. La respuesta es un run que consultas — las herramientas sincrónicas terminan en la primera consulta.
Leer
Obtienes el reporte JSON del run: hallazgos, puntajes, metadatos o la descripción para la página de la publicación.
Descargar
Las reparaciones y ediciones agregan nuevas versiones del archivo. Descargas la versión de trabajo con un enlace de corta duración.
Autenticación
Cada request lleva una clave de API de workspace como token Bearer. La clave está atada a un workspace: todo lo que creas y lees con ella vive ahí, exactamente como si trabajaras en la app.
Las claves se emiten por workspace y se muestran una sola vez. La gestión autoservicio llega pronto a la configuración del workspace; mientras tanto, pide tu clave a tu contacto en publica.la.
curl https://origami.publica.la/api/v1/publications \
-H "Authorization: Bearer ${ORIGAMI_API_KEY}" \
-H "Accept: application/json"Inicio rápido
Seis requests llevan un libro de tu disco a un reporte de validación, ida y vuelta. Reemplaza el token y el nombre de archivo; el resto es copiar y pegar.
1 · Pide un lugar de subida
curl -X POST https://origami.publica.la/api/v1/uploads \
-H "Authorization: Bearer ${ORIGAMI_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"original_filename": "book.epub", "size_bytes": 4180294}'2 · PUT de los bytes a la URL prefirmada
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
-H "Content-Type: application/epub+zip" \
--data-binary @book.epub3 · Registra la publicación
curl -X POST https://origami.publica.la/api/v1/publications \
-H "Authorization: Bearer ${ORIGAMI_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"publication_id": "ID_FROM_STEP_1", "key": "KEY_FROM_STEP_1", "original_filename": "book.epub", "size_bytes": 4180294}'4 · Corre una herramienta
curl -X POST https://origami.publica.la/api/v1/publications/PUBLICATION_ID/runs \
-H "Authorization: Bearer ${ORIGAMI_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"tool": "epub-check"}'5 · Consulta el run y lee el reporte
curl https://origami.publica.la/api/v1/runs/RUN_ID \
-H "Authorization: Bearer ${ORIGAMI_API_KEY}"
curl https://origami.publica.la/api/v1/runs/RUN_ID/report \
-H "Authorization: Bearer ${ORIGAMI_API_KEY}"6 · Descarga la versión de trabajo
curl https://origami.publica.la/api/v1/publications/PUBLICATION_ID/files/current \
-H "Authorization: Bearer ${ORIGAMI_API_KEY}"
curl -L -o book-improved.epub \
https://origami.publica.la/api/v1/files/FILE_ID/download \
-H "Authorization: Bearer ${ORIGAMI_API_KEY}"Endpoints
Todos los endpoints viven bajo /api/v1, hablan JSON y responden errores como {error, reason, detail} con un reason estable para máquinas.
Publicaciones y subidas
/api/v1/tools
El catálogo de herramientas que expone la API, con sus flags de medición.
/api/v1/uploads
Genera un PUT prefirmado para un archivo nuevo (30 minutos).
/api/v1/publications
Registra un objeto subido como publicación.
/api/v1/publications
Lista las publicaciones del workspace (paginación por cursor).
/api/v1/publications/{id}
Una publicación: tipo, estado, título, archivo de trabajo.
Versiones de archivo
/api/v1/publications/{id}/files
El historial completo de versiones: el original inmutable más cada copia mejorada.
/api/v1/publications/{id}/files/current
La versión de trabajo — sobre la que actúa la próxima herramienta.
/api/v1/files/{id}/download
302 a un enlace de descarga de corta duración para cualquier versión.
Ejecuciones de herramientas
/api/v1/publications/{id}/runs
Inicia una ejecución (202). Acepta un objeto options y un header Idempotency-Key.
/api/v1/publications/{id}/runs
Lista los runs de una publicación, filtrable por herramienta.
/api/v1/runs/{id}
Estado, tiempos y detalle de error del run.
/api/v1/runs/{id}/report
El reporte JSON del run terminado.
Convenciones
Asincrónico por defecto
Los runs responden 202 con un recurso que consultas. Un run es terminal en succeeded, failed o rejected.
Idempotencia
Manda un header Idempotency-Key en POST /runs; un reintento devuelve el run original en vez de gastar dos veces.
Paginación
Las listas responden {data, next_cursor, has_more}; pasa next_cursor como ?cursor= hasta que has_more sea false.
Límites
Los requests se limitan por clave. Las herramientas medidas comparten el cupo diario de uso justo de tu workspace — un 429 con reason daily_limit_reached significa reintentar mañana, y las subidas consumen el cupo de publicaciones del plan.
Descripciones
La herramienta de descripciones devuelve el texto para la página de la publicación: un solo estilo (back_cover) con una versión larga para el cuerpo y una corta para tarjetas y metadatos.
Los archivos van directo
Las subidas son PUTs prefirmados y las descargas GETs prefirmados contra el storage — la API nunca hace de proxy de los bytes, así que las transferencias son rápidas a cualquier tamaño.
¿Construyendo una integración?
Cuéntanos qué estás automatizando — ingesta masiva, un hook desde tu DAM, un pipeline de preflight — y te ayudamos a conectarlo.