Base: https://api.editorbrain.com. Las rutas de cliente usan /v1. Esta guía explica las operaciones y los contratos principales del código revisado; consulta versiones para disponibilidad. No es una especificación OpenAPI ni promete endpoints administrativos a los clientes.
Autenticación y alcance
Para una credencial de API autorizada:
Authorization: Bearer TU_CREDENCIAL
Content-Type: application/json
Mantén el secreto en tu gestor de credenciales. El workspace se deriva de la autorización; enviar otro workspaceId no concede acceso. En la versión publicada, las claves están ligadas al espacio autorizado. Las conexiones OAuth pueden estar limitadas adicionalmente por permisos del miembro y alcance de equipo.
reader: consultas permitidas por su alcance.editor: escrituras permitidas; no implica acceso a todas las operaciones de gasto.owner: administración del espacio, sin acceso automático a otros espacios ni al laboratorio interno.
La sesión web usa su propio flujo y protecciones; no copies cookies del navegador para construir una integración. La configuración de notificaciones, cuenta, registro y recuperación pertenece a ese flujo web. Usa el consentimiento de dispositivo del CLI o el OAuth del MCP para conectar agentes.
Primera consulta
curl --fail-with-body --silent --show-error \
-H "Authorization: Bearer $EDITORBRAIN_API_KEY" \
https://api.editorbrain.com/v1/me
El ejemplo supone que el gestor de secretos ya suministró la variable. No escribas su valor en el comando ni actives trazas del shell. /v1/me devuelve identidad, workspace, ámbito y límites; no presupongas que la forma exacta será idéntica para un miembro de equipo restringido.
Leer el contexto de una edición
POST /v1/workflow/check
{"projectId":"mi-proyecto"}
La respuesta incluye modo de revisión, preferencias resueltas, editorialSnapshot, integraciones y versiones del contexto. Si pasas previousVersion y previousContextVersion, revisa tanto changed como contextChanged. Un cambio documental no se detecta solamente con la versión de preferencias de revisión.
interaction, agregado después de 0.39.1, describe cómo consultar/revisar sin imponer un wizard. Tolera su ausencia en APIs anteriores. El servidor registra un recibo de lectura; no certifica que el agente entendió o editó el video.
Documentos y concurrencia
GET /v1/documents/videos/mi-proyecto/brief.md
PUT /v1/documents/videos/mi-proyecto/brief.md
Cuerpo de la escritura:
{"content":"# Objetivo\nExplicar el producto con claridad.\n","expectedRevision":3}
Usa la revisión que acabas de leer; 0 crea un documento nuevo. El ejemplo 3 es ilustrativo, no un valor que puedas reutilizar en cualquier cuenta. La respuesta devuelve la nueva revisión y hash.
Ante un conflicto 409: vuelve a leer, conserva cambios ajenos, recompón la intención del usuario y envía una escritura con la revisión actual. No reintentes la misma escritura a ciegas. Codifica cada segmento de la ruta con encodeURIComponent; conserva las barras que separan carpetas. No se aceptan rutas de archivos arbitrarios del servidor.
Buscar desde un brief
POST /v1/search/brief
{
"projectId":"mi-proyecto",
"mode":"both",
"brief":{
"source":{"kind":"script","summary":"Comparación de dos formas de organizar tareas","inspected":["script"],"coverage":"Guion completo leído"},
"goal":"Explicar cuándo conviene cada opción",
"audience":"Profesionales que empiezan con IA",
"tone":"Claro y cercano",
"pacing":"Ágil con pausas para leer",
"availableAssets":["Capturas propias"],
"missingAssets":[],
"hardConstraints":["Conservar colores de marca"],
"uncertainty":[],
"styleQuery":"comparación visual con demostración",
"eventQueries":["contraste entre dos alternativas"]
}
}
inspected y coverage deben describir una inspección real. La API recupera candidatos; no realiza ni aprueba la decisión creativa. detail es summary por defecto; solicita full solo si necesitas más evidencia. search/edit es análisis explícito opcional, no fallback automático.
Índice de operaciones
Las rutas siguientes requieren autorización salvo /health. {id}, {project}, {revision} y {path} son marcadores. Los cuerpos exactos de muchas operaciones están también en las herramientas equivalentes de la referencia MCP; en REST, los IDs de la ruta no siempre se repiten en el cuerpo. La tabla no describe rutas internas de operación, callbacks de proveedores ni URLs firmadas.
Identidad, marcas y documentos
| Método | Ruta | Entrada / propósito |
|---|---|---|
| GET | /health | Estado básico y versión; no prueba proveedores |
| GET | /v1/me | Identidad, espacio y límites |
| GET | /v1/brands | limit, after; marcas accesibles |
| GET | /v1/projects | brand, limit, after; proyectos accesibles |
| GET | /v1/documents | prefix; listado acotado |
| GET / PUT | /v1/documents/{path} | Leer (opcional revision) o escribir content, expectedRevision |
| GET | /v1/history | path, opcional before |
| POST | /v1/history/restore | path, revisión fuente y expectedRevision actual |
| GET | /v1/projects/{project}/style-policy | Effective rules/hashes and project decisions; verification not assessed (next release) |
| POST | /v1/projects/{project}/resolve | Contexto efectivo |
| POST | /v1/projects/{project}/export | adapter: neutral, hyperframes o remotion |
| GET / POST | /v1/keys | Owner: listar o crear con label, role |
| DELETE | /v1/keys/{id} | Owner: revocar clave; no la propia activa |
Preferencias, memoria y revisión editorial
| Método | Ruta | Entrada / propósito |
|---|---|---|
| GET / PUT | /v1/workflow | Leer; escribir mode, expectedRevision |
| POST | /v1/workflow/check | projectId, versiones previas, previousSourceHashes (hasta256) y questionNeeds opcionales |
| GET | /v1/integrations | Preferencias personales del miembro |
| PUT | /v1/integrations/{provider} | Configuración validada y revisión esperada |
| GET | /v1/brain | brandId; estado de propuesta del cerebro |
| POST | /v1/brain/prepare | Preparar propuesta; disponibilidad y consumo propios |
| POST | /v1/brain/accept | Aceptar propuesta revisada con sus precondiciones |
| GET / POST | /v1/memory | Consulta por scope, scopeId; cambio de entradas con revisión |
| POST | /v1/memory/promote | Promoción explícita de aprendizaje a un ámbito |
| POST | /v1/feedback | Registrar observación de proyecto |
| GET | /v1/improvements | brandId; propuestas de mejora |
| POST | /v1/improvements/settings | Configuración de propuestas |
| POST | /v1/improvements/run | Solicitar propuesta para brandId; comprobar disponibilidad |
| POST | /v1/improvements/accept | Aceptar una propuesta concreta con revisión |
| GET / POST | /v1/product-learning | Consentimiento separado para aprendizaje del producto |
| POST | /v1/product-learning/signals | Señal acotada bajo consentimiento |
Bibliotecas
| Método | Ruta | Entrada / propósito |
|---|---|---|
| POST | /v1/search/brief | Brief del agente; ver ejemplo superior |
| GET | /v1/style-sources/{id}/source | version, sha256; código de estilo autorizado con enlace temporal |
| POST | /v1/search/edit | Análisis de edición solicitado explícitamente |
| GET | /v1/library | query, limit, after |
| GET | /v1/library/{id} | Ficha y evidencias accesibles |
| GET | /v1/library/{id}/documents | path, opcional sha256 |
| GET | /v1/library/{id}/media/{sha256} | Bytes de un medio autorizado |
| GET | /v1/narrative | query, kind, channel, limit |
| GET | /v1/library/{id}/narrative | eventOffset, relationOffset, limit, sha256 |
| GET | /v1/style-packs | Estilos disponibles |
| POST | /v1/projects/{project}/recommend-styles | Recomendaciones según material/capacidades |
| POST | /v1/projects/{project}/preview-direction | Preparar dirección, no render |
| GET | /v1/media-styles | category: image o motion |
| GET | /v1/media-styles/{id} | version de receta |
| GET | /v1/motion-components | q; componentes locales reutilizables |
| GET | /v1/motion-components/{id} | version de componente |
| GET | /v1/authored-motion | q, limit, after, version, material, funcion, encuadre, tresD |
| GET | /v1/authored-motion/{id} | version de escena |
| GET | /v1/authored-motion/{id}/preview | version, ratio, kind, opcional preset; enlace de preview |
| GET / HEAD | /v1/authored-motion/{id}/media | Preview autorizada con versión/formato; bytes |
| GET | /v1/authored-motion/{id}/source | version, sha256 del bundle; enlace de fuente |
| GET / PUT | /v1/library-favorites | Leer por brandId; guardar/quitar selección del miembro |
| GET | /v1/sfx/catalog | brandId, bankId; explorar banco accesible |
| GET / HEAD | /v1/sfx/preview | Preview con identidad de banco/sonido devuelta por catálogo |
| GET | /v1/sfx/search | projectId, query, bankId, limit, sceneRole |
| GET | /v1/sfx/get | Proyecto, banco, soundId, catalogSha256 y rol de escena |
| POST | /v1/sfx/check | projectId en query; plan y hash de contexto en cuerpo |
Material, almacenamiento y herramientas
| Método | Ruta | Entrada / propósito |
|---|---|---|
| GET | /v1/resources/guide | Campos y usos de material reutilizable |
| GET | /v1/resources | query, brand, kind, state, limit, after |
| GET / PUT | /v1/resources/{id} | Leer o guardar resource, expectedRevision, confirmación aplicable |
| GET / PUT | /v1/resources/{id}/index | Segmentos (offset, limit) o guardar índice versionado |
| GET | /v1/assets | limit, cursor; archivos accesibles |
| PUT | /v1/assets/{sha256} | Bytes, tipo y longitud; name, purpose, projectId, sourceSha256 |
| GET / HEAD | /v1/assets/{sha256} | Descargar o consultar archivo |
| GET | /v1/storage | Cuota, uso y candidatos de limpieza |
| GET | /v1/storage/preview-upload | sha256, bytes, projectId; plan previo |
| POST | /v1/storage/cleanup | Selección explícita validada; protege archivos necesarios |
| GET | /v1/studio/catalog | Herramientas, precios, permisos y disponibilidad |
| GET | /v1/studio/voices | Catálogo público de alias Vox; filtros q, language, accent, gender |
| GET | /v1/studio/voices/{id}/preview | Muestra de catálogo con autenticación, cuando exista; no genera narración |
| GET | /v1/studio/voice-selection | Exactamente uno de brandId o projectId; selección, herencia, ruta canónica y revisión |
| PUT | /v1/studio/voice-selection | brandId o projectId, voiceId, expectedRevision; modifica solo audio.json.voice |
| POST | /v1/studio/quotes | Solicitud Tempo/Prism/Vox/Aura; cotización |
| POST | /v1/studio/jobs | quoteId, maxCredits, userConfirmed, lease de lote si aplica |
| GET | /v1/studio/jobs | Historial; after |
| GET | /v1/studio/jobs/{id} | Estado y resultados; consultar sin duplicar |
| GET | /v1/billing/status | Saldo, plan, oferta y disponibilidad |
| POST | /v1/billing/checkout | Oferta e intento autorizados; requiere propietario habilitado |
| POST | /v1/billing/portal | Portal de membresía/pago habilitado |
| POST | /v1/billing/welcome | Beneficio inicial sujeto a elegibilidad |
| POST | /v1/billing/reward | rewardId; beneficio elegible, no créditos arbitrarios |
Proyectos, lotes, feedback y equipos
| Método | Ruta | Entrada / propósito |
|---|---|---|
| GET | /v1/projects/progress | ids separados por coma; resumen |
| GET / POST | /v1/projects/{project}/progress | Leer o cambiar con versión esperada y confirmación aplicable |
| GET / POST | /v1/batches | Listar (after) o crear lote de proyectos existentes |
| GET / POST | /v1/batches/{id} | Estado o acción con revisión esperada |
| POST | /v1/batches/{id}/lease | Claim/renew/release/attention de turno |
| GET / POST | /v1/projects/{project}/production-reviews | Listar (after) o registrar revisión |
| DELETE | /v1/projects/{project}/production-reviews/{revision} | Revocar revisión |
| GET | /v1/projects/{project}/production-reviews/{revision}/transcript | Transcripción de esa versión |
| POST | /v1/projects/{project}/production-reviews/{revision}/approve | Confirmación del usuario y contexto exacto |
| POST | /v1/projects/{project}/production-reviews/{revision}/changes | Cambio localizado y contexto exacto |
| GET | /v1/projects/{project}/production-feedback | status, revisionId, after |
| POST | /v1/projects/{project}/production-feedback/{id}/resolve | Evidencia de la corrección y nueva versión |
| GET / POST | /v1/reviews | Listar por projectId o crear enlace explícito de revisión |
| DELETE | /v1/reviews/{id} | Revocar enlace |
| GET | /v1/team | Alcance y capacidades del miembro |
| GET | /v1/team/members | Integrantes e invitaciones; solo propietario |
| PATCH | /v1/team/members/{id} | Solo propietario: {expectedRevision,grants:[{kind,scopeId}],userConfirmed:true}; sustituye concesiones con control de concurrencia |
| DELETE | /v1/team/members/{id} | Retirar miembro autorizado |
| POST | /v1/team/invitations | Invitar correo con tipo/alcance; envía correo real |
| DELETE | /v1/team/invitations/{id} | Revocar invitación |
| POST | /v1/team/preview | Browser autenticado: {token}, destinatario verificado; muestra alcance sin aceptar |
| POST | /v1/team/accept | Browser autenticado: {token}; aceptación explícita, selecciona el espacio compartido |
| GET | /v1/team/projects | Proyectos accesibles al equipo |
| GET | /v1/team/projects/{project}/reviews | Versiones compartidas; after |
| GET | /v1/team/projects/{project}/reviews/{revision}/comments | Comentarios públicos de esta versión, after, nextCursor; acceso revalidado en cada página |
| POST | /v1/team/projects/{project}/reviews/{revision}/share | Compartir o retirar versión según acción |
| POST | /v1/team/projects/{project}/reviews/{revision}/comment | Comentario y momento opcional |
| POST | /v1/team/projects/{project}/reviews/{revision}/approve | Aprobación explícita de versión/contexto |
GET /v1/team/members incluye permissionsRevision para cada colaborador
restringido. Usa ese valor como expectedRevision al guardar la lista completa de
1–100 concesiones (brand_editor o project_reviewer); no envíes un workspace ID.
team_permissions_changed (409) exige releer y reconciliar. Guardar invalida enlaces
anteriores. Si el miembro queda solo como revisor, revoca sus conexiones de agente;
no borra archivos. Para quitar todos los accesos usa DELETE.
Paginación
No todos los endpoints usan el mismo cursor. Devuelve al mismo endpoint el valor recibido con los mismos filtros. En motion, after es opaco y está ligado a consulta/facetas/versión. Si construyes URLs con URLSearchParams, pasa el cursor original y deja que esa función lo codifique una vez. No uses decodeURIComponent sobre él.
Un cambio de filtro comienza una consulta nueva. Una lista vacía no equivale a pérdida de permisos ni prueba que no exista material en otra página. No amplíes la búsqueda a otro cliente para rellenarla.
Archivos y URLs temporales
Una subida de assets requiere Content-Length entre 1 byte y 90 MiB y un MIME aceptado (MP4/MOV/WebM, PNG/JPEG/WebP, MP3/WAV/M4A/OGG). El ID es el SHA-256 de los bytes; el servicio lo verifica. La cuota del espacio puede ser menor que el tamaño máximo técnico.
Los archivos se autorizan por espacio/proyecto, no por conocer el hash. Guarda IDs y hashes, no URLs firmadas temporales. Cuando venza un enlace, vuelve a solicitarlo con la credencial apropiada. En descargas parciales, respeta Range, 206 y 416.
Errores y reintentos
Formato de error HTTP habitual:
{"error":{"code":"revision_conflict","message":"El documento cambió; vuelve a leerlo."}}
El texto del ejemplo es ilustrativo. Usa error.code, estado HTTP y error.recovery cuando exista; no hagas parsing del mensaje. 401: autenticación; 403: permisos; 404: recurso no accesible; 409: conflicto; 413/415: tamaño/formato; 429: espera; 503: capacidad no disponible. La API añade Retry-After en respuestas 429.
Los GET se pueden reintentar con espera acotada cuando el fallo sea transitorio. No reintentes un POST de gasto por un timeout sin consultar el intento original. Para Studio conserva quoteId/job ID; para pagos conserva el ID de intento. No inventes un header universal de idempotencia: cada operación define su mecanismo.
Descubrir y retomar proyectos
Este contrato requiere API 0.45.0 o posterior. Comprueba su disponibilidad antes de depender de estas rutas.
GET /v1/projects admite brand,
query, updatedSince, updatedBefore, sort=recent|id, limit y after.
Las fechas son ISO UTC; el intervalo incluye el inicio y excluye el final.
La consulta compara literalmente ID/nombre/tema. lastActivityAt usa tiempos
servidor de documentos y progreso. checkpoint resume el último hito con su
revisión/hash y fecha servidor, no la fecha declarada por el agente; no implica
aprobación. Continúa con nextCursor sin modificarlo y conserva filtros y espacio.
Es un listado vivo: deduplica por ID y reinicia sin cursor para una lectura nueva.
Se aplican los permisos actuales de marca/proyecto en cada página. No hay un
filtro de proyectos archivados; un hito completed no oculta el proyecto.
GET /v1/projects/ID/continuity reúne contexto, checkpoint, revisiones, feedback
pendiente, lote, trabajos y catálogo de assets autorizados. Cada sección indica
available con value, o unavailable con el motivo; las listas acotadas declaran
complete/nextCursor. Los jobs Studio pertenecen a la conexión actual y Render
al usuario actual. No se exponen proveedores ni rutas privadas del dispositivo.
La consulta no inicia trabajos, refresca facturación ni descarga medios.
El registro de carpetas de cada dispositivo es privado y no forma parte de esta API.
lastApprovedReview recupera la última aprobación histórica aunque no aparezca
en la primera página. Solo effectiveApproval=true confirma que sigue vigente;
puede haberse invalidado por cambios de contexto, feedback o disponibilidad.
Acepta reviewsAfter, feedbackAfter y studioAfter para continuar esas listas.
Un 409 continuity_changed exige repetir la lectura, porque el contexto cambió.
Un recurso catalogado no acredita sus bytes ni equivale a un enlace público:
para recuperarlo usa el endpoint de descarga autorizado y verifica su hash.
Las preferencias guardadas no conceden permiso de gasto.
Los checkpoints v1 y v2 viajan por la API existente de documentos, con su revisión esperada. V2 conserva versión declarada, artefactos relativos, dependencias, comando orientativo y hashes del contexto; nunca se ejecuta contenido guardado. La historia y restauración usan los endpoints existentes de documentos: restaurar crea una nueva revisión, no borra versiones previas ni altera aprobaciones.
Mapa de tareas y orientación compacta
GET /v1/guide/tasks devuelve los temas públicos de ayuda; ?topic=sonido
devuelve una ruta con comandos, herramientas y referencias. Requiere la sesión
autenticada habitual; no busca recursos, ejecuta tareas ni anuncia capacidades
privadas. Los handlers de cada operación siguen comprobando sus permisos.
POST /v1/workflow/check admite detail: "summary" | "full". La respuesta
completa sigue siendo el default. El resumen tiene
kind: "editorbrain.workflow-summary", coverage explícita y el camino de
vuelta al detalle; no contiene un editorialSnapshot completo.
nextActions sólo orienta, incluso cuando hay recursos sin registrar.