Esta es la lista completa de lo que la API pública de RecReview acepta y devuelve. Para crear una clave y elegir sus permisos, empieza por Claves de API y la API pública.
Antes de empezar: la API requiere una suscripción Studio de pago. Creator, Pro y la prueba gratuita no la incluyen.
Lo básico
- URL base:
https://rec.review/api/v1 - Autenticación: envía
Authorization: Bearer rr_live_...en cada solicitud. Cada clave pertenece a un workspace, así que nunca indicas el id del workspace. - Formato: cuerpos de solicitud y respuesta en JSON. Los campos que la API no conoce se rechazan con un error
400. - Fechas: ISO 8601 con hora, como
2026-10-30T15:00:00.000Z. - Respuestas: el éxito es
{ "success": true, "data": ... }. El error es{ "success": false, "error": "...", "code": "..." }.
Rutas
| Llamada | Permiso | Qué hace |
|---|---|---|
GET /me |
Cualquiera | Muestra el nombre, los permisos y el workspace de la clave |
POST /tasks |
Crear tareas | Crea una tarea de video o de galería de fotos |
GET /tasks |
Leer tareas | Lista tareas, de la actualizada más recientemente a la más antigua |
GET /tasks/:id |
Leer tareas | Lee una tarea con sus enlaces, etiquetas y versiones |
PATCH /tasks/:id |
Actualizar tareas | Actualiza una tarea |
POST /tasks/:id/attachments |
Actualizar tareas | Añade enlaces a una tarea |
GET /tasks/:id/comments |
Leer comentarios de revisión | Lee los comentarios de una versión |
POST /tasks/:id/verdict |
Registrar el veredicto del cliente | Registra lo que el cliente decidió fuera de la app |
GET /time-entries |
Leer horas | Lee las horas registradas |
GET /clients |
Leer clientes | Lista los clientes |
POST /clients |
Crear clientes | Añade un cliente |
GET /projects |
Leer proyectos | Lista los proyectos, con filtro opcional por clientId |
POST /projects |
Crear proyectos | Añade un proyecto |
GET /members |
Leer miembros | Lista a quienes pueden ser responsables de una tarea |
GET /workflow |
Leer estados, fases y bloqueos | Lista las claves de estado y de fase y los ids de bloqueo |
Crear una tarea
POST /tasks responde 201 con la tarea. Solo title es obligatorio.
| Campo | Tipo | Observación |
|---|---|---|
title |
texto, hasta 256 caracteres | Obligatorio |
kind |
video o gallery |
El valor predeterminado es video |
description |
texto, hasta 5.000 caracteres | |
clientId |
id | Un cliente del workspace |
projectId |
id | El cliente viene del proyecto. Si también envías clientId, tiene que coincidir |
assignedToUserId |
id | Un miembro activo, de GET /members |
status |
clave | De GET /workflow. Un estado desconocido cae en la primera columna |
phase |
clave | De GET /workflow |
waitingForBlockerId |
id | De GET /workflow |
dueDate |
fecha | El plazo del cliente |
internalDueDate |
fecha | El plazo del equipo. Tiene que ser igual o anterior a dueDate |
isUrgent |
true o false | |
priority |
low, medium, high o urgent |
|
tags |
lista de textos, hasta 20 | |
estimatedHours |
número | |
talent |
texto | Solo en tareas de video |
estimatedVideoDuration |
número entero | Solo en tareas de video |
attachments |
lista de hasta 20 { "type": "link", "name": "...", "url": "..." } |
Enlaces absolutos http o https. type se puede omitir |
Envía el encabezado Idempotency-Key, de hasta 255 caracteres, basado en el evento que originó la solicitud. Si la misma clave llega otra vez con el mismo cuerpo, recibes la tarea ya creada, con 200 y el encabezado Idempotent-Replayed: true. La misma clave con un cuerpo distinto responde 422.
Listar tareas
GET /tasks acepta estos filtros:
| Parámetro | Observación |
|---|---|
clientId, projectId, assignedToUserId |
Solo las tareas que coinciden |
status, phase |
Claves de GET /workflow |
q |
Búsqueda por texto |
kind |
video (predeterminado), gallery o all |
limit |
Hasta 200. El valor predeterminado es 50 |
cursor |
El valor de nextCursor de la página anterior |
La respuesta es { "success": true, "data": [...], "nextCursor": "..." }. Cuando nextCursor es null, no hay más páginas.
Cada elemento trae id, kind, title, videoCode, status, phase, clientId, projectId, assignedToUserId, waitingForBlockerId, isUrgent, dueDate, internalDueDate, createdAt, updatedAt y url.
GET /tasks/:id añade description, tags, attachments, gallery y versions. Cada versión trae id, versionNumber, title, createdAt, isLatestVersion, reviewStatus y reviewVerdict.
Actualizar una tarea
PATCH /tasks/:id acepta title, description, status, phase, isUrgent, assignedToUserId, waitingForBlockerId, dueDate, internalDueDate, tags, estimatedHours y talent. Envía solo lo que cambia. Envía null para vaciar un campo, excepto title, status, isUrgent y tags.
Cambiar el estado, la fase o el bloqueo ejecuta tus automatizaciones. El cliente y el proyecto de una tarea no se pueden cambiar por la API.
Añadir enlaces
POST /tasks/:id/attachments recibe { "attachments": [{ "type": "link", "name": "Guion", "url": "https://..." }] }. Añade hasta 20 enlaces por llamada y conserva los existentes. Cada tarea guarda como máximo 50.
Leer comentarios
GET /tasks/:id/comments devuelve la versión más reciente. Envía versionId para leer otra. La respuesta es { "success": true, "data": { "version": { "id", "versionNumber" }, "comments": [...] } }.
Cada comentario trae id, timestamp (segundos del video), timelineEndTimestamp, content, type, status, isPrivate, authorName, authorIsTeam, createdAt, resolvedAt, attachmentsCount y replies. Los comentarios solo del equipo vienen incluidos.
Registrar el veredicto del cliente
POST /tasks/:id/verdict recibe:
| Campo | Valores |
|---|---|
verdict |
approved o changes_requested. Obligatorio |
channel |
whatsapp, email, meeting u other. Obligatorio |
sendFinalEmail |
true o false. Se aplica a las aprobaciones, y por defecto se envía |
Atención: la aprobación hace la entrega final. RecReview envía el correo al cliente y dispara el webhook
video.delivery_approved, salvo que envíes"sendFinalEmail": false, que solo desactiva el correo.
Solo funciona en la versión más reciente. Una versión ya aprobada, o que ya tiene ese veredicto, responde 409.
Leer horas
GET /time-entries acepta from, to, clientId, projectId, taskId, userId y limit. El limit llega hasta 5.000 y el valor predeterminado es 500. Esta lista no tiene páginas, así que acota las fechas si necesitas más.
Cada registro trae id, userId, userName, taskId, projectId, versionId, title, notes, startedAt, stoppedAt, durationSeconds y isRunning.
Clientes y proyectos
POST /clients requiere name y code. El código tiene de 2 a 12 letras o números y se convierte en el prefijo de los códigos de video del cliente. contactName, contactEmail y contactPhone son opcionales. Un código ya en uso responde 409.
POST /projects requiere name y clientId. code, description y dueDate son opcionales.
GET /clients y GET /projects devuelven todos los registros de una vez, sin páginas.
Errores
| Estado | Códigos | Qué significa |
|---|---|---|
400 |
invalid_request, invalid_idempotency_key |
Algo en la solicitud no es válido, o un id enviado en el cuerpo no es de este workspace. invalid_idempotency_key indica que el encabezado Idempotency-Key no es válido |
401 |
missing_api_key, invalid_api_key, api_key_revoked, api_key_expired, api_key_creator_inactive |
La clave no se puede usar |
403 |
insufficient_scope |
La clave no tiene ese permiso |
403 |
plan_required, trial_expired, subscription_inactive |
El workspace no está en una suscripción Studio de pago |
404 |
not_found |
La tarea o versión de la URL no existe, o es de otro workspace |
409 |
conflict, attachment_limit, no_version, already_approved, already_recorded, verdict_changed, not_latest_version, idempotency_in_progress, idempotency_resource_gone |
La solicitud entra en conflicto con el estado actual |
422 |
idempotency_key_reused |
La misma Idempotency-Key llegó con un cuerpo distinto |
429 |
rate_limited, daily_task_limit |
Se superó un límite. Espera e inténtalo de nuevo |
Límites
- 120 solicitudes por minuto por clave.
- 2.000 tareas creadas por la API por workspace cada 24 horas.
- Demasiados intentos de autenticación fallidos desde la misma dirección quedan bloqueados unos minutos.
Para reaccionar a eventos en lugar de consultarlos, usa los webhooks.