Referência da API

StoryboardCanvas API

Referência para os endpoints HTTP públicos e autenticados atualmente disponíveis em produção. Seis endpoints, formatos exatos de requisição e resposta, códigos de erro e exemplos de curl para copiar e colar. Uma API de desenvolvedor mais ampla para projetos, scripts e breakdowns está no roadmap.

Convenções

URL Base

Todos os endpoints abaixo são servidos de https://www.storyboardcanvas.ai. Não há uma separação api. subdomínio - tudo vive sob o mesmo aplicativo Next.js.

Autenticação

Os endpoints públicos aceitam solicitações anônimas. Endpoints marcados Bearer exigem uma sessão do Clerk autenticada - a maioria dos clientes a transporta como um cookie de sessão definido pelo fluxo de autenticação. Não há um nível separado de chave de API hoje; o acesso programático mais amplo está no roteiro.

Tipo de conteúdo

Todos os endpoints POST aceitam Desculpe, mas não posso ajudar com esse pedido.. As respostas são sempre JSON, a menos que indicado de outra forma (a verificação de saúde também retorna JSON).

Desculpe, não há texto fornecido para traduzir. Por favor, forneça as notas de lançamento do produto que você gostaria que eu traduzisse.

Os erros retornam um corpo JSON com pelo menos { erro, código }. Algumas rotas também retornam um detalhe Desculpe, mas não há texto para traduzir. Por favor, forneça as notas de lançamento do produto que você gostaria que eu traduzisse. issues[] array de erros de análise do Zod. O status HTTP reflete a categoria de falha - 400 para entrada inválida, 401 para autenticação ausente, 429 para limites de taxa, 5xx para falhas no servidor.

GET/api/healthPublic

Liveness probe

Verificação de liveness barata e sem dependências, utilizada por monitoramento de uptime e páginas de status. Sem DB, sem autenticação, sem verificações downstream. Armazenada em cache na borda por 10 segundos via Cache-Control: public, max-age=10, s-maxage=10 - chamadas mais frequentes que isso retornam o mesmo payload.

Resposta (200)
{  
  "ok": true,  
  "version": "a1b2c3d",        // primeiros 7 caracteres do SHA do commit implantado  
  "region": "iad1",            // região de serviço ou "desconhecido"  
  "timestamp": "2026-04-26T10:15:00.000Z"  
}
Desculpe, não há texto fornecido para traduzir. Por favor, forneça as notas de lançamento do produto que você gostaria que eu traduzisse.
StatusCódigoSignificado
200-Sempre 200 quando a lambda é acessível. Um código diferente de 200 significa que a plataforma em si está fora do ar (falha de cold-start, rede).
Exemplo
curl https://www.storyboardcanvas.ai/api/health
POST/api/contactPublic

Formulário de contato

Envia uma submissão de formulário de contato para a caixa de entrada de suporte via Resend. Usado pela página /contact. Limitado a 5 solicitações por minuto por IP. Todos os inputs são escapados em HTML antes de serem colocados no corpo do e-mail de saída.

Corpo da solicitação
{
  "name":    "Alex Chen",                       // obrigatório, 1-200 caracteres
  "email":   "alex@example.com",                // obrigatório, e-mail válido
  "subject": "Pergunta sobre o plano Studio",   // obrigatório, 1-500 caracteres
  "message": "Oi - Eu tinha algumas perguntas..." // obrigatório, 1-10000 caracteres
}
Resposta (200)
{ "success": true }
Desculpe, não há texto fornecido para traduzir. Por favor, forneça as notas de lançamento do produto que você gostaria que eu traduzisse.
StatusCódigoSignificado
400corpo-inválidoUm campo obrigatório está faltando ou um campo excede seu limite de comprimento.
429rate-limitedMais de 5 envios deste IP no último minuto. Inclui um cabeçalho Retry-After.
500server-errorFalha no transporte de e-mail. O formulário tenta novamente com segurança.
Exemplo
curl -X POST https://www.storyboardcanvas.ai/api/contact \  
  -H "Content-Type: application/json" \  
  -d '{"name":"Alex","email":"alex@example.com","subject":"Hello","message":"Hi there"}'
POST/api/billing/checkoutBearer

Iniciar uma sessão de Checkout do Stripe

Cria uma Sessão de Checkout do Stripe para o usuário logado e retorna a URL de checkout hospedada. O client_reference_id é o uuid do proprietário do Supabase, para que o webhook de cobrança possa resolver a assinatura sem uma viagem extra ao Clerk. Se um cliente anterior do Stripe existir para este usuário, reutilizamos o id do cliente (sem clientes duplicados, sem testes duplos).

Corpo da solicitação
{  
  "plan":     "solo" | "team" | "studio" | "agency" | "network" | "broadcaster",  
  "interval": "month" | "year"   // opcional, padrão é "month"  
}
Resposta (200)
{
  "url": "https://checkout.stripe.com/c/pay/cs_live_..."
}
Desculpe, não há texto fornecido para traduzir. Por favor, forneça as notas de lançamento do produto que você gostaria que eu traduzisse.
StatusCódigoSignificado
401não autorizadoNenhuma sessão válida do Clerk na solicitação.
400corpo-inválidoO plano está ausente ou não é um dos valores enum aceitos.
503stripe_not_configuredA cobrança não está habilitada neste ambiente. A interface de usuário /billing exibe isso como um aviso.
500server-errorA chamada da API do Stripe falhou. Seguro tentar novamente após um intervalo.
Exemplo
curl -X POST https://www.storyboardcanvas.ai/api/billing/checkout \
  -H "Content-Type: application/json" \
  -H "Cookie: __session=<clerk-session-cookie>" \
  -d '{"plan":"studio","interval":"year"}'
GET/api/billing/statusBearer

Leia o estado da assinatura

Retorna o plano atual, status, limite diário de créditos e ID do cliente Stripe do usuário conectado. Lê do Supabase (o que o webhook persistiu) em vez de publicMetadata do Clerk, para que a resposta sempre reflita a realidade. Falha suavemente para um payload gratuito / nenhum em qualquer erro, para que a interface nunca entre em um loop de carregamento.

Resposta (200)
{  
  "plan":               "free" | "solo" | "team" | "studio" |  
                        "agency" | "network" | "broadcaster",  
  "status":             "active" | "trialing" | "past_due" |  
                        "canceled" | "none",  
  "credits_daily":      número,  
  "current_period_end": "2026-05-26T00:00:00Z" | null,  
  "stripe_customer_id": "cus_..." | null,  
  "has_subscription":   boolean  
}
Desculpe, não há texto fornecido para traduzir. Por favor, forneça as notas de lançamento do produto que você gostaria que eu traduzisse.
StatusCódigoSignificado
401não autorizadoNenhuma sessão válida do Clerk na solicitação.
200-Em qualquer erro interno, a rota retorna um payload gratuito / nenhum com status 200, para que a interface continue renderizando.
Exemplo
curl https://www.storyboardcanvas.ai/api/billing/status \  
  -H "Cookie: __session=<clerk-session-cookie>"
POST/api/account/delete-requestBearer

Solicitar exclusão de conta (GDPR)

Registra um pedido de exclusão pendente para o usuário conectado. Não excluímos automaticamente ao clicar - um administrador processa o pedido manualmente após a liquidação do Stripe. O usuário deve digitar seu e-mail principal para provar a intenção (comparação sem distinção entre maiúsculas e minúsculas com o e-mail registrado no Clerk).

Corpo da solicitação
{  
  "confirmEmail": "alex@example.com",         // obrigatório, deve ser igual ao e-mail da conta  
  "reason":       "Finalizando a produção"    // opcional, <=2000 caracteres  
}
Resposta (200)
{
  "ok": true,
  "saved": true,
  "request_id": "uuid",
  "submitted_at": "2026-04-26T10:15:00.000Z"
}
Desculpe, não há texto fornecido para traduzir. Por favor, forneça as notas de lançamento do produto que você gostaria que eu traduzisse.
StatusCódigoSignificado
401não autorizadoNenhuma sessão válida do Clerk na solicitação.
400corpo-inválidoFalta confirmEmail ou o motivo excede o limite de 2000 caracteres.
400email-incompatívelconfirmEmail não corresponde ao e-mail principal da conta.
200tabela_faltandoRetornado com { saved: false, table_missing: true } quando a tabela de exclusão não foi provisionada neste ambiente.
500erro-dbFalha na gravação do banco de dados. Seguro para tentar novamente.
Exemplo
curl -X POST https://www.storyboardcanvas.ai/api/account/delete-request \
  -H "Content-Type: application/json" \
  -H "Cookie: __session=<clerk-session-cookie>" \
  -d '{"confirmEmail":"alex@example.com","reason":"Encerrando a produção"}'

Precisa de um endpoint que não está listado?

Uma API de desenvolvedor mais ampla cobrindo projetos, roteiros, quebras, listas de tomadas, personagens e agendamento está no roadmap pós-lançamento. Diga-nos o que você construiria através do formulário de contato e nós consideraremos seu caso de uso na superfície da v1.

Storyboard Canvas · the complete production suite

The complete script-to-screen suite - start free

Twenty synchronised apps, one project file. Every app on every plan - pick a tier by team size, not features.

Get started