For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /ko/docs/web/api.md (or send Accept: text/markdown).
공개 API, 키, 웹훅
고객이 구축하는 버전 관리된 REST 표면.
시작하기 전에
파일 → 폴더 열기를 사용하여 Visual Studio Code에서 다운로드한 supastack 프로젝트를 연 다음 터미널 → 새 터미널을 선택합니다. 저장소 루트는 package.json, 앱 및 패키지가 포함된 폴더입니다. 아래 명령을 실행하고 터미널을 열어 두십시오. 명령이 인식되지 않으면 계속하기 전에 도구 설치 가이드를 완료하세요.
먼저 플랫폼 튜토리얼을 읽어보세요. 서버는 브라우저 또는 전화 요청에 응답하는 앱 프로세스입니다. 웹은 apps/web/.env.local를 읽고, Expo는 apps/mobile/.env.local를 읽고, 데이터베이스 마이그레이션 명령은 루트 .env를 읽습니다. 데이터베이스 없는 /dashboard 데모는 Postgres를 마이그레이션해야 하는 실제 /auth 계정과 별개입니다. 전화 또는 데스크톱 전용 결제에는 별도로 실행되는 웹 백엔드가 필요합니다.
corepack pnpm --filter @supastack/web dev설치 및 설정
packages/api가 버전 관리된 계약을 정의합니다: 모든 요청과 응답의 zod 스키마, 오류 엔벌로프, /api/v1/openapi에서 제공되고 /api/docs에서 렌더링되는 OpenAPI 문서. 워크스페이스 API 키는 설정 → 개발자에서 생성하고, 평문은 한 번만 표시된 후 해시된 키만 남습니다.
키는 프리픽스(sk_<env>_…), 스코프(기본 읽기)를 가지며 요청마다 워크스페이스로 해석됩니다. 아웃바운드 웹훅 구독은 같은 개발자 표면에서 관리합니다.
GET /api/v1/workspaces/current
GET /api/v1/entitlements
GET /api/v1/models/requirements
POST /api/v1/ai-tasks
GET /api/v1/openapi # machine-readable spec
GET /api/docs # rendered reference
Authorization: Bearer sk_live_…구현 워크플로
Bearer 키로 인증하고, 서버는 클라이언트 제공 id가 아닌 키에서 워크스페이스를 해석합니다. 응답 형태는 버전 관리를 유지하세요 — v1 내 추가적 변경, 브레이킹 변경은 새 버전 뒤에.
아웃바운드 웹훅은 엔드포인트 URL을 이벤트 카탈로그에 구독하고, 전달은 서명·기록되어 소비자가 검증하고 재생할 수 있습니다. 카탈로그는 webhook-events.ts, 시도는 webhook-delivery.ts를 사용합니다.
검증 및 문제 해결
폐기된 키가 401을 반환하는지, 스코프가 부족한 키가 거부되는지, OpenAPI 문서가 파싱되는지 확인합니다. 웹훅은 서명 검증, 실패 후 재전달, 이벤트 페이로드에 프로바이더 시크릿이 없는지를 테스트하세요.