Referencia de la API
Base: https://api.lectoresbeta.com/api/v1. Todas las peticiones llevan
Authorization: Bearer <access_token> y, las que tienen cuerpo, Content-Type: application/json.
Los ejemplos están resumidos: una respuesta puede traer más campos, que debes ignorar si no los
usas.
Identidad
Sección titulada «Identidad»GET /connect/me
Sección titulada «GET /connect/me»A quién representa tu aplicación. Vale cualquier token válido, sea cual sea su permiso.
{ "userId": "0192f8a1-4c3b-7e2a-9f10-6b5d2c8e4a71", "username": "beatriz", "name": "Beatriz Ramos", "avatarUrl": "https://…/avatar.webp"}name y avatarUrl pueden ser null. No se expone el correo ni el resto del perfil.
GET /connect/works — works:read
Sección titulada «GET /connect/works — works:read»Las obras propias, paginadas.
| Parámetro | Valores | Por defecto |
|---|---|---|
status |
DRAFT, PUBLISHED, IN_CORRECTION |
todas |
format |
CHAPTERED, SINGLE_TEXT |
todos |
sort |
recent, oldest, rated, read |
recent |
page |
desde 1 | 1 |
perPage |
de 1 a 50 | 20 |
{ "total": 3, "totalPages": 1, "page": 1, "perPage": 20, "works": [ { "workId": "0192f8a2-0000-7000-9000-000000000001", "title": "El cuaderno de bitácora", "synopsis": null, "status": "DRAFT", "format": "CHAPTERED", "wordCount": 1300, "chapterCount": 2, "genres": ["SCIENCE_FICTION"], "beingCorrected": false, "archived": false, "createdAt": "2026-11-05T10:00:00+00:00", "updatedAt": "2026-11-05T10:20:00+00:00" } ]}El listado no trae la revision ni el texto: para eso, la obra entera.
POST /connect/works — works:write
Sección titulada «POST /connect/works — works:write»Crea una obra con sus capítulos, en borrador.
{ "title": "El cuaderno de bitácora", "synopsis": "Una travesía contada por quien no quería ir.", "genres": ["SCIENCE_FICTION"], "format": "CHAPTERED", "chapters": [ { "title": "Uno", "contentHtml": "<p>Primer capítulo…</p>" }, { "title": "Dos", "contentHtml": "<p>Segundo capítulo…</p>" } ]}| Campo | Obligatorio | Notas |
|---|---|---|
title |
Sí | Hasta 180 caracteres |
synopsis |
No | |
genres |
No | Hasta 3 códigos (SCIENCE_FICTION, CRIME…) del catálogo público GET /api/v1/genres, que no necesita token |
format |
No | CHAPTERED (por defecto) o SINGLE_TEXT, que admite un solo capítulo |
chapters |
Sí | En orden. title opcional; contentHtml con texto (ver el contenido de un capítulo) |
Respuesta 201:
{ "workId": "0192f8a2-0000-7000-9000-000000000001", "revision": 3, "chapterIds": ["0192f8a3-…-01", "0192f8a3-…-02"]}GET /connect/works/{workId} — works:read
Sección titulada «GET /connect/works/{workId} — works:read»La obra entera, con el texto de cada capítulo y la revisión actual.
{ "workId": "0192f8a2-0000-7000-9000-000000000001", "title": "El cuaderno de bitácora", "synopsis": null, "status": "DRAFT", "format": "CHAPTERED", "revision": 3, "chapters": [ { "chapterId": "0192f8a3-…-01", "position": 1, "title": "Uno", "status": "IN_CORRECTION", "version": 1, "wordCount": 900, "blocked": false, "contentHtml": "<p>Primer capítulo…</p>" } ]}POST /connect/works/{workId}/revisions — works:write
Sección titulada «POST /connect/works/{workId}/revisions — works:write»Una versión nueva de la obra entera, escrita sobre baseRevision. Las reglas están en
Publicar una versión nueva.
{ "baseRevision": 3, "chapters": [ { "chapterId": "0192f8a3-…-02", "title": "Dos", "contentHtml": "<p>…</p>" }, { "chapterId": "0192f8a3-…-01", "title": "Uno, revisado", "contentHtml": "<p>…</p>" }, { "title": "Tres", "contentHtml": "<p>…</p>" } ], "removedChapterIds": []}Respuesta 201, con los capítulos en su orden final:
{ "workId": "0192f8a2-0000-7000-9000-000000000001", "revision": 6, "chapterIds": ["0192f8a3-…-02", "0192f8a3-…-01", "0192f8a3-…-03"]}Errores propios: 409 WORK_REVISION_CONFLICT (con currentRevision), 422 CHAPTER_OMITTED,
422 CHAPTER_NOT_IN_WORK, 422 CHAPTER_LISTED_TWICE, 422 EMPTY_CHAPTER,
409 CHAPTER_HAS_CORRECTIONS, 409 CHAPTER_BLOCKED, 409 SINGLE_TEXT_HAS_ONE_CHAPTER,
409 WORK_NEEDS_A_CHAPTER.
GET /connect/works/{workId}/status — works:read
Sección titulada «GET /connect/works/{workId}/status — works:read»Dónde está la obra.
{ "workId": "0192f8a2-0000-7000-9000-000000000001", "status": "IN_CORRECTION", "revision": 6, "beingCorrected": true, "chapters": [ { "chapterId": "0192f8a3-…-02", "position": 1, "status": "PUBLISHED", "version": 1, "correctable": false, "hasBeenCorrected": false }, { "chapterId": "0192f8a3-…-01", "position": 2, "status": "IN_CORRECTION", "version": 2, "correctable": true, "hasBeenCorrected": true } ]}beingCorrected: alguien está corrigiendo la obra ahora mismo. No dice quién.correctable: la obra y el capítulo están abiertos a corrección y el capítulo no está bloqueado.hasBeenCorrected: algún lector empezó a corregir este capítulo alguna vez.
POST /connect/works/{workId}/correction-opening — works:write
Sección titulada «POST /connect/works/{workId}/correction-opening — works:write»Pedir correcciones: abre la obra y los capítulos indicados. Ver Pedir correcciones.
{ "chapterIds": ["0192f8a3-…-01"], "publishIfDraft": false }Respuesta 200 con la misma forma que /status. Errores propios:
409 ILLEGAL_WORK_TRANSITION (obra en borrador sin publishIfDraft), 422 CHAPTER_NOT_IN_WORK,
409 CHAPTER_BLOCKED.
Correcciones
Sección titulada «Correcciones»GET /connect/corrections — feedback:read
Sección titulada «GET /connect/corrections — feedback:read»Las correcciones entregadas a la persona, de la más reciente a la más antigua.
| Parámetro | Valores | Por defecto |
|---|---|---|
workId |
Solo las de esta obra | todas |
chapterId |
Solo las de este capítulo | todos |
unread |
true: solo las que la autora no ha abierto |
false |
hidden |
true: solo las que la autora apartó |
false |
limit |
de 1 a 100 | 50 |
offset |
desde 0 | 0 |
{ "corrections": [ { "correctionId": "0192f8a4-…", "workId": "0192f8a2-…", "workTitle": "El cuaderno de bitácora", "chapterId": "0192f8a3-…-01", "chapterTitle": "Uno", "chapterPosition": 2, "readerId": "0192f8a1-…", "anonymous": false, "authorLabel": "@lectora", "origin": "BETA_READER", "visibility": "VISIBLE", "questionnaireVersion": 2, "submittedAt": "2026-11-05T12:00:00+00:00", "read": false, "stars": null, "replied": false, "betweenWritingBuddies": false } ]}anonymous: quien corrigió pidió no ser identificado;readerIdlleganullyauthorLabeldice cómo nombrarlo.origin:BETA_READER(lector con cuenta) oPUBLIC_LINK(alguien sin cuenta, por un enlace público).visibility:VISIBLE,LOCKED(retenida por saldo negativo: sin contenido hasta que se recupere) oHIDDEN_BY_AUTHOR.
GET /connect/corrections/{correctionId} — feedback:read
Sección titulada «GET /connect/corrections/{correctionId} — feedback:read»Una corrección con las respuestas a su cuestionario. Abrirla la marca como leída (salvo que
esté LOCKED).
{ "correctionId": "0192f8a4-…", "chapterId": "0192f8a3-…-01", "visibility": "VISIBLE", "questionnaireVersion": 2, "submittedAt": "2026-11-05T12:00:00+00:00", "answers": [ { "questionId": "0192f8a5-…", "position": 1, "statement": "¿Cómo funciona el ritmo?", "type": "TEXT", "text": "El arranque es lento, pero…", "wordCount": 64, "value": null, "chosen": [] }, { "questionId": "0192f8a5-…", "position": 2, "statement": "¿Te ha enganchado?", "type": "YES_NO", "text": "", "wordCount": 0, "value": true, "chosen": [] } ]}statementes el enunciado tal como estaba cuando se respondió, aunque la autora haya cambiado el cuestionario después.typeesTEXT,SCALE,SINGLE_CHOICE,MULTIPLE_CHOICEoYES_NO. La respuesta está entext(TEXT),value(SCALEoYES_NO) ochosen(las de opciones, con la etiqueta de cada opción marcada).- Con
visibility: LOCKED,answersllega vacío.
GET /connect/corrections/{correctionId}/chapter-text — feedback:read
Sección titulada «GET /connect/corrections/{correctionId}/chapter-text — feedback:read»El texto exacto sobre el que se hizo la corrección.
{ "correctionId": "0192f8a4-…", "chapterId": "0192f8a3-…-01", "title": "Uno", "contentHtml": "<p>Primer capítulo…</p>", "wordCount": 900, "version": 1, "isCurrentVersion": false}isCurrentVersion: false significa que el capítulo se ha reescrito desde entonces: útil para
enseñar la corrección junto al texto que la motivó.
Créditos
Sección titulada «Créditos»GET /connect/credits/balance — credits:read
Sección titulada «GET /connect/credits/balance — credits:read»{ "balance": 12 }El saldo puede ser negativo. Solo se puede leer: ninguna aplicación puede mover créditos.
GET /connect/works/{workId}/correction-affordability — credits:read
Sección titulada «GET /connect/works/{workId}/correction-affordability — credits:read»Si el saldo alcanza para recibir una corrección de cada capítulo de una obra propia.
{ "workId": "0192f8a2-…", "balance": 12, "chapters": [ { "chapterId": "0192f8a3-…-01", "price": 4, "affordable": true }, { "chapterId": "0192f8a3-…-02", "price": 15, "affordable": false } ]}Usa affordable tal cual: lo decide la plataforma, con reglas que no se ven desde fuera (por
ejemplo, el descubierto concedido). Un capítulo recién creado puede tardar un momento en tener
precio; una obra sin ningún capítulo con precio responde 404 WORK_NOT_FOUND.
Fuera de /connect
Sección titulada «Fuera de /connect»| Endpoint | Para qué |
|---|---|
GET /api/v1/genres |
El catálogo de temáticas (code, name). Público, sin token |
GET /api/v1/oauth/authorize, POST /api/v1/oauth/token, POST /api/v1/oauth/revoke |
Ver Autorización |