Esta é a lista completa do que a API pública do RecReview aceita e devolve. Para criar uma chave e escolher as permissões, comece por Chaves de API e a API pública.
Antes de começar: a API exige assinatura Studio paga. Creator, Pro e o período de teste não incluem.
O básico
- URL base:
https://rec.review/api/v1 - Autenticação: mande
Authorization: Bearer rr_live_...em toda requisição. Cada chave pertence a um workspace, então você nunca informa o id do workspace. - Formato: corpos de requisição e resposta em JSON. Campos que a API não conhece são recusados com erro
400. - Datas: ISO 8601 com hora, como
2026-10-30T15:00:00.000Z. - Respostas: sucesso é
{ "success": true, "data": ... }. Erro é{ "success": false, "error": "...", "code": "..." }.
Rotas
| Chamada | Permissão | O que faz |
|---|---|---|
GET /me |
Qualquer | Mostra nome, permissões e workspace da chave |
POST /tasks |
Criar tarefas | Cria uma tarefa de vídeo ou de galeria de fotos |
GET /tasks |
Ler tarefas | Lista tarefas, da atualizada mais recentemente para a mais antiga |
GET /tasks/:id |
Ler tarefas | Lê uma tarefa com links, tags e versões |
PATCH /tasks/:id |
Atualizar tarefas | Atualiza uma tarefa |
POST /tasks/:id/attachments |
Atualizar tarefas | Adiciona links a uma tarefa |
GET /tasks/:id/comments |
Ler comentários de revisão | Lê os comentários de uma versão |
POST /tasks/:id/verdict |
Registrar o veredito do cliente | Registra o que o cliente decidiu fora do app |
GET /time-entries |
Ler horas | Lê as horas registradas |
GET /clients |
Ler clientes | Lista os clientes |
POST /clients |
Criar clientes | Adiciona um cliente |
GET /projects |
Ler projetos | Lista os projetos, com filtro opcional por clientId |
POST /projects |
Criar projetos | Adiciona um projeto |
GET /members |
Ler membros | Lista quem pode ser responsável por uma tarefa |
GET /workflow |
Ler status, fases e bloqueios | Lista as chaves de status e de fase e os ids de bloqueio |
Criar uma tarefa
POST /tasks responde 201 com a tarefa. Só title é obrigatório.
| Campo | Tipo | Observação |
|---|---|---|
title |
texto, até 256 caracteres | Obrigatório |
kind |
video ou gallery |
O padrão é video |
description |
texto, até 5.000 caracteres | |
clientId |
id | Um cliente do workspace |
projectId |
id | O cliente vem do projeto. Se mandar clientId junto, ele tem que bater |
assignedToUserId |
id | Um membro ativo, de GET /members |
status |
chave | De GET /workflow. Status desconhecido cai na primeira coluna |
phase |
chave | De GET /workflow |
waitingForBlockerId |
id | De GET /workflow |
dueDate |
data | O prazo do cliente |
internalDueDate |
data | O prazo da equipe. Tem que ser igual ou anterior a dueDate |
isUrgent |
true ou false | |
priority |
low, medium, high ou urgent |
|
tags |
lista de textos, até 20 | |
estimatedHours |
número | |
talent |
texto | Só em tarefa de vídeo |
estimatedVideoDuration |
número inteiro | Só em tarefa de vídeo |
attachments |
lista de até 20 { "type": "link", "name": "...", "url": "..." } |
Links absolutos http ou https. type pode ficar de fora |
Mande o cabeçalho Idempotency-Key, com até 255 caracteres, baseado no evento que disparou a requisição. Se a mesma chave chegar de novo com o mesmo corpo, você recebe a tarefa já criada, com 200 e o cabeçalho Idempotent-Replayed: true. A mesma chave com corpo diferente responde 422.
Listar tarefas
GET /tasks aceita estes filtros:
| Parâmetro | Observação |
|---|---|
clientId, projectId, assignedToUserId |
Só as tarefas que batem |
status, phase |
Chaves de GET /workflow |
q |
Busca por texto |
kind |
video (padrão), gallery ou all |
limit |
Até 200. O padrão é 50 |
cursor |
O valor de nextCursor da página anterior |
A resposta é { "success": true, "data": [...], "nextCursor": "..." }. Quando nextCursor é null, não há mais páginas.
Cada item traz id, kind, title, videoCode, status, phase, clientId, projectId, assignedToUserId, waitingForBlockerId, isUrgent, dueDate, internalDueDate, createdAt, updatedAt e url.
GET /tasks/:id acrescenta description, tags, attachments, gallery e versions. Cada versão traz id, versionNumber, title, createdAt, isLatestVersion, reviewStatus e reviewVerdict.
Atualizar uma tarefa
PATCH /tasks/:id aceita title, description, status, phase, isUrgent, assignedToUserId, waitingForBlockerId, dueDate, internalDueDate, tags, estimatedHours e talent. Mande só o que mudou. Mande null para limpar um campo, exceto title, status, isUrgent e tags.
Mudar o status, a fase ou o bloqueio roda as suas automações. O cliente e o projeto de uma tarefa não mudam pela API.
Adicionar links
POST /tasks/:id/attachments recebe { "attachments": [{ "type": "link", "name": "Roteiro", "url": "https://..." }] }. Adiciona até 20 links por chamada e mantém os que já existem. Cada tarefa guarda no máximo 50.
Ler comentários
GET /tasks/:id/comments devolve a versão mais recente. Mande versionId para ler outra. A resposta é { "success": true, "data": { "version": { "id", "versionNumber" }, "comments": [...] } }.
Cada comentário traz id, timestamp (segundos do vídeo), timelineEndTimestamp, content, type, status, isPrivate, authorName, authorIsTeam, createdAt, resolvedAt, attachmentsCount e replies. Comentários só da equipe vêm junto.
Registrar o veredito do cliente
POST /tasks/:id/verdict recebe:
| Campo | Valores |
|---|---|
verdict |
approved ou changes_requested. Obrigatório |
channel |
whatsapp, email, meeting ou other. Obrigatório |
sendFinalEmail |
true ou false. Vale para aprovações, e o padrão é enviar |
Atenção: a aprovação faz a entrega final. O RecReview manda o e-mail ao cliente e dispara o webhook
video.delivery_approved, a menos que você mande"sendFinalEmail": false, que desliga só o e-mail.
Só funciona na versão mais recente. Uma versão já aprovada, ou que já tem esse veredito, responde 409.
Ler horas
GET /time-entries aceita from, to, clientId, projectId, taskId, userId e limit. O limit vai até 5.000 e o padrão é 500. Esta lista não tem páginas, então reduza o período se precisar de mais.
Cada registro traz id, userId, userName, taskId, projectId, versionId, title, notes, startedAt, stoppedAt, durationSeconds e isRunning.
Clientes e projetos
POST /clients exige name e code. O código tem de 2 a 12 letras ou números e vira o prefixo dos códigos de vídeo do cliente. contactName, contactEmail e contactPhone são opcionais. Código já em uso responde 409.
POST /projects exige name e clientId. code, description e dueDate são opcionais.
GET /clients e GET /projects devolvem todos os registros de uma vez, sem páginas.
Erros
| Status | Códigos | O que significa |
|---|---|---|
400 |
invalid_request, invalid_idempotency_key |
Algo na requisição é inválido, ou um id enviado no corpo não é deste workspace. invalid_idempotency_key indica que o cabeçalho Idempotency-Key é inválido |
401 |
missing_api_key, invalid_api_key, api_key_revoked, api_key_expired, api_key_creator_inactive |
A chave não pode ser usada |
403 |
insufficient_scope |
A chave não tem essa permissão |
403 |
plan_required, trial_expired, subscription_inactive |
O workspace não está numa assinatura Studio paga |
404 |
not_found |
A tarefa ou versão da URL não existe, ou é de outro workspace |
409 |
conflict, attachment_limit, no_version, already_approved, already_recorded, verdict_changed, not_latest_version, idempotency_in_progress, idempotency_resource_gone |
A requisição conflita com o estado atual |
422 |
idempotency_key_reused |
A mesma Idempotency-Key veio com corpo diferente |
429 |
rate_limited, daily_task_limit |
Passou de um limite. Espere e tente de novo |
Limites
- 120 requisições por minuto por chave.
- 2.000 tarefas criadas pela API por workspace a cada 24 horas.
- Muitas tentativas de autenticação com falha vindas do mesmo endereço ficam bloqueadas por alguns minutos.
Para reagir a eventos em vez de perguntar por eles, use os webhooks.