{ "openapi": "3.1.0", "info": { "title": "APPSTAGE Developer API", "version": "1.3.0", "description": "기존 /api/v1 공개·개발자 API와 호환되는 APPSTAGE v5.4 명세입니다. 간편 AI 연결, 실제 이메일 인증, 격리된 HTML 개발자 글과 허용 목록 기반 APPSTAGE Bridge를 제공합니다." }, "servers": [ { "url": "http://127.0.0.1:8787", "description": "Wrangler local Worker" } ], "tags": [ { "name": "Public" }, { "name": "Account" }, { "name": "Workspace" }, { "name": "Developer registration" }, { "name": "Sandbox keys" }, { "name": "Draft API" }, { "name": "Admin boundary" } ], "components": { "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "__Host-appstage_session", "description": "운영 세션 쿠키. 로컬 HTTP에서는 appstage_session_local을 사용합니다." }, "csrfToken": { "type": "apiKey", "in": "header", "name": "X-CSRF-Token", "description": "상태 변경 세션 요청에 필요한 메모리 전용 CSRF 토큰" }, "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "appstage_test__", "description": "원문은 발급 순간 한 번만 표시되고 D1에는 SHA-256 해시만 저장됩니다." } }, "schemas": { "Slug": { "type": "string", "minLength": 3, "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "User": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "email_verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "enum": [ "active", "suspended", "blocked", "deleted" ] } } }, "Session": { "type": "object", "properties": { "authenticated": { "type": "boolean" }, "csrf_token": { "type": [ "string", "null" ], "writeOnly": true }, "user": { "anyOf": [ { "$ref": "#/components/schemas/User" }, { "type": "null" } ] }, "developer": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperRegistration" }, { "type": "null" } ] } } }, "DeveloperRegistration": { "type": "object", "properties": { "id": { "type": "string" }, "developer_id": { "type": [ "string", "null" ] }, "developer_name": { "type": "string" }, "slug": { "$ref": "#/components/schemas/Slug" }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "suspended" ] }, "decision": { "type": "string", "enum": [ "pending", "approved", "rejected", "manual_review_required" ] }, "manual_review_required": { "type": "boolean" }, "manual_review_reason": { "type": [ "string", "null" ] }, "live_access_status": { "type": "string", "enum": [ "not_requested", "pending", "approved", "rejected" ] }, "first_app_review_status": { "type": "string", "enum": [ "not_submitted", "pending", "approved", "rejected" ] } } }, "SandboxKey": { "type": "object", "properties": { "key_id": { "type": "string" }, "key_prefix": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "environment": { "type": "string", "const": "test" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "draft:write" ] } }, "status": { "type": "string", "enum": [ "active", "revoked", "expired" ] }, "rate_limit_per_minute": { "type": "integer", "const": 60 }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "value": { "type": "string", "writeOnly": true, "description": "발급 또는 회전 응답에서 한 번만 반환" }, "one_time_display": { "type": "boolean" } } }, "Developer": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "$ref": "#/components/schemas/Slug" }, "display_name": { "type": "string" }, "bio": { "type": "string" }, "website_url": { "type": [ "string", "null" ], "format": "uri" }, "image_url": { "type": [ "string", "null" ], "format": "uri" }, "apps": { "type": "array", "items": { "$ref": "#/components/schemas/App" } }, "posts": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } } } }, "App": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "$ref": "#/components/schemas/Slug" }, "name": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string" } }, "demo_url": { "type": [ "string", "null" ], "format": "uri" }, "image_url": { "type": [ "string", "null" ], "format": "uri" }, "status": { "type": "string", "enum": [ "draft", "published", "archived" ] }, "review_status": { "type": "string" }, "developer": { "type": "object" } } }, "Post": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "$ref": "#/components/schemas/Slug" }, "title": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "string" }, "content_type": { "type": "string", "enum": [ "markdown", "html" ] }, "body_html": { "type": [ "string", "null" ] }, "bridge_actions": { "type": "array", "items": { "type": "object", "required": [ "action", "target" ], "properties": { "action": { "type": "string", "enum": [ "open-screen", "run-effect", "set-theme", "set-orientation", "reset" ] }, "target": { "type": "string" } } } }, "status": { "type": "string", "enum": [ "draft", "published", "archived" ] }, "headings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" } } } } } }, "PaginationMeta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" } } }, "SignupInput": { "type": "object", "additionalProperties": false, "required": [ "email", "password", "terms_accepted", "privacy_accepted", "terms_version", "privacy_version" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 12, "writeOnly": true }, "terms_accepted": { "type": "boolean", "const": true }, "privacy_accepted": { "type": "boolean", "const": true }, "terms_version": { "type": "string" }, "privacy_version": { "type": "string" } } }, "LoginInput": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "writeOnly": true } } }, "TokenInput": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string", "minLength": 32, "writeOnly": true } } }, "EmailInput": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } }, "ResetCompleteInput": { "type": "object", "required": [ "token", "password" ], "properties": { "token": { "type": "string", "writeOnly": true }, "password": { "type": "string", "minLength": 12, "writeOnly": true } } }, "DeveloperRegistrationInput": { "type": "object", "additionalProperties": false, "required": [ "developer_name", "slug", "account_type", "contact", "country", "use_purpose", "first_app_name", "first_app_slug", "first_app_summary", "first_app_category", "first_app_platforms", "expected_calls_per_month", "policy_version", "policy_accepted" ], "properties": { "developer_name": { "type": "string", "minLength": 2 }, "slug": { "$ref": "#/components/schemas/Slug" }, "account_type": { "type": "string", "enum": [ "individual", "business" ] }, "contact": { "type": "string" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" }, "use_purpose": { "type": "string", "minLength": 20 }, "first_app_name": { "type": "string" }, "first_app_slug": { "$ref": "#/components/schemas/Slug" }, "first_app_summary": { "type": "string", "minLength": 20 }, "first_app_category": { "$ref": "#/components/schemas/Slug" }, "first_app_platforms": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "ios", "android", "web", "watch", "tablet", "desktop" ] } }, "expected_calls_per_month": { "type": "integer", "minimum": 1 }, "policy_version": { "type": "string", "const": "2026-07-28" }, "policy_accepted": { "type": "boolean", "const": true } } }, "AppInput": { "type": "object", "required": [ "slug", "name", "summary", "category", "platforms" ], "properties": { "slug": { "$ref": "#/components/schemas/Slug" }, "name": { "type": "string" }, "summary": { "type": "string", "minLength": 10 }, "description": { "type": "string" }, "category": { "type": "string" }, "platforms": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "image_url": { "type": [ "string", "null" ], "format": "uri" }, "demo_url": { "type": [ "string", "null" ], "format": "uri" } } }, "PostInput": { "type": "object", "required": [ "slug", "title", "body" ], "properties": { "slug": { "$ref": "#/components/schemas/Slug" }, "title": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "string", "description": "검색과 접근성을 위한 일반 텍스트 대체 본문" }, "content_type": { "type": "string", "enum": [ "markdown", "html" ], "default": "markdown" }, "body_html": { "type": "string", "maxLength": 200000 }, "bridge_actions": { "type": "array", "maxItems": 24, "items": { "type": "object", "required": [ "action", "target" ], "properties": { "action": { "type": "string", "enum": [ "open-screen", "run-effect", "set-theme", "set-orientation", "reset" ] }, "target": { "type": "string", "pattern": "^[a-z0-9-]+$" } } } }, "headings": { "type": "array", "items": { "type": "object" } } } }, "ReviewInput": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "approved", "rejected", "suspended" ] }, "reason": { "type": [ "string", "null" ] } } } }, "responses": { "BadRequest": { "description": "입력 오류", "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "type": "null" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "Unauthorized": { "description": "인증 실패, 만료·폐기 키 또는 세션", "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "type": "null" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "Forbidden": { "description": "권한·CSRF·Origin 또는 소유권 부족", "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "type": "null" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "NotFound": { "description": "리소스 없음", "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "type": "null" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "Conflict": { "description": "중복·재사용·상태 충돌", "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "type": "null" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "PayloadTooLarge": { "description": "1MiB 본문 제한 초과", "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "type": "null" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "RateLimited": { "description": "요청 한도 초과", "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "type": "null" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } }, "paths": { "/api/v1/health": { "get": { "tags": [ "Public" ], "summary": "상태 확인", "responses": { "200": { "description": "정상", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "1.3" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "type": "object" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "x-status": 200 } } } }, "/api/v1/apps": { "get": { "tags": [ "Public" ], "summary": "공개 앱 목록", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "category", "in": "query", "schema": { "type": "string" } }, { "name": "platform", "in": "query", "schema": { "type": "string" } }, { "name": "developer", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "앱 목록", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "1.3" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/App" } }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "x-status": 200 } } }, "post": { "tags": [ "Draft API" ], "summary": "본인 앱 draft 생성", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppInput" } } } }, "responses": { "201": { "description": "생성", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "1.3" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "$ref": "#/components/schemas/App" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "x-status": 200 }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/apps/{slug}": { "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Slug" } } ], "get": { "tags": [ "Public" ], "summary": "공개 앱 상세", "responses": { "200": { "description": "앱", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "1.3" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "$ref": "#/components/schemas/App" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "x-status": 200 }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Draft API" ], "summary": "본인 앱 수정", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "수정", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "1.3" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "$ref": "#/components/schemas/App" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "x-status": 200 }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/developers/{slug}": { "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Slug" } } ], "get": { "tags": [ "Public" ], "summary": "개발자 공개 프로필", "responses": { "200": { "description": "개발자", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "1.3" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "$ref": "#/components/schemas/Developer" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "x-status": 200 }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/apps/{slug}/posts": { "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Slug" } } ], "get": { "tags": [ "Public" ], "summary": "공개 글 목록", "responses": { "200": { "description": "글", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "1.3" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "type": "object", "properties": { "app": { "type": "object" }, "posts": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } } } }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "x-status": 200 }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "Draft API" ], "summary": "본인 앱 draft 글 생성", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostInput" } } } }, "responses": { "201": { "description": "초안 글", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "1.3" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "$ref": "#/components/schemas/Post" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "x-status": 200 }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/apps/{slug}/publish": { "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Slug" } } ], "post": { "tags": [ "Draft API" ], "summary": "앱 공개", "description": "Sandbox 키에는 publish scope가 없으므로 403입니다. 첫 앱 관리자 검토 후 별도 live 권한 경계를 통해서만 허용됩니다.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "공개", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "1.3" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "$ref": "#/components/schemas/App" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "x-status": 200 }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/auth/signup": { "post": { "tags": [ "Account" ], "summary": "회원가입", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupInput" } } } }, "responses": { "201": { "description": "가입 및 인증 안내 처리", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "1.3" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "type": "object" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "x-status": 200 }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/auth/email-verification/request": { "post": { "tags": [ "Account" ], "summary": "이메일 인증 재요청", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailInput" } } } }, "responses": { "202": { "description": "열거 방지 수락", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "1.3" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "type": "object" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "x-status": 200 }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v1/auth/email-verification/complete": { "post": { "tags": [ "Account" ], "summary": "이메일 인증 완료와 세션 생성", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenInput" } } } }, "responses": { "200": { "description": "인증됨", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "1.3" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "$ref": "#/components/schemas/Session" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "x-status": 200 }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/auth/login": { "post": { "tags": [ "Account" ], "summary": "로그인", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginInput" } } } }, "responses": { "200": { "description": "로그인됨", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "1.3" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "$ref": "#/components/schemas/Session" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "x-status": 200 }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/auth/logout": { "post": { "tags": [ "Account" ], "summary": "로그아웃", "security": [ { "sessionCookie": [], "csrfToken": [] } ], "responses": { "200": { "description": "로그아웃됨", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "1.3" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "type": "object" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "x-status": 200 }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/auth/session/me": { "get": { "tags": [ "Account" ], "summary": "현재 세션·개발자 상태", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "세션", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "1.3" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "$ref": "#/components/schemas/Session" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "x-status": 200 } } } }, "/api/v1/auth/password-reset/request": { "post": { "tags": [ "Account" ], "summary": "비밀번호 재설정 요청", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailInput" } } } }, "responses": { "202": { "description": "열거 방지 수락", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "1.3" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "type": "object" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "x-status": 200 } } } }, "/api/v1/auth/password-reset/complete": { "post": { "tags": [ "Account" ], "summary": "비밀번호 재설정 완료", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetCompleteInput" } } } }, "responses": { "200": { "description": "재설정 및 기존 세션 폐기", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "1.3" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "type": "object" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "x-status": 200 }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/workspace": { "get": { "tags": [ "Workspace" ], "summary": "내 개인 작업공간의 앱·글·공개 주소", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "개인 작업공간", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "1.3" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "type": "object", "properties": { "developer": { "anyOf": [ { "$ref": "#/components/schemas/Developer" }, { "type": "null" } ] }, "apps": { "type": "array", "items": { "$ref": "#/components/schemas/App" } }, "posts": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } }, "counts": { "type": "object" } } }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "x-status": 200 }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/workspace/profile": { "patch": { "tags": [ "Workspace" ], "summary": "내 공개 개발자 프로필 수정", "security": [ { "sessionCookie": [], "csrfToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "display_name": { "type": "string", "minLength": 2, "maxLength": 80 }, "bio": { "type": "string", "maxLength": 1000 }, "website_url": { "type": [ "string", "null" ], "format": "uri" }, "image_url": { "type": [ "string", "null" ], "format": "uri" } } } } } }, "responses": { "200": { "description": "수정된 공개 프로필", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "1.3" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "$ref": "#/components/schemas/Developer" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "x-status": 200 }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/developer/registration": { "get": { "tags": [ "Developer registration" ], "summary": "내 개발자 신청 상태", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "신청 상태", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "1.3" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "type": "object" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "x-status": 200 }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "Developer registration" ], "summary": "개발자 등록·정책 판정·초기 Sandbox 키 1회 발급", "description": "인증 이메일과 CSRF/Origin이 필요합니다. 민감·규제·대량 수집·고트래픽은 manual_review_required로 전환되고 키를 자동 발급하지 않습니다. Idempotency-Key를 지원합니다.", "security": [ { "sessionCookie": [], "csrfToken": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperRegistrationInput" } } } }, "responses": { "201": { "description": "자동 승인", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "1.3" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "type": "object" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "x-status": 200 }, "202": { "description": "수동 검토 대기", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "1.3" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "type": "object" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "x-status": 200 }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/developer/quick-connect": { "post": { "tags": [ "Developer registration" ], "summary": "개인 개발자 공간과 첫 Sandbox 키 간편 생성", "description": "이메일 인증 계정에 개인·대한민국·일반 앱 기본값을 적용합니다. 앱 초안은 만들지 않고 AI 연결 키만 한 번 표시합니다.", "security": [ { "sessionCookie": [], "csrfToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "developer_name", "slug", "policy_accepted" ], "properties": { "developer_name": { "type": "string", "minLength": 2, "maxLength": 120 }, "slug": { "$ref": "#/components/schemas/Slug" }, "policy_accepted": { "type": "boolean", "const": true } } } } } }, "responses": { "201": { "description": "개인 공간과 1회 표시 키", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "1.3" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "type": "object" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "x-status": 200 }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/developer/keys": { "get": { "tags": [ "Sandbox keys" ], "summary": "내 Sandbox 키 메타데이터 목록", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "키 목록", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "1.3" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/SandboxKey" } } } }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "x-status": 200 }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "Sandbox keys" ], "summary": "Sandbox 키 추가 발급", "security": [ { "sessionCookie": [], "csrfToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "display_name": { "type": "string", "maxLength": 80 } } } } } }, "responses": { "201": { "description": "한 번만 표시되는 키", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "1.3" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/SandboxKey" } } }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "x-status": 200 }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/developer/keys/{keyId}/rotate": { "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Sandbox keys" ], "summary": "새 키 생성 후 기존 키 원자적 폐기", "security": [ { "sessionCookie": [], "csrfToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "display_name": { "type": "string" } } } } } }, "responses": { "201": { "description": "교체 키 1회 표시", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "1.3" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "type": "object" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "x-status": 200 }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/developer/keys/{keyId}/revoke": { "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Sandbox keys" ], "summary": "Sandbox 키 폐기", "security": [ { "sessionCookie": [], "csrfToken": [] } ], "responses": { "200": { "description": "폐기됨", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "1.3" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "type": "object" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "x-status": 200 }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/admin/developer-applications/{applicationId}/review": { "parameters": [ { "name": "applicationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Admin boundary" ], "summary": "관리자 개발자 신청 검토 경계", "description": "admin scope의 외부 관리자 인증 구성이 배포 차단 조건입니다. 이 패키지는 관리자 비밀값이나 live 키를 생성하지 않습니다.", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewInput" } } } }, "responses": { "200": { "description": "상태 변경", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "1.3" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "type": "object" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "x-status": 200 }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/admin/apps/{slug}/review": { "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Slug" } } ], "post": { "tags": [ "Admin boundary" ], "summary": "첫 앱 검토와 live 접근 상태 경계", "description": "승인은 상태만 변경하며 live 키는 발급하지 않습니다.", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewInput" } } } }, "responses": { "200": { "description": "검토 상태", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "1.3" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "data", "error" ], "properties": { "request_id": { "type": "string" }, "data": { "type": "object" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "x-status": 200 }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } } }