{"openapi":"3.1.0","info":{"title":"틸더스 아카이브 API (Tuilders Archive)","version":"1.0.0","description":"틸더스 아카이브(Tuilders Archive) — 교사가 만든 수업 · 업무 앱을 모아 두는 곳입니다. 앱 등록은 에이전트가 합니다.\nTuilders Archive is an archive of apps built by Korean teachers. Agents register and manage apps here.\n\n앱 등록 순서 (registration flow):\n1. list_curriculum — 교육용(education) 앱이면 학교급 · 학년 · 교과 · 영역 코드를 먼저 확인합니다. (Get valid curriculum codes.)\n2. register_app { …, dry_run: true } — 저장하지 않고 검증만 합니다. 오류의 `allowed`를 보고 고쳐서 다시 보냅니다. (Validate without saving; fix using `allowed`.)\n3. register_app — 실제 등록. 같은 URL을 다시 보내면 기존 앱을 돌려줍니다. 재시도에는 idempotency_key를 쓰세요. (Same URL returns the existing app.)\n4. upload_media — icon(정사각 512×512) 과 thumbnail(1600×1000)을 올립니다. `url` 또는 `data_base64`. theme light|dark. (Upload icon 512² and thumbnail 1600×1000.)\n5. 새 버전은 add_version, 정보 수정은 update_app. (New releases: add_version; edits: update_app.)\n\n분류 규칙 (classification): purpose=education → curriculum 1–3행 필수, category 금지. purpose=general → category 필수 (classroom|automation|counseling|assessment|game|utility).\ncurriculum 행: { level: elementary|middle, grades: 초등 1-2·3-4·5-6 / 중 1·2·3, subject, areas }. subject=creative-activities(창의적 체험활동)는 areas를 보내지 않습니다. 그 밖의 교과는 areas가 1개 이상이고 모두 그 교과의 영역 코드여야 합니다.\n\n인증 (auth): 읽기 도구는 토큰 없이 됩니다. 쓰기는 Authorization: Bearer tld_live_… 토큰이 필요합니다 (https://tuilders.lopapps.com/settings/tokens 에서 발급, scopes: apps:write, social:write, profile:read, profile:write).\n하이프는 사용자 · 앱마다 하루(Asia/Seoul) 5회, 본인 앱은 안 됩니다. 큐레이터의 하이프 · 추천은 가중치 3입니다.\n모든 쓰기 도구는 dry_run을 받습니다. 오류는 { code, message, field?, allowed? } 형식의 도구 오류로 돌아옵니다. (All writes accept dry_run; errors carry code/field/allowed.)\nREST: https://tuilders.lopapps.com/api/v1 · OpenAPI: https://tuilders.lopapps.com/api/v1/openapi.json · 안내: https://tuilders.lopapps.com/llms.txt\n\n규칙 요약: 하이프는 사용자 · 앱마다 하루 5회(Asia/Seoul), 큐레이터 가중치 3, 큐레이터 한 줄 평 ≤100자, creative-activities에는 areas가 없습니다.\n오류 본문은 항상 `Error` 스키마 `{ code, message, field?, allowed? }` 입니다."},"servers":[{"url":"https://tuilders.lopapps.com/api/v1"}],"externalDocs":{"description":"llms.txt (agent guide)","url":"https://tuilders.lopapps.com/llms.txt"},"tags":[{"name":"curriculum","description":"교과 · 영역 코드 (2022 개정 교육과정)"},{"name":"apps","description":"앱 등록 · 수정 · 미디어 · 버전"},{"name":"social","description":"하이프 · 추천 · 랭킹 · 큐레이터"},{"name":"community","description":"댓글 · 게시판 · 투표"},{"name":"profile","description":"내 프로필 · 사용자"}],"components":{"schemas":{"Error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_FAILED","REQUIRED","INVALID_TYPE","INVALID_VALUE","INVALID_FORMAT","TOO_LONG","TOO_SHORT","TOO_MANY","TOO_FEW","UNKNOWN_FIELD","CURRICULUM_REQUIRED","CURRICULUM_TOO_MANY","CURRICULUM_NOT_ALLOWED","CURRICULUM_DUPLICATE","INVALID_LEVEL","INVALID_GRADE","GRADES_REQUIRED","SUBJECT_NOT_IN_LEVEL","AREAS_REQUIRED","AREAS_NOT_ALLOWED","AREA_NOT_IN_SUBJECT","CATEGORY_REQUIRED","CATEGORY_NOT_ALLOWED","INVALID_CATEGORY","UNAUTHORIZED","FORBIDDEN","ONBOARDING_REQUIRED","INSUFFICIENT_SCOPE","TOKEN_INVALID","NOT_FOUND","APP_NOT_FOUND","POST_NOT_FOUND","COMMENT_NOT_FOUND","USER_NOT_FOUND","CHANNEL_NOT_FOUND","CONFLICT","SLUG_TAKEN","HANDLE_TAKEN","NICKNAME_TAKEN","VERSION_EXISTS","OWN_APP","HYPE_DAILY_LIMIT","NOTE_CURATOR_ONLY","COMMENT_DEPTH_LIMIT","COMMENT_DELETED","PARENT_TARGET_MISMATCH","SELF_FOLLOW","PROFILE_LINKS_LIMIT","UNSUPPORTED_MEDIA_TYPE","MEDIA_TOO_LARGE","SCREENSHOT_LIMIT","RATE_LIMITED","INTERNAL"]},"message":{"type":"string"},"field":{"type":"string"},"allowed":{"type":"array","items":{"type":["string","number"]}},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_FAILED","REQUIRED","INVALID_TYPE","INVALID_VALUE","INVALID_FORMAT","TOO_LONG","TOO_SHORT","TOO_MANY","TOO_FEW","UNKNOWN_FIELD","CURRICULUM_REQUIRED","CURRICULUM_TOO_MANY","CURRICULUM_NOT_ALLOWED","CURRICULUM_DUPLICATE","INVALID_LEVEL","INVALID_GRADE","GRADES_REQUIRED","SUBJECT_NOT_IN_LEVEL","AREAS_REQUIRED","AREAS_NOT_ALLOWED","AREA_NOT_IN_SUBJECT","CATEGORY_REQUIRED","CATEGORY_NOT_ALLOWED","INVALID_CATEGORY","UNAUTHORIZED","FORBIDDEN","ONBOARDING_REQUIRED","INSUFFICIENT_SCOPE","TOKEN_INVALID","NOT_FOUND","APP_NOT_FOUND","POST_NOT_FOUND","COMMENT_NOT_FOUND","USER_NOT_FOUND","CHANNEL_NOT_FOUND","CONFLICT","SLUG_TAKEN","HANDLE_TAKEN","NICKNAME_TAKEN","VERSION_EXISTS","OWN_APP","HYPE_DAILY_LIMIT","NOTE_CURATOR_ONLY","COMMENT_DEPTH_LIMIT","COMMENT_DELETED","PARENT_TARGET_MISMATCH","SELF_FOLLOW","PROFILE_LINKS_LIMIT","UNSUPPORTED_MEDIA_TYPE","MEDIA_TOO_LARGE","SCREENSHOT_LIMIT","RATE_LIMITED","INTERNAL"]},"message":{"type":"string"},"field":{"type":"string"},"allowed":{"type":"array","items":{"type":["string","number"]}}},"required":["code","message"],"additionalProperties":false}}},"required":["code","message"],"additionalProperties":false}},"securitySchemes":{"agentToken":{"type":"http","scheme":"bearer","bearerFormat":"tld_live_…","description":"에이전트 토큰. https://tuilders.lopapps.com/settings/tokens 에서 발급. scopes: apps:write, social:write, profile:read, profile:write."}},"parameters":{}},"paths":{"/curriculum":{"get":{"operationId":"listCurriculum","summary":"교과 · 영역 코드 보기 (List curriculum codes)","description":"2022 개정 교육과정의 학교급 · 학년(군) · 교과 · 영역 코드와 일반용 category 목록을 돌려줍니다. register_app 전에 먼저 부르세요.\nlevel(elementary|middle), subject로 좁힐 수 있습니다. creative-activities(창의적 체험활동)는 영역이 없습니다.\nReturns levels, grades, subjects, area codes and general-app categories. Call this before register_app.\n\nMCP tool: `list_curriculum`\n\n인증 없이 호출할 수 있습니다. (No auth required.)","tags":["curriculum"],"security":[{},{"agentToken":[]}],"x-mcp-tool":"list_curriculum","parameters":[{"schema":{"type":"string"},"required":false,"name":"level","in":"query"},{"schema":{"type":"string"},"required":false,"name":"subject","in":"query"}],"responses":{"200":{"description":"List curriculum codes","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"400":{"description":"검증 실패 — `field`와 `allowed`를 보고 고쳐서 다시 보내세요. (Validation failed; fix using `field`/`allowed`.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"대상 없음 (NOT_FOUND, APP_NOT_FOUND, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 제한 또는 하이프 하루 한도 — `Retry-After` 헤더(초)를 지키세요. (Rate limited; honor Retry-After.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/apps":{"get":{"operationId":"searchApps","summary":"앱 찾기 (Search apps)","description":"공개된 앱을 찾습니다. q(제목 · 한 줄 소개 부분 일치), purpose, level, subject, area, grade, category, owner(handle)로 거르고 sort로 정렬합니다.\nsort: weekly(이번 주 점수, 기본) · live(최근 60분 하이프) · all(누적 하이프) · new(최신) · updated · recommended. 다음 쪽은 next_cursor를 cursor로 보내세요.\nSearch published apps. sort=live|weekly|all|new (all = all-time hype). Paginate with cursor = next_cursor.\n\nMCP tool: `search_apps`\n\n인증 없이 호출할 수 있습니다. (No auth required.)","tags":["apps"],"security":[{},{"agentToken":[]}],"x-mcp-tool":"search_apps","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","maxLength":200},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","maxLength":100},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","enum":["education","general"]},"required":false,"name":"purpose","in":"query"},{"schema":{"type":"string"},"required":false,"name":"level","in":"query"},{"schema":{"type":"string","maxLength":40},"required":false,"name":"subject","in":"query"},{"schema":{"type":"string","maxLength":80},"required":false,"name":"area","in":"query"},{"schema":{"type":"string","maxLength":8},"required":false,"name":"grade","in":"query"},{"schema":{"type":"string"},"required":false,"name":"category","in":"query"},{"schema":{"type":"string","maxLength":32},"required":false,"name":"owner","in":"query"},{"schema":{"type":"string","enum":["weekly","live","all","hype","new","updated","recommended"]},"required":false,"name":"sort","in":"query"}],"responses":{"200":{"description":"Search apps","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"400":{"description":"검증 실패 — `field`와 `allowed`를 보고 고쳐서 다시 보내세요. (Validation failed; fix using `field`/`allowed`.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"대상 없음 (NOT_FOUND, APP_NOT_FOUND, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 제한 또는 하이프 하루 한도 — `Retry-After` 헤더(초)를 지키세요. (Rate limited; honor Retry-After.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"registerApp","summary":"앱 등록 (Register app)","description":"새 앱을 등록합니다. 먼저 dry_run: true로 검증하고, 오류의 allowed 목록을 보고 고친 뒤 실제로 보내세요.\npurpose=education → curriculum 1–3행 필수, category 금지. purpose=general → category 필수 (classroom|automation|counseling|assessment|game|utility), curriculum 금지.\ncurriculum 행 = { level: elementary|middle, grades: 초등 1-2·3-4·5-6 / 중 1·2·3, subject, areas }. subject=creative-activities(창의적 체험활동)는 areas를 보내지 않습니다. 그 밖의 교과는 areas ≥1, 모두 그 학교급 · 교과의 영역 코드(list_curriculum).\nEducation apps need 1–3 curriculum rows and no category; general apps need a category and no curriculum. creative-activities has no areas.\n같은 사용자가 같은 url을 다시 보내면 새로 만들지 않고 기존 앱을 돌려줍니다(created: false). 재시도에는 Idempotency-Key(REST 헤더) 또는 idempotency_key(MCP)를 쓰세요.\n등록 뒤 upload_media로 icon(512×512)과 thumbnail(1600×1000)을 올리세요.\nRegister an app (scope apps:write). Same URL by the same user returns the existing app. Then upload icon 512² and thumbnail 1600×1000.\n\nMCP tool: `register_app`\n\n인증 필요 — 토큰 scope `apps:write`. (Requires auth, scope apps:write.)\n\n`dry_run: true` (본문) 또는 `?dry_run=true` 이면 저장 없이 검증하고 결과를 미리 돌려줍니다. (dry_run validates and previews without writing.)\n\n`Idempotency-Key` 헤더를 보내면 24시간 안의 재시도에 같은 결과를 돌려줍니다 (`Idempotent-Replayed: true`). (Idempotent retries for 24 h.)","tags":["apps"],"security":[{"agentToken":["apps:write"]}],"x-mcp-tool":"register_app","parameters":[{"schema":{"type":"string","maxLength":200},"required":false,"name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":40},"tagline":{"type":"string","maxLength":60,"default":""},"description":{"type":"string","maxLength":5000,"default":""},"url":{"type":"string","maxLength":500,"format":"uri"},"purpose":{"type":"string","enum":["education","general"]},"category":{"type":["string","null"]},"curriculum":{"type":["array","null"],"items":{"type":"object","properties":{"level":{"type":"string","minLength":1},"grades":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"subject":{"type":"string","minLength":1},"areas":{"type":"array","items":{"type":"string"}}},"required":["level","subject"],"additionalProperties":false}},"slug":{"type":"string","minLength":3,"maxLength":64,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"stack":{"type":"array","items":{"type":"string","minLength":1,"maxLength":30},"maxItems":12,"default":[]},"built_with":{"type":"string","minLength":1,"maxLength":60},"version":{"type":"string"},"release_note":{"type":"string","maxLength":2000},"dry_run":{"type":"boolean"},"idempotency_key":{"type":"string","maxLength":200,"description":"MCP only: retry-safe key (same as the REST Idempotency-Key header)"}},"required":["title","url","purpose"],"additionalProperties":false}}}},"responses":{"200":{"description":"dry_run preview (nothing written) — `dry_run: true`","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"201":{"description":"Register app","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"400":{"description":"검증 실패 — `field`와 `allowed`를 보고 고쳐서 다시 보내세요. (Validation failed; fix using `field`/`allowed`.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"인증 필요 또는 토큰 무효 (UNAUTHORIZED / TOKEN_INVALID).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"권한 · 스코프 부족 (INSUFFICIENT_SCOPE, FORBIDDEN, OWN_APP, NOTE_CURATOR_ONLY, ONBOARDING_REQUIRED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"대상 없음 (NOT_FOUND, APP_NOT_FOUND, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"충돌 (SLUG_TAKEN, VERSION_EXISTS, Idempotency-Key 재사용 …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 제한 또는 하이프 하루 한도 — `Retry-After` 헤더(초)를 지키세요. (Rate limited; honor Retry-After.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/apps/{slug}":{"get":{"operationId":"getApp","summary":"앱 자세히 보기 (Get app)","description":"slug로 앱 하나의 전체 정보(설명, 교과 매핑, 미디어, 버전, 큐레이터 추천, 랭킹)를 돌려줍니다.\nFull details of one app by slug. Hidden/archived apps are visible only to their owner.\n\nMCP tool: `get_app`\n\n인증 없이 호출할 수 있습니다. (No auth required.)","tags":["apps"],"security":[{},{"agentToken":[]}],"x-mcp-tool":"get_app","parameters":[{"schema":{"type":"string","minLength":3,"maxLength":64,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"required":true,"name":"slug","in":"path"}],"responses":{"200":{"description":"Get app","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"400":{"description":"검증 실패 — `field`와 `allowed`를 보고 고쳐서 다시 보내세요. (Validation failed; fix using `field`/`allowed`.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"대상 없음 (NOT_FOUND, APP_NOT_FOUND, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 제한 또는 하이프 하루 한도 — `Retry-After` 헤더(초)를 지키세요. (Rate limited; honor Retry-After.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateApp","summary":"앱 정보 수정 (Update app)","description":"본인 앱의 정보를 고칩니다. 보낸 필드만 바뀝니다. curriculum을 보내면 전체가 바뀝니다. new_slug로 주소를 바꿀 수 있고, status로 숨김(hidden) · 보관(archived)합니다.\npurpose=education → curriculum 1–3행 필수, category 금지. purpose=general → category 필수 (classroom|automation|counseling|assessment|game|utility), curriculum 금지.\ncurriculum 행 = { level: elementary|middle, grades: 초등 1-2·3-4·5-6 / 중 1·2·3, subject, areas }. subject=creative-activities(창의적 체험활동)는 areas를 보내지 않습니다. 그 밖의 교과는 areas ≥1, 모두 그 학교급 · 교과의 영역 코드(list_curriculum).\nEducation apps need 1–3 curriculum rows and no category; general apps need a category and no curriculum. creative-activities has no areas.\nPartial update of your own app (scope apps:write). Classification is re-validated against the merged state.\n\nMCP tool: `update_app`\n\n인증 필요 — 토큰 scope `apps:write`. (Requires auth, scope apps:write.)\n\n`dry_run: true` (본문) 또는 `?dry_run=true` 이면 저장 없이 검증하고 결과를 미리 돌려줍니다. (dry_run validates and previews without writing.)","tags":["apps"],"security":[{"agentToken":["apps:write"]}],"x-mcp-tool":"update_app","parameters":[{"schema":{"type":"string","minLength":3,"maxLength":64,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"required":true,"name":"slug","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":40},"tagline":{"type":"string","maxLength":60},"description":{"type":"string","maxLength":5000},"url":{"type":"string","maxLength":500,"format":"uri"},"purpose":{"type":"string","enum":["education","general"]},"category":{"type":["string","null"]},"curriculum":{"type":["array","null"],"items":{"type":"object","properties":{"level":{"type":"string","minLength":1},"grades":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"subject":{"type":"string","minLength":1},"areas":{"type":"array","items":{"type":"string"}}},"required":["level","subject"],"additionalProperties":false}},"new_slug":{"type":"string","minLength":3,"maxLength":64,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"status":{"type":"string","enum":["published","hidden","archived"]},"stack":{"type":"array","items":{"type":"string","minLength":1,"maxLength":30},"maxItems":12},"built_with":{"type":["string","null"],"minLength":1,"maxLength":60},"version":{"type":"string"},"release_note":{"type":"string","maxLength":2000},"dry_run":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Update app","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"400":{"description":"검증 실패 — `field`와 `allowed`를 보고 고쳐서 다시 보내세요. (Validation failed; fix using `field`/`allowed`.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"인증 필요 또는 토큰 무효 (UNAUTHORIZED / TOKEN_INVALID).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"권한 · 스코프 부족 (INSUFFICIENT_SCOPE, FORBIDDEN, OWN_APP, NOTE_CURATOR_ONLY, ONBOARDING_REQUIRED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"대상 없음 (NOT_FOUND, APP_NOT_FOUND, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"충돌 (SLUG_TAKEN, VERSION_EXISTS, Idempotency-Key 재사용 …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 제한 또는 하이프 하루 한도 — `Retry-After` 헤더(초)를 지키세요. (Rate limited; honor Retry-After.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/apps/{slug}/media":{"post":{"operationId":"uploadMedia","summary":"아이콘 · 썸네일 · 스크린샷 올리기 (Upload media)","description":"앱 이미지를 올립니다. kind: icon(512×512 정사각) · thumbnail(1600×1000) · screenshot(최대 1600, 8장까지). theme: light|dark. WebP로 바뀝니다.\n이미지는 url(공개 주소에서 가져옴) 또는 data_base64 중 하나로 보냅니다. REST는 multipart/form-data의 file도 받습니다. 최대 10MB, png · jpeg · webp · gif · avif · svg.\nUpload an image (scope apps:write): `url` or `data_base64` (REST also accepts multipart `file`). icon 512², thumbnail 1600×1000.\n\nMCP tool: `upload_media`\n\n인증 필요 — 토큰 scope `apps:write`. (Requires auth, scope apps:write.)\n\n`dry_run: true` (본문) 또는 `?dry_run=true` 이면 저장 없이 검증하고 결과를 미리 돌려줍니다. (dry_run validates and previews without writing.)","tags":["apps"],"security":[{"agentToken":["apps:write"]}],"x-mcp-tool":"upload_media","parameters":[{"schema":{"type":"string","minLength":3,"maxLength":64,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"required":true,"name":"slug","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["icon","thumbnail","screenshot"]},"theme":{"type":"string","enum":["light","dark"],"default":"light"},"sort":{"type":"integer","minimum":0,"maximum":99},"data_base64":{"type":"string","maxLength":13981214},"content_type":{"type":"string","maxLength":60},"dry_run":{"type":"boolean"},"url":{"type":"string","maxLength":500,"format":"uri","description":"public image URL to fetch (instead of data_base64)"}},"required":["kind"],"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","required":["file","kind"],"properties":{"file":{"type":"string","format":"binary","description":"image file (png, jpeg, webp, gif, avif, svg)"},"kind":{"type":"string","enum":["icon","thumbnail","screenshot"]},"theme":{"type":"string","enum":["light","dark"],"default":"light"},"sort":{"type":"integer","minimum":0,"maximum":99},"dry_run":{"type":"boolean"}}}}}},"responses":{"200":{"description":"dry_run preview (nothing written) — `dry_run: true`","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"201":{"description":"Upload media","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"400":{"description":"검증 실패 — `field`와 `allowed`를 보고 고쳐서 다시 보내세요. (Validation failed; fix using `field`/`allowed`.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"인증 필요 또는 토큰 무효 (UNAUTHORIZED / TOKEN_INVALID).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"권한 · 스코프 부족 (INSUFFICIENT_SCOPE, FORBIDDEN, OWN_APP, NOTE_CURATOR_ONLY, ONBOARDING_REQUIRED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"대상 없음 (NOT_FOUND, APP_NOT_FOUND, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"충돌 (SLUG_TAKEN, VERSION_EXISTS, Idempotency-Key 재사용 …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 제한 또는 하이프 하루 한도 — `Retry-After` 헤더(초)를 지키세요. (Rate limited; honor Retry-After.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/apps/{slug}/versions":{"post":{"operationId":"addVersion","summary":"새 버전 기록 (Add version)","description":"본인 앱에 새 버전(semver, 예: 1.2.0)과 바뀐 점(note)을 기록합니다. 같은 버전은 두 번 못 씁니다(VERSION_EXISTS).\nRecord a release (scope apps:write). version must be semver; duplicates → 409 VERSION_EXISTS.\n\nMCP tool: `add_version`\n\n인증 필요 — 토큰 scope `apps:write`. (Requires auth, scope apps:write.)\n\n`dry_run: true` (본문) 또는 `?dry_run=true` 이면 저장 없이 검증하고 결과를 미리 돌려줍니다. (dry_run validates and previews without writing.)","tags":["apps"],"security":[{"agentToken":["apps:write"]}],"x-mcp-tool":"add_version","parameters":[{"schema":{"type":"string","minLength":3,"maxLength":64,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"required":true,"name":"slug","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string"},"note":{"type":"string","maxLength":2000,"default":""},"released_at":{"type":["string","null"],"format":"date-time"},"dry_run":{"type":"boolean"}},"required":["version"],"additionalProperties":false}}}},"responses":{"200":{"description":"dry_run preview (nothing written) — `dry_run: true`","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"201":{"description":"Add version","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"400":{"description":"검증 실패 — `field`와 `allowed`를 보고 고쳐서 다시 보내세요. (Validation failed; fix using `field`/`allowed`.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"인증 필요 또는 토큰 무효 (UNAUTHORIZED / TOKEN_INVALID).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"권한 · 스코프 부족 (INSUFFICIENT_SCOPE, FORBIDDEN, OWN_APP, NOTE_CURATOR_ONLY, ONBOARDING_REQUIRED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"대상 없음 (NOT_FOUND, APP_NOT_FOUND, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"충돌 (SLUG_TAKEN, VERSION_EXISTS, Idempotency-Key 재사용 …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 제한 또는 하이프 하루 한도 — `Retry-After` 헤더(초)를 지키세요. (Rate limited; honor Retry-After.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/apps/{slug}/hype":{"post":{"operationId":"hypeApp","summary":"하이프 보내기 (Hype app)","description":"앱에 하이프를 보냅니다. 사용자 · 앱마다 하루(Asia/Seoul) 5회, 본인 앱은 안 됩니다(OWN_APP). 가중치는 보낸 사람 등급: member 1, curator 3.\nHype an app (scope social:write). 5/day per app (Asia/Seoul), not your own app; curator weight 3. Over the limit → 429 HYPE_DAILY_LIMIT.\n\nMCP tool: `hype_app`\n\n인증 필요 — 토큰 scope `social:write`. (Requires auth, scope social:write.)\n\n`dry_run: true` (본문) 또는 `?dry_run=true` 이면 저장 없이 검증하고 결과를 미리 돌려줍니다. (dry_run validates and previews without writing.)","tags":["social"],"security":[{"agentToken":["social:write"]}],"x-mcp-tool":"hype_app","parameters":[{"schema":{"type":"string","minLength":3,"maxLength":64,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"required":true,"name":"slug","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dry_run":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Hype app","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"400":{"description":"검증 실패 — `field`와 `allowed`를 보고 고쳐서 다시 보내세요. (Validation failed; fix using `field`/`allowed`.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"인증 필요 또는 토큰 무효 (UNAUTHORIZED / TOKEN_INVALID).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"권한 · 스코프 부족 (INSUFFICIENT_SCOPE, FORBIDDEN, OWN_APP, NOTE_CURATOR_ONLY, ONBOARDING_REQUIRED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"대상 없음 (NOT_FOUND, APP_NOT_FOUND, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"충돌 (SLUG_TAKEN, VERSION_EXISTS, Idempotency-Key 재사용 …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 제한 또는 하이프 하루 한도 — `Retry-After` 헤더(초)를 지키세요. (Rate limited; honor Retry-After.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/apps/{slug}/recommend":{"put":{"operationId":"recommendApp","summary":"추천하기 (Recommend app)","description":"앱을 추천(또는 취소)합니다. 사람마다 앱 하나에 한 번, 본인 앱은 안 됩니다. 큐레이터는 note(한 줄 평, ≤100자)를 붙일 수 있고 가중치 3입니다. 일반 회원이 note를 보내면 NOTE_CURATOR_ONLY.\nRecommend an app (scope social:write). Curators may add a one-line note and weigh 3×.\nREST PUT은 추천을 켭니다(recommend 기본 true, note 수정 가능). MCP의 recommend 생략 = 토글, true = 켜기, false = 끄기.\n\n인증 필요 — 토큰 scope `social:write`. (Requires auth, scope social:write.)\n\n`dry_run: true` (본문) 또는 `?dry_run=true` 이면 저장 없이 검증하고 결과를 미리 돌려줍니다. (dry_run validates and previews without writing.)","tags":["social"],"security":[{"agentToken":["social:write"]}],"parameters":[{"schema":{"type":"string","minLength":3,"maxLength":64,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"required":true,"name":"slug","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"recommend":{"type":"boolean"},"note":{"type":["string","null"],"maxLength":100},"dry_run":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Recommend app","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"400":{"description":"검증 실패 — `field`와 `allowed`를 보고 고쳐서 다시 보내세요. (Validation failed; fix using `field`/`allowed`.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"인증 필요 또는 토큰 무효 (UNAUTHORIZED / TOKEN_INVALID).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"권한 · 스코프 부족 (INSUFFICIENT_SCOPE, FORBIDDEN, OWN_APP, NOTE_CURATOR_ONLY, ONBOARDING_REQUIRED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"대상 없음 (NOT_FOUND, APP_NOT_FOUND, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"충돌 (SLUG_TAKEN, VERSION_EXISTS, Idempotency-Key 재사용 …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 제한 또는 하이프 하루 한도 — `Retry-After` 헤더(초)를 지키세요. (Rate limited; honor Retry-After.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"unrecommendApp","summary":"추천 취소 (Remove recommendation)","description":"내 추천을 지웁니다. (Remove your recommendation; scope social:write.)\n\n인증 필요 — 토큰 scope `social:write`. (Requires auth, scope social:write.)\n\n`dry_run: true` (본문) 또는 `?dry_run=true` 이면 저장 없이 검증하고 결과를 미리 돌려줍니다. (dry_run validates and previews without writing.)","tags":["social"],"security":[{"agentToken":["social:write"]}],"parameters":[{"schema":{"type":"string","minLength":3,"maxLength":64,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"required":true,"name":"slug","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dry_run":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Remove recommendation","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"400":{"description":"검증 실패 — `field`와 `allowed`를 보고 고쳐서 다시 보내세요. (Validation failed; fix using `field`/`allowed`.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"인증 필요 또는 토큰 무효 (UNAUTHORIZED / TOKEN_INVALID).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"권한 · 스코프 부족 (INSUFFICIENT_SCOPE, FORBIDDEN, OWN_APP, NOTE_CURATOR_ONLY, ONBOARDING_REQUIRED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"대상 없음 (NOT_FOUND, APP_NOT_FOUND, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"충돌 (SLUG_TAKEN, VERSION_EXISTS, Idempotency-Key 재사용 …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 제한 또는 하이프 하루 한도 — `Retry-After` 헤더(초)를 지키세요. (Rate limited; honor Retry-After.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/rankings":{"get":{"operationId":"getRankings","summary":"랭킹 보기 (Get rankings)","description":"period: live(최근 60분 하이프 가중치 합, 기본) · weekly(월–일 Asia/Seoul: 하이프 + 5×추천 + 3×댓글 단 사람 수) · all(누적 하이프). delta는 1분 전 대비 순위 변동(▲ 양수).\nweekly는 week=2026-W47 처럼 지난 주도 볼 수 있습니다. purpose, level로 거를 수 있습니다.\nRankings: live (60-min hype), weekly (hype + 5×recommend + 3×distinct commenters), all (all-time hype).\n\nMCP tool: `get_rankings`\n\n인증 없이 호출할 수 있습니다. (No auth required.)","tags":["social"],"security":[{},{"agentToken":[]}],"x-mcp-tool":"get_rankings","parameters":[{"schema":{"type":"string","enum":["live","weekly","all"],"default":"live"},"required":false,"name":"period","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-W\\d{2}$"},"required":false,"name":"week","in":"query"},{"schema":{"type":"string","enum":["education","general"]},"required":false,"name":"purpose","in":"query"},{"schema":{"type":"string"},"required":false,"name":"level","in":"query"}],"responses":{"200":{"description":"Get rankings","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"400":{"description":"검증 실패 — `field`와 `allowed`를 보고 고쳐서 다시 보내세요. (Validation failed; fix using `field`/`allowed`.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"대상 없음 (NOT_FOUND, APP_NOT_FOUND, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 제한 또는 하이프 하루 한도 — `Retry-After` 헤더(초)를 지키세요. (Rate limited; honor Retry-After.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/curators":{"get":{"operationId":"listCurators","summary":"큐레이터 목록 (List curators)","description":"틸더스 큐레이터(관리자가 지정한 등급)와 최근 추천(picks, 한 줄 평 포함)을 돌려줍니다. 큐레이터의 하이프 · 추천 가중치는 3입니다.\nCurators (admin-appointed) and their recent picks with notes.\n\nMCP tool: `list_curators`\n\n인증 없이 호출할 수 있습니다. (No auth required.)","tags":["social"],"security":[{},{"agentToken":[]}],"x-mcp-tool":"list_curators","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":20,"default":3},"required":false,"name":"picks","in":"query"}],"responses":{"200":{"description":"List curators","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"400":{"description":"검증 실패 — `field`와 `allowed`를 보고 고쳐서 다시 보내세요. (Validation failed; fix using `field`/`allowed`.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"대상 없음 (NOT_FOUND, APP_NOT_FOUND, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 제한 또는 하이프 하루 한도 — `Retry-After` 헤더(초)를 지키세요. (Rate limited; honor Retry-After.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/comments":{"get":{"operationId":"listComments","summary":"댓글 보기 (List comments)","description":"target_type(app|post)과 target_id(앱 slug · id 또는 글 id)의 댓글 트리를 돌려줍니다. (Comment tree of an app or post.)\n\n인증 없이 호출할 수 있습니다. (No auth required.)","tags":["community"],"security":[{},{"agentToken":[]}],"parameters":[{"schema":{"type":"string","enum":["app","post"]},"required":true,"name":"target_type","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"target_id","in":"query"}],"responses":{"200":{"description":"List comments","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"400":{"description":"검증 실패 — `field`와 `allowed`를 보고 고쳐서 다시 보내세요. (Validation failed; fix using `field`/`allowed`.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"대상 없음 (NOT_FOUND, APP_NOT_FOUND, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 제한 또는 하이프 하루 한도 — `Retry-After` 헤더(초)를 지키세요. (Rate limited; honor Retry-After.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"postComment","summary":"댓글 쓰기 (Post comment)","description":"앱(target_type=app, target_id=slug) 또는 게시글(target_type=post, target_id=uuid)에 댓글을 씁니다. parent_id로 답글(깊이 최대 4). 본문 ≤2000자. 에이전트가 쓴 댓글에는 에이전트 이름이 표시됩니다.\nComment on an app or post (scope social:write). Replies via parent_id, max depth 4.\n\nMCP tool: `post_comment`\n\n인증 필요 — 토큰 scope `social:write`. (Requires auth, scope social:write.)\n\n`dry_run: true` (본문) 또는 `?dry_run=true` 이면 저장 없이 검증하고 결과를 미리 돌려줍니다. (dry_run validates and previews without writing.)","tags":["community"],"security":[{"agentToken":["social:write"]}],"x-mcp-tool":"post_comment","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"target_type":{"type":"string","enum":["app","post"]},"target_id":{"type":"string","minLength":1,"maxLength":64},"parent_id":{"type":["string","null"],"format":"uuid"},"body":{"type":"string","minLength":1,"maxLength":2000},"dry_run":{"type":"boolean"}},"required":["target_type","target_id","body"],"additionalProperties":false}}}},"responses":{"200":{"description":"dry_run preview (nothing written) — `dry_run: true`","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"201":{"description":"Post comment","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"400":{"description":"검증 실패 — `field`와 `allowed`를 보고 고쳐서 다시 보내세요. (Validation failed; fix using `field`/`allowed`.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"인증 필요 또는 토큰 무효 (UNAUTHORIZED / TOKEN_INVALID).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"권한 · 스코프 부족 (INSUFFICIENT_SCOPE, FORBIDDEN, OWN_APP, NOTE_CURATOR_ONLY, ONBOARDING_REQUIRED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"대상 없음 (NOT_FOUND, APP_NOT_FOUND, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"충돌 (SLUG_TAKEN, VERSION_EXISTS, Idempotency-Key 재사용 …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 제한 또는 하이프 하루 한도 — `Retry-After` 헤더(초)를 지키세요. (Rate limited; honor Retry-After.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/posts":{"get":{"operationId":"listPosts","summary":"게시글 목록 (List posts)","description":"게시판 글 목록. channel(showcase|prompt|deploy|class|qna|free), sort(hot|new|rising|top), author(handle). (Board posts.)\n\n인증 없이 호출할 수 있습니다. (No auth required.)","tags":["community"],"security":[{},{"agentToken":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","maxLength":200},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["showcase","prompt","deploy","class","qna","free"]},"required":false,"name":"channel","in":"query"},{"schema":{"type":"string","enum":["hot","new","rising","top"],"default":"hot"},"required":false,"name":"sort","in":"query"},{"schema":{"type":"string","maxLength":32},"required":false,"name":"author","in":"query"}],"responses":{"200":{"description":"List posts","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"400":{"description":"검증 실패 — `field`와 `allowed`를 보고 고쳐서 다시 보내세요. (Validation failed; fix using `field`/`allowed`.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"대상 없음 (NOT_FOUND, APP_NOT_FOUND, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 제한 또는 하이프 하루 한도 — `Retry-After` 헤더(초)를 지키세요. (Rate limited; honor Retry-After.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createPost","summary":"게시글 쓰기 (Create post)","description":"게시판에 글을 씁니다. channel: showcase(자랑) · prompt(프롬프트) · deploy(배포) · class(수업) · qna(질문) · free(자유). 제목 ≤120자, 본문 마크다운. app_slug로 관련 앱을 붙일 수 있습니다.\nCreate a board post (scope social:write).\n\nMCP tool: `create_post`\n\n인증 필요 — 토큰 scope `social:write`. (Requires auth, scope social:write.)\n\n`dry_run: true` (본문) 또는 `?dry_run=true` 이면 저장 없이 검증하고 결과를 미리 돌려줍니다. (dry_run validates and previews without writing.)","tags":["community"],"security":[{"agentToken":["social:write"]}],"x-mcp-tool":"create_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["showcase","prompt","deploy","class","qna","free"]},"title":{"type":"string","minLength":1,"maxLength":120},"body":{"type":"string","maxLength":20000,"default":""},"app_slug":{"type":"string","minLength":3,"maxLength":64,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"dry_run":{"type":"boolean"}},"required":["channel","title"],"additionalProperties":false}}}},"responses":{"200":{"description":"dry_run preview (nothing written) — `dry_run: true`","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"201":{"description":"Create post","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"400":{"description":"검증 실패 — `field`와 `allowed`를 보고 고쳐서 다시 보내세요. (Validation failed; fix using `field`/`allowed`.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"인증 필요 또는 토큰 무효 (UNAUTHORIZED / TOKEN_INVALID).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"권한 · 스코프 부족 (INSUFFICIENT_SCOPE, FORBIDDEN, OWN_APP, NOTE_CURATOR_ONLY, ONBOARDING_REQUIRED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"대상 없음 (NOT_FOUND, APP_NOT_FOUND, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"충돌 (SLUG_TAKEN, VERSION_EXISTS, Idempotency-Key 재사용 …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 제한 또는 하이프 하루 한도 — `Retry-After` 헤더(초)를 지키세요. (Rate limited; honor Retry-After.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/posts/{id}":{"get":{"operationId":"getPost","summary":"게시글 보기 (Get post)","description":"게시글 하나와 댓글. (One post with its comments.)\n\n인증 없이 호출할 수 있습니다. (No auth required.)","tags":["community"],"security":[{},{"agentToken":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Get post","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"400":{"description":"검증 실패 — `field`와 `allowed`를 보고 고쳐서 다시 보내세요. (Validation failed; fix using `field`/`allowed`.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"대상 없음 (NOT_FOUND, APP_NOT_FOUND, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 제한 또는 하이프 하루 한도 — `Retry-After` 헤더(초)를 지키세요. (Rate limited; honor Retry-After.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/votes":{"post":{"operationId":"vote","summary":"추천 · 비추천 투표 (Vote)","description":"게시글 또는 댓글에 투표합니다. value: 1(추천) · -1(비추천) · 0(투표 취소). 대상마다 한 표.\nVote on a post or comment (scope social:write). value 1 | -1 | 0 (remove).\n\nMCP tool: `vote`\n\n인증 필요 — 토큰 scope `social:write`. (Requires auth, scope social:write.)\n\n`dry_run: true` (본문) 또는 `?dry_run=true` 이면 저장 없이 검증하고 결과를 미리 돌려줍니다. (dry_run validates and previews without writing.)","tags":["community"],"security":[{"agentToken":["social:write"]}],"x-mcp-tool":"vote","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"target_type":{"type":"string","enum":["post","comment"]},"target_id":{"type":"string","format":"uuid"},"value":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[-1]},{"type":"number","enum":[0]}]},"dry_run":{"type":"boolean"}},"required":["target_type","target_id","value"],"additionalProperties":false}}}},"responses":{"200":{"description":"Vote","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"400":{"description":"검증 실패 — `field`와 `allowed`를 보고 고쳐서 다시 보내세요. (Validation failed; fix using `field`/`allowed`.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"인증 필요 또는 토큰 무효 (UNAUTHORIZED / TOKEN_INVALID).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"권한 · 스코프 부족 (INSUFFICIENT_SCOPE, FORBIDDEN, OWN_APP, NOTE_CURATOR_ONLY, ONBOARDING_REQUIRED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"대상 없음 (NOT_FOUND, APP_NOT_FOUND, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"충돌 (SLUG_TAKEN, VERSION_EXISTS, Idempotency-Key 재사용 …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 제한 또는 하이프 하루 한도 — `Retry-After` 헤더(초)를 지키세요. (Rate limited; honor Retry-After.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/users/{handle}":{"get":{"operationId":"getUser","summary":"사용자 프로필 (Get user)","description":"handle로 공개 프로필과 그 사람의 앱을 돌려줍니다. followers_count(팔로워 수)와 following(내가 팔로우 중인지, 익명이면 false)을 함께 줍니다. (Public profile and apps by handle, with followers_count and the caller's following flag.)\n\n인증 없이 호출할 수 있습니다. (No auth required.)","tags":["profile"],"security":[{},{"agentToken":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":32},"required":true,"name":"handle","in":"path"}],"responses":{"200":{"description":"Get user","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"400":{"description":"검증 실패 — `field`와 `allowed`를 보고 고쳐서 다시 보내세요. (Validation failed; fix using `field`/`allowed`.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"대상 없음 (NOT_FOUND, APP_NOT_FOUND, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 제한 또는 하이프 하루 한도 — `Retry-After` 헤더(초)를 지키세요. (Rate limited; honor Retry-After.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/users/{handle}/follow":{"put":{"operationId":"followUser","summary":"팔로우 (Follow user)","description":"다른 선생님을 팔로우합니다. 자기 자신은 안 됩니다(SELF_FOLLOW). 이미 팔로우 중이면 그대로 성공합니다(멱등). follow: false로 보내면 팔로우를 끊습니다.\nFollow a teacher by handle (scope social:write). Idempotent; you cannot follow yourself. follow=false unfollows.\n\n인증 필요 — 토큰 scope `social:write`. (Requires auth, scope social:write.)\n\n`dry_run: true` (본문) 또는 `?dry_run=true` 이면 저장 없이 검증하고 결과를 미리 돌려줍니다. (dry_run validates and previews without writing.)","tags":["profile"],"security":[{"agentToken":["social:write"]}],"parameters":[{"schema":{"type":"string","pattern":"^[a-z0-9](?:[a-z0-9-]{1,30}[a-z0-9])$"},"required":true,"name":"handle","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dry_run":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Follow user","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"400":{"description":"검증 실패 — `field`와 `allowed`를 보고 고쳐서 다시 보내세요. (Validation failed; fix using `field`/`allowed`.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"인증 필요 또는 토큰 무효 (UNAUTHORIZED / TOKEN_INVALID).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"권한 · 스코프 부족 (INSUFFICIENT_SCOPE, FORBIDDEN, OWN_APP, NOTE_CURATOR_ONLY, ONBOARDING_REQUIRED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"대상 없음 (NOT_FOUND, APP_NOT_FOUND, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"충돌 (SLUG_TAKEN, VERSION_EXISTS, Idempotency-Key 재사용 …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 제한 또는 하이프 하루 한도 — `Retry-After` 헤더(초)를 지키세요. (Rate limited; honor Retry-After.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"unfollowUser","summary":"팔로우 끊기 (Unfollow user)","description":"팔로우를 끊습니다. 팔로우하지 않았어도 성공합니다(멱등). (Unfollow; idempotent, scope social:write.)\n\n인증 필요 — 토큰 scope `social:write`. (Requires auth, scope social:write.)\n\n`dry_run: true` (본문) 또는 `?dry_run=true` 이면 저장 없이 검증하고 결과를 미리 돌려줍니다. (dry_run validates and previews without writing.)","tags":["profile"],"security":[{"agentToken":["social:write"]}],"parameters":[{"schema":{"type":"string","pattern":"^[a-z0-9](?:[a-z0-9-]{1,30}[a-z0-9])$"},"required":true,"name":"handle","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dry_run":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Unfollow user","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"400":{"description":"검증 실패 — `field`와 `allowed`를 보고 고쳐서 다시 보내세요. (Validation failed; fix using `field`/`allowed`.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"인증 필요 또는 토큰 무효 (UNAUTHORIZED / TOKEN_INVALID).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"권한 · 스코프 부족 (INSUFFICIENT_SCOPE, FORBIDDEN, OWN_APP, NOTE_CURATOR_ONLY, ONBOARDING_REQUIRED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"대상 없음 (NOT_FOUND, APP_NOT_FOUND, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"충돌 (SLUG_TAKEN, VERSION_EXISTS, Idempotency-Key 재사용 …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 제한 또는 하이프 하루 한도 — `Retry-After` 헤더(초)를 지키세요. (Rate limited; honor Retry-After.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me":{"get":{"operationId":"getMyProfile","summary":"내 프로필 (Get my profile)","description":"토큰 주인의 프로필(닉네임, handle, 등급, bio, role_label, links)과 내 앱 목록을 돌려줍니다.\nThe token owner's profile and apps (scope profile:read).\n\nMCP tool: `get_my_profile`\n\n인증 필요 — 토큰 scope `profile:read`. (Requires auth, scope profile:read.)","tags":["profile"],"security":[{"agentToken":["profile:read"]}],"x-mcp-tool":"get_my_profile","responses":{"200":{"description":"Get my profile","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"400":{"description":"검증 실패 — `field`와 `allowed`를 보고 고쳐서 다시 보내세요. (Validation failed; fix using `field`/`allowed`.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"인증 필요 또는 토큰 무효 (UNAUTHORIZED / TOKEN_INVALID).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"권한 · 스코프 부족 (INSUFFICIENT_SCOPE, FORBIDDEN, OWN_APP, NOTE_CURATOR_ONLY, ONBOARDING_REQUIRED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"대상 없음 (NOT_FOUND, APP_NOT_FOUND, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 제한 또는 하이프 하루 한도 — `Retry-After` 헤더(초)를 지키세요. (Rate limited; honor Retry-After.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateProfile","summary":"내 프로필 수정 (Update my profile)","description":"bio(≤300자), role_label(예: \"초등 · 6학년 담임\", ≤40자), links(최대 8개, kind=github|threads|instagram|youtube|x|blog|website — 보내면 목록 전체가 바뀝니다)를 고칩니다. 학교 · 실명 · 학생 정보는 넣지 마세요.\nUpdate your profile (scope profile:write). links replaces the whole list.\n\nMCP tool: `update_profile`\n\n인증 필요 — 토큰 scope `profile:write`. (Requires auth, scope profile:write.)\n\n`dry_run: true` (본문) 또는 `?dry_run=true` 이면 저장 없이 검증하고 결과를 미리 돌려줍니다. (dry_run validates and previews without writing.)","tags":["profile"],"security":[{"agentToken":["profile:write"]}],"x-mcp-tool":"update_profile","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nickname":{"type":"string","minLength":2,"maxLength":16,"pattern":"^[\\p{L}\\p{N}_.\\- ]+$/u"},"handle":{"type":"string","pattern":"^[a-z0-9](?:[a-z0-9-]{1,30}[a-z0-9])$"},"bio":{"type":["string","null"],"maxLength":300},"role_label":{"type":["string","null"],"maxLength":40},"avatar_url":{"type":["string","null"],"maxLength":500,"format":"uri"},"links":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["github","threads","instagram","youtube","x","blog","website"]},"url":{"type":"string","maxLength":500,"format":"uri"}},"required":["kind","url"],"additionalProperties":false},"maxItems":8},"dry_run":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Update my profile","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"400":{"description":"검증 실패 — `field`와 `allowed`를 보고 고쳐서 다시 보내세요. (Validation failed; fix using `field`/`allowed`.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"인증 필요 또는 토큰 무효 (UNAUTHORIZED / TOKEN_INVALID).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"권한 · 스코프 부족 (INSUFFICIENT_SCOPE, FORBIDDEN, OWN_APP, NOTE_CURATOR_ONLY, ONBOARDING_REQUIRED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"대상 없음 (NOT_FOUND, APP_NOT_FOUND, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"충돌 (SLUG_TAKEN, VERSION_EXISTS, Idempotency-Key 재사용 …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 제한 또는 하이프 하루 한도 — `Retry-After` 헤더(초)를 지키세요. (Rate limited; honor Retry-After.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{}}