API 참조

StoryboardCanvas API

현재 프로덕션에서 제공되는 공개 및 로그인된 HTTP 엔드포인트에 대한 참조입니다. 여섯 개의 엔드포인트, 정확한 요청 및 응답 형식, 오류 코드, 복사하여 붙여넣기 가능한 curl 예제. 프로젝트, 스크립트 및 분석을 위한 더 넓은 개발자 API가 로드맵에 있습니다.

규칙

기본 URL

아래의 모든 엔드포인트는 https://www.storyboardcanvas.ai에서 제공됩니다. 별도의 api. 서브도메인 - 모든 것이 동일한 Next.js 앱 아래에 있습니다.

인증

공용 엔드포인트는 익명 요청을 수락합니다. 표시된 엔드포인트 Bearer 는 로그인된 Clerk 세션을 요구합니다 - 대부분의 클라이언트는 로그인 흐름에 의해 설정된 세션 쿠키로 이를 보유합니다. 현재 별도의 API 키 계층은 없으며, 더 넓은 프로그래밍적 접근은 로드맵.

콘텐츠 유형

모든 POST 엔드포인트는 수락합니다. application/json. 응답은 명시적으로 언급되지 않는 한 항상 JSON 형식입니다 (헬스 프로브도 JSON을 반환합니다).

오류

오류는 최소한 { error, code }를 포함하는 JSON 본문을 반환합니다. 일부 경로는 또한 detail 문자열을 반환합니다. 문제[] Zod 파싱 오류의 배열. HTTP 상태는 실패 범주를 반영합니다 - 잘못된 입력에 대해 400, 인증 누락에 대해 401, 비율 제한에 대해 429, 서버 오류에 대해 5xx.

엔드포인트

GET/api/healthPublic POST/api/contactPublic POST/api/billing/checkoutBearer GET/api/billing/statusBearer POST/api/account/delete-requestBearer

GET/api/healthPublic

Liveness probe

업타임 모니터링 및 상태 페이지에서 사용되는 저렴하고 의존성이 없는 생존 체크입니다. 데이터베이스, 인증, 하위 프로브가 없습니다. Cache-Control: public, max-age=10, s-maxage=10을 통해 엣지에서 10초 동안 캐시됩니다 - 그보다 더 자주 호출하면 동일한 페이로드가 반환됩니다.

Response (200)

{  
  "ok": true,  
  "version": "a1b2c3d",        // 배포된 커밋 SHA의 처음 7자  
  "region": "iad1",            // 서비스 지역 또는 "unknown"  
  "timestamp": "2026-04-26T10:15:00.000Z"  
}

오류

상태	코드	Meaning
200	-	람다가 접근 가능할 때 항상 200입니다. 비 200 응답은 플랫폼 자체가 다운되었음을 의미합니다 (콜드 스타트 실패, 네트워크 문제).

Example

curl https://www.storyboardcanvas.ai/api/health

POST/api/contactPublic

연락처 양식

Resend를 통해 지원 인박스로 연락처 양식 제출을 전송합니다. /contact 페이지에서 사용됩니다. IP당 요청 수는 분당 5회로 제한됩니다. 모든 입력은 발신 이메일 본문에 배치되기 전에 HTML로 이스케이프 처리됩니다.

요청 본문

{  
  "name":    "Alex Chen",                       // 필수, 1-200자  
  "email":   "alex@example.com",                // 필수, 유효한 이메일  
  "subject": "Studio 플랜에 대한 질문",         // 필수, 1-500자  
  "message": "안녕하세요 - 몇 가지 질문이 있습니다..." // 필수, 1-10000자  
}

Response (200)

{ "success": true }

오류

상태	코드	Meaning
400	잘못된 본문	필수 필드가 누락되었거나, 필드가 길이 제한을 초과했습니다.
429	요청 수 제한됨	이 IP에서 지난 1분 동안 5개 이상의 제출물이 있었습니다. Retry-After 헤더가 포함되어 있습니다.
500	서버 오류	이메일 전송에 실패했습니다. 양식이 안전하게 재시도됩니다.

Example

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

Stripe Checkout 세션 시작

로그인한 사용자에 대한 Stripe Checkout 세션을 생성하고 호스팅된 체크아웃 URL을 반환합니다. client_reference_id는 Supabase 소유자 uuid로, 청구 웹후크가 추가 Clerk 왕복 없이 구독을 정산할 수 있도록 합니다. 이 사용자에 대한 이전 Stripe 고객이 존재하는 경우 고객 ID를 재사용합니다(중복 고객 없음, 이중 체험 없음).

요청 본문

{
  "plan":     "solo" | "team" | "studio" | "agency" | "network" | "broadcaster",
  "interval": "month" | "year"   // 선택 사항, 기본값은 "month"
}

Response (200)

{
  "url": "https://checkout.stripe.com/c/pay/cs_live_..."
}

오류

상태	코드	Meaning
401	무단	요청에 유효한 Clerk 세션이 없습니다.
400	잘못된 본문	플랜이 누락되었거나 허용된 열거형 값 중 하나가 아닙니다.
503	stripe_not_configured	이 환경에서는 청구가 활성화되어 있지 않습니다. /billing UI는 이를 토스트로 표시합니다.
500	서버 오류	Stripe API 호출에 실패했습니다. 백오프 후에 재시도해도 안전합니다.

Example

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

구독 상태 읽기

현재 로그인한 사용자의 현재 요금제, 상태, 일일 크레딧 허용량 및 Stripe 고객 ID를 반환합니다. Clerk의 publicMetadata가 아닌 Supabase(웹훅이 유지한 데이터)에서 읽어오기 때문에 응답은 항상 현실을 반영합니다. 오류가 발생할 경우 UI가 스피너 루프에 빠지지 않도록 무료/없음 페이로드로 부드럽게 실패합니다.

Response (200)

{
  "plan":               "free" | "solo" | "team" | "studio" |
                        "agency" | "network" | "broadcaster",
  "status":             "active" | "trialing" | "past_due" |
                        "canceled" | "none",
  "credits_daily":      숫자,
  "current_period_end": "2026-05-26T00:00:00Z" | null,
  "stripe_customer_id": "cus_..." | null,
  "has_subscription":   불리언
}

오류

상태	코드	Meaning
401	무단	요청에 유효한 Clerk 세션이 없습니다.
200	-	내부 오류가 발생할 경우 경로는 상태 200으로 무료/없음 페이로드를 반환하여 UI가 계속 렌더링됩니다.

Example

curl https://www.storyboardcanvas.ai/api/billing/status \
  -H "Cookie: __session=<clerk-session-cookie>"

POST/api/account/delete-requestBearer

계정 삭제 요청 (GDPR)

로그인한 사용자의 삭제 요청을 보류 중으로 제출합니다. 클릭 시 자동 삭제되지 않으며, 관리자가 Stripe 정산 후 수동으로 요청을 처리합니다. 사용자는 의도를 증명하기 위해 기본 이메일을 다시 입력해야 합니다(Clerk의 기록 이메일과 대소문자 구분 없이 일치).

요청 본문

{
  "confirmEmail": "alex@example.com",         // 필수, 계정 이메일과 같아야 함
  "reason":       "제작 마무리 중"            // 선택 사항, <=2000자
}

Response (200)

{
  "ok": true,
  "saved": true,
  "request_id": "uuid",
  "submitted_at": "2026-04-26T10:15:00.000Z"
}

오류

상태	코드	Meaning
401	무단	요청에 유효한 Clerk 세션이 없습니다.
400	잘못된 본문	confirmEmail이 없거나 이유가 2000자 한도를 초과합니다.
400	이메일 불일치	confirmEmail이 계정의 기본 이메일과 일치하지 않습니다.
200	테이블 없음	이 환경에서 삭제 테이블이 프로비저닝되지 않았을 때 { saved: false, table_missing: true }로 반환되었습니다.
500	db 오류	데이터베이스 쓰기 실패. 다시 시도해도 안전합니다.

Example

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"}'

필요한 엔드포인트가 목록에 없으신가요?

프로젝트, 스크립트, 분해, 샷 리스트, 캐릭터 및 일정 관리를 포함하는 더 넓은 개발자 API가 출시 후 로드맵에 있습니다. 어떤 것을 구축할지 알려주세요. 연락처 양식을 통해 귀하의 사용 사례를 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