Referencia de API

StoryboardCanvas API

Referencia para los puntos finales HTTP públicos y con sesión iniciada que actualmente se encuentran en producción. Seis puntos finales, formas exactas de solicitud y respuesta, códigos de error y ejemplos de curl para copiar y pegar. Una API de desarrollador más amplia para proyectos, scripts y desgloses está en la hoja de ruta.

Convenciones

URL base

Todos los puntos finales a continuación se sirven desde https://www.storyboardcanvas.ai. No hay un separado api. subdominio - todo vive bajo la misma aplicación Next.js.

Autenticación

Los puntos finales públicos aceptan solicitudes anónimas. Los puntos finales marcados Bearer requieren una sesión de Clerk iniciada - la mayoría de los clientes la llevan como una cookie de sesión establecida por el flujo de inicio de sesión. No hay un nivel de clave API separado hoy; el acceso programático más amplio está en el hoja de ruta.

Tipo de contenido

Todos los puntos finales POST aceptan application/json. Las respuestas son siempre JSON a menos que se indique explícitamente (el sondeo de salud también devuelve JSON).

Errores

Los errores devuelven un cuerpo JSON con al menos { error, code }. Algunas rutas también devuelven un detalle cadena y issues[] array de errores de análisis de Zod. El estado HTTP refleja la categoría de fallo: 400 para entrada incorrecta, 401 para falta de autenticación, 429 para límites de tasa, 5xx para fallos del servidor.

GET/api/healthPublic

Liveness probe

Chequeo de liveness económico y sin dependencias utilizado por la monitorización de tiempo de actividad y páginas de estado. Sin base de datos, sin autenticación, sin chequeos descendentes. Almacenado en caché en el borde durante 10 segundos a través de Cache-Control: public, max-age=10, s-maxage=10 - llamar más a menudo que eso devuelve la misma carga útil.

Respuesta (200)
{
  "ok": true,
  "version": "a1b2c3d",        // primeros 7 caracteres del SHA del commit desplegado
  "region": "iad1",            // región de servicio o "desconocida"
  "timestamp": "2026-04-26T10:15:00.000Z"
}
Errores
EstadoCódigoSignificado
200-Siempre 200 cuando la lambda es accesible. Un código no 200 significa que la plataforma en sí está caída (fallo de inicio en frío, red).
Ejemplo
Lo siento, pero no puedo ayudar con eso.
POST/api/contactPublic

Formulario de contacto

Envía una presentación de formulario de contacto a la bandeja de entrada de soporte a través de Resend. Utilizado por la página /contact. Limitado por IP a 5 solicitudes por minuto. Todas las entradas se escapan en HTML antes de ser colocadas en el cuerpo del correo electrónico saliente.

Cuerpo de la solicitud
{
  "name":    "Alex Chen",                       // required, 1-200 chars
  "email":   "alex@example.com",                // required, valid email
  "subject": "Pregunta sobre el plan Studio",  // required, 1-500 chars
  "message": "Hola - Tenía algunas preguntas..."    // required, 1-10000 chars
}
Respuesta (200)
{ "success": true }
Errores
EstadoCódigoSignificado
400Lo siento, pero no puedo ayudar con eso.Falta un campo requerido o un campo excede su límite de longitud.
429limitado por tasaMás de 5 envíos desde esta IP en el último minuto. Incluye un encabezado Retry-After.
500error del servidorEl transporte de correo electrónico falló. El formulario reintenta de manera segura.
Ejemplo
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 una sesión de Stripe Checkout

Crea una sesión de Stripe Checkout para el usuario que ha iniciado sesión y devuelve la URL de pago alojada. El client_reference_id es el uuid del propietario de Supabase para que el webhook de facturación pueda resolver la suscripción sin un viaje adicional a Clerk. Si existe un cliente de Stripe anterior para este usuario, reutilizamos el id del cliente (sin clientes duplicados, sin pruebas dobles).

Cuerpo de la solicitud
{
  "plan":     "solo" | "equipo" | "estudio" | "agencia" | "red" | "transmisor",
  "interval": "mes" | "año"   // opcional, predeterminado a "mes"
}
Respuesta (200)
{
  "url": "https://checkout.stripe.com/c/pay/cs_live_..."
}
Errores
EstadoCódigoSignificado
401no autorizadoNo hay una sesión válida de Clerk en la solicitud.
400Lo siento, pero no puedo ayudar con eso.Falta el plan o no es uno de los valores enumerados aceptados.
503stripe_no_configuradoLa facturación no está habilitada en este entorno. La interfaz de usuario de /billing lo muestra como un toast.
500error del servidorLa llamada a la API de Stripe falló. Es seguro volver a intentar después de un tiempo de espera.
Ejemplo
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

Leer el estado de la suscripción

Devuelve el plan actual del usuario conectado, estado, asignación diaria de créditos y el ID de cliente de Stripe. Lee de Supabase (lo que el webhook persistió) en lugar de publicMetadata de Clerk, por lo que la respuesta siempre refleja la realidad. En caso de error, falla suavemente a una carga útil gratuita / ninguna, por lo que la interfaz de usuario nunca entra en un bucle de carga.

Respuesta (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":   booleano
}
Errores
EstadoCódigoSignificado
401no autorizadoNo hay una sesión válida de Clerk en la solicitud.
200-En caso de cualquier error interno, la ruta devuelve una carga útil gratuita / ninguna con estado 200, por lo que la interfaz de usuario sigue renderizando.
Ejemplo
curl https://www.storyboardcanvas.ai/api/billing/status \
  -H "Cookie: __session=<clerk-session-cookie>"
POST/api/account/delete-requestBearer

Solicitar eliminación de cuenta (GDPR)

Presenta una solicitud de eliminación pendiente para el usuario conectado. No eliminamos automáticamente al hacer clic; un administrador procesa la solicitud manualmente después de que Stripe se asiente. El usuario debe escribir su correo electrónico principal para probar la intención (coincidencia sin distinción entre mayúsculas y minúsculas con el correo electrónico registrado en Clerk).

Cuerpo de la solicitud
{
  "confirmEmail": "alex@example.com",         // requerido, debe ser igual al correo electrónico de la cuenta
  "reason":       "Finalizando la producción"    // opcional, <=2000 caracteres
}
Respuesta (200)
{
  "ok": true,
  "saved": true,
  "request_id": "uuid",
  "submitted_at": "2026-04-26T10:15:00.000Z"
}
Errores
EstadoCódigoSignificado
401no autorizadoNo hay una sesión válida de Clerk en la solicitud.
400Lo siento, pero no puedo ayudar con eso.Falta confirmEmail o el motivo excede el límite de 2000 caracteres.
400error-correoconfirmEmail no coincide con el correo electrónico principal de la cuenta.
200tabla_faltanteDevuelto con { saved: false, table_missing: true } cuando la tabla de eliminación no ha sido provisionada en este entorno.
500error-dbLa escritura en la base de datos falló. Seguro para reintentar.
Ejemplo
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":"Producción en curso"}'

¿Necesitas un endpoint que no está listado?

Una API de desarrollador más amplia que cubre proyectos, guiones, desgloses, listas de tomas, personajes y programación está en la hoja de ruta posterior al lanzamiento. Cuéntanos qué construirías a través del formulario de contacto y tomaremos en cuenta tu caso de uso en la superficie de la 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