API-Referenz

StoryboardCanvas API

Referenz für die öffentlichen und angemeldeten HTTP-Endpunkte, die derzeit in der Produktion bereitgestellt werden. Sechs Endpunkte, genaue Anforderungs- und Antwortformate, Fehlercodes und Copy-Paste-curl-Beispiele. Eine umfassendere Entwickler-API für Projekte, Skripte und Aufschlüsselungen steht auf der Roadmap.

Konventionen

Basis-URL

Alle unten aufgeführten Endpunkte werden bereitgestellt von https://www.storyboardcanvas.ai. Es gibt keine separate api. Subdomain - alles lebt unter derselben Next.js-App.

Authentifizierung

Öffentliche Endpunkte akzeptieren anonyme Anfragen. Endpunkte, die markiert sind Bearer erfordern eine angemeldete Clerk-Sitzung - die meisten Clients tragen sie als Sitzungscookie, das durch den Anmeldefluss gesetzt wird. Es gibt heute keine separate API-Schlüsselstufe; breiterer programmgesteuerter Zugriff ist auf dem fahrplan.

Inhaltstyp

Alle POST-Endpunkte akzeptieren application/json. Antworten sind immer im JSON-Format, es sei denn, es wird ausdrücklich anders angegeben (der Gesundheitscheck gibt ebenfalls JSON zurück).

Fehler

Fehler geben einen JSON-Body mit mindestens { error, code }zurück. Einige Routen geben auch eine detail Zeichenkette zurück und issues[] Array von Zod-Parse-Fehlern. Der HTTP-Status spiegelt die Fehlerkategorie wider - 400 für ungültige Eingaben, 401 für fehlende Authentifizierung, 429 für Ratenlimits, 5xx für Serverfehler.

GET/api/healthPublic

Liveness-Probe

Günstige, abhängigkeitfreie Liveness-Prüfung, die von Uptime-Überwachungen und Statusseiten verwendet wird. Keine DB, keine Authentifizierung, keine nachgelagerten Prüfungen. An der Edge für 10 Sekunden zwischengespeichert über Cache-Control: public, max-age=10, s-maxage=10 - häufigere Aufrufe liefern dasselbe Payload.

Antwort (200)
{  
  "ok": true,  
  "version": "a1b2c3d",        // erste 7 Zeichen des bereitgestellten Commit-SHA  
  "region": "iad1",            // bediente Region oder "unbekannt"  
  "timestamp": "2026-04-26T10:15:00.000Z"  
}
Fehler
StatusCodeBedeutung
200-Immer 200, wenn die Lambda erreichbar ist. Ein Nicht-200 bedeutet, dass die Plattform selbst ausgefallen ist (Cold-Start-Fehler, Netzwerk).
Beispiel
curl https://www.storyboardcanvas.ai/api/health
POST/api/contactPublic

Kontaktformular

Sendet eine Kontaktformularübermittlung an das Support-Postfach über Resend. Wird von der /contact-Seite verwendet. Pro IP auf 5 Anfragen pro Minute begrenzt. Alle Eingaben werden vor dem Einfügen in den ausgehenden E-Mail-Text HTML-escaped.

Anforderungsinhalt
{
  "name":    "Alex Chen",                       // erforderlich, 1-200 Zeichen
  "email":   "alex@example.com",                // erforderlich, gültige E-Mail
  "subject": "Frage zum Studio-Plan",           // erforderlich, 1-500 Zeichen
  "message": "Hallo - ich hatte ein paar Fragen..." // erforderlich, 1-10000 Zeichen
}
Antwort (200)
{ "success": true }
Fehler
StatusCodeBedeutung
400ungültiger-InhaltEin erforderliches Feld fehlt oder ein Feld überschreitet seine Längenbeschränkung.
429rate-limitiertMehr als 5 Einsendungen von dieser IP in der letzten Minute. Enthält einen Retry-After-Header.
500server-errorE-Mail-Transport fehlgeschlagen. Das Formular wird sicher erneut gesendet.
Beispiel
curl -X POST https://www.storyboardcanvas.ai/api/contact \
  -H "Content-Type: application/json" \
  -d '{"name":"Alex","email":"alex@example.com","subject":"Hallo","message":"Hallo zusammen"}'
POST/api/billing/checkoutBearer

Starten Sie eine Stripe Checkout-Sitzung

Erstellt eine Stripe Checkout-Sitzung für den angemeldeten Benutzer und gibt die gehostete Checkout-URL zurück. Die client_reference_id ist die Supabase-Besitzer-UUID, sodass der Abrechnungs-Webhook das Abonnement ohne eine zusätzliche Clerk-Rundreise abwickeln kann. Wenn ein vorheriger Stripe-Kunde für diesen Benutzer existiert, verwenden wir die Kunden-ID erneut (keine doppelten Kunden, keine doppelten Testversionen).

Anforderungsinhalt
{
  "plan":     "solo" | "team" | "studio" | "agentur" | "netzwerk" | "sender",
  "interval": "monat" | "jahr"   // optional, standardmäßig "monat"
}
Antwort (200)
{
  "url": "https://checkout.stripe.com/c/pay/cs_live_..."
}
Fehler
StatusCodeBedeutung
401unauthorizedKeine gültige Clerk-Sitzung in der Anfrage.
400ungültiger-InhaltPlan fehlt oder ist nicht einer der akzeptierten Enum-Werte.
503stripe_not_configuredAbrechnung ist in dieser Umgebung nicht aktiviert. Die /billing UI zeigt dies als Toast an.
500server-errorStripe API-Aufruf fehlgeschlagen. Sicher, nach einer Wartezeit erneut zu versuchen.
Beispiel
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

Abonnementstatus lesen

Gibt den aktuellen Plan, Status, das tägliche Kreditlimit und die Stripe-Kunden-ID des angemeldeten Benutzers zurück. Liest von Supabase (was der Webhook gespeichert hat) anstelle von Clerk publicMetadata, sodass die Antwort immer die Realität widerspiegelt. Bei einem Fehler wird sanft auf ein kostenloses / kein Payload zurückgegriffen, sodass die Benutzeroberfläche niemals in einer Lade-Schleife bleibt.

Antwort (200)
{
  "plan":               "free" | "solo" | "team" | "studio" |
                        "agency" | "network" | "broadcaster",
  "status":             "active" | "trialing" | "past_due" |
                        "canceled" | "none",
  "credits_daily":      number,
  "current_period_end": "2026-05-26T00:00:00Z" | null,
  "stripe_customer_id": "cus_..." | null,
  "has_subscription":   boolean
}
Fehler
StatusCodeBedeutung
401unauthorizedKeine gültige Clerk-Sitzung in der Anfrage.
200-Bei einem internen Fehler gibt die Route ein kostenloses / kein Payload mit dem Status 200 zurück, sodass die Benutzeroberfläche weiterhin gerendert wird.
Beispiel
curl https://www.storyboardcanvas.ai/api/billing/status \
  -H "Cookie: __session=<clerk-session-cookie>"
POST/api/account/delete-requestBearer

Antrag auf Kontolöschung (DSGVO)

Reicht einen ausstehenden Löschantrag für den angemeldeten Benutzer ein. Wir löschen nicht automatisch mit einem Klick - ein Administrator bearbeitet die Anfrage manuell, nachdem Stripe die Zahlung abgeschlossen hat. Der Benutzer muss seine primäre E-Mail-Adresse eingeben, um die Absicht zu beweisen (nicht groß-/kleinschreibungsempfindlicher Abgleich mit der E-Mail von Clerk).

Anforderungsinhalt
{
  "confirmEmail": "alex@example.com",         // erforderlich, muss mit der Kontoe-Mail übereinstimmen
  "reason":       "Produktion abschließen"    // optional, <=2000 Zeichen
}
Antwort (200)
{
  "ok": true,
  "saved": true,
  "request_id": "uuid",
  "submitted_at": "2026-04-26T10:15:00.000Z"
}
Fehler
StatusCodeBedeutung
401unauthorizedKeine gültige Clerk-Sitzung in der Anfrage.
400ungültiger-InhaltFehlende confirmEmail oder Grund überschreitet das 2000-Zeichen-Limit.
400E-Mail stimmt nicht übereinconfirmEmail stimmt nicht mit der primären E-Mail des Kontos überein.
200tabelle_fehltZurückgegeben mit { saved: false, table_missing: true }, wenn die Lösch-Tabelle in dieser Umgebung nicht bereitgestellt wurde.
500db-fehlerDatenbankschreibung fehlgeschlagen. Sicher, es erneut zu versuchen.
Beispiel
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":"Wrapping production"}'

Benötigen Sie einen Endpunkt, der nicht aufgeführt ist?

Eine umfassendere Entwickler-API, die Projekte, Skripte, Aufschlüsselungen, Shot-Listen, Charaktere und Zeitpläne abdeckt, steht auf der Roadmap nach dem Launch. Lassen Sie uns wissen, was Sie erstellen würden über das Kontaktformular und wir werden Ihren Anwendungsfall in die v1-Oberfläche einfließen lassen.

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