{"openapi":"3.1.0","info":{"title":"Persona Wiki public API","version":"0.6.0","description":"공개 위키와 컨텍스트 다운로드. 익명 3회/분·20회/일, API 키 계정 합산 5회/분·100회/일. 받아둔 컨텍스트를 재사용합니다."},"servers":[{"url":"https://personawiki.app"}],"security":[],"paths":{"/api/v1/manifest":{"get":{"operationId":"getPublicationManifest","summary":"하루 한 번 확인할 발행 식별자","responses":{"200":{"description":"release와 페르소나 버전 목록"},"304":{"description":"변경 없음"},"429":{"description":"요청 또는 공개 페르소나 오류","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"503":{"description":"요청 또는 공개 페르소나 오류","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/v1/knowledge":{"get":{"operationId":"listKnowledge","summary":"직무별 이론·지식 검색","parameters":[{"name":"persona_id","in":"query","schema":{"type":"string","maxLength":80},"description":"공개 페르소나 ID"},{"name":"category","in":"query","schema":{"type":"string","maxLength":80},"description":"지식 목록의 직업군 이름"},{"name":"kind","in":"query","schema":{"type":"string","enum":["theory","framework","method","standard","principle"]}},{"name":"q","in":"query","schema":{"type":"string","maxLength":200},"description":"ID·제목·요약·핵심 개념 검색"}],"responses":{"200":{"description":"검색 목록","content":{"application/json":{"schema":{"type":"object","required":["knowledge","total","version","filters"],"properties":{"knowledge":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeSummary"}},"total":{"type":"integer"},"version":{"type":"string"},"filters":{"type":"object","additionalProperties":{"type":"string"}}}}}}},"400":{"description":"요청 또는 공개 페르소나 오류","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"요청 또는 공개 페르소나 오류","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/v1/knowledge/{knowledgeId}":{"get":{"operationId":"getKnowledge","summary":"출처·조건을 포함한 이론·지식 상세","parameters":[{"name":"knowledgeId","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","in":"query","schema":{"type":"string","pattern":"^kb-[a-f0-9]{16}$"},"description":"생략하면 현재, 지정하면 보관된 지식 버전"}],"responses":{"200":{"description":"참고 지식","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Knowledge"}}}},"400":{"description":"요청 또는 공개 페르소나 오류","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"요청 또는 공개 페르소나 오류","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/v1/personas/{personaId}/versions":{"get":{"operationId":"listPersonaVersions","summary":"현재·보관 버전 목록","parameters":[{"name":"personaId","in":"path","required":true,"schema":{"type":"string"},"description":"공개 목록의 안정적인 페르소나 ID"}],"responses":{"200":{"description":"판단 구조·지식 고정 버전. 승인 취소·수정된 경험은 과거 버전에서도 제외.","content":{"application/json":{"schema":{"type":"object","properties":{"persona_id":{"type":"string"},"versions":{"type":"array","items":{"type":"object","properties":{"version":{"type":"string"},"updated_at":{"type":"string"},"current":{"type":"boolean"}}}},"policy":{"type":"string"}}}}}},"400":{"description":"요청 또는 공개 페르소나 오류","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"요청 또는 공개 페르소나 오류","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/v1/personas":{"get":{"operationId":"listPersonas","summary":"서비스가 제공하는 공개 페르소나 목록","responses":{"200":{"description":"공개 목록","content":{"application/json":{"schema":{"type":"object","required":["personas"],"properties":{"personas":{"type":"array","items":{"$ref":"#/components/schemas/Persona"}}}}}}},"400":{"description":"요청 또는 공개 페르소나 오류","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}},"parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":200},"description":"직무 이름·설명·배치·판단 내용 검색"},{"name":"category","in":"query","schema":{"type":"string","maxLength":80},"description":"공개 목록의 직업군 이름. q와 함께 적용"}]}},"/api/v1/personas/{personaId}":{"get":{"operationId":"getPersona","summary":"기본 판단 구조와 성향 설정","parameters":[{"name":"personaId","in":"path","required":true,"schema":{"type":"string"},"description":"공개 목록의 안정적인 페르소나 ID"}],"responses":{"200":{"description":"페르소나","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Persona"}}}},"404":{"description":"요청 또는 공개 페르소나 오류","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/v1/personas/{personaId}/context":{"get":{"operationId":"getPersonaContext","summary":"관리자가 갱신한 기본 컨텍스트","parameters":[{"name":"personaId","in":"path","required":true,"schema":{"type":"string"},"description":"공개 목록의 안정적인 페르소나 ID"},{"name":"format","in":"query","schema":{"type":"string","enum":["json","text"],"default":"json"}},{"name":"task","in":"query","schema":{"type":"string","maxLength":2000}},{"name":"include","in":"query","schema":{"type":"string","enum":["knowledge"]},"description":"예산 내 관련 지식을 reference-data로 함께 반환. 부족하면 usage.omitted_knowledge_documents에 표시"},{"name":"version","in":"query","schema":{"type":"string","maxLength":200},"description":"versions 목록의 고정 버전. 없으면 현재 버전"},{"name":"directions","in":"query","schema":{"type":"string","maxLength":1000},"description":"축 ID:0~100을 쉼표로 연결. 예: pace:30,change:60. 선택하지 않은 축은 기본값"},{"name":"token_budget","in":"query","schema":{"type":"integer","minimum":256,"maximum":8192,"default":4096}}],"responses":{"200":{"description":"컨텍스트","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Context"}},"text/plain":{"schema":{"type":"string"}}}},"304":{"description":"변경 없음. 요청 한도에는 포함됩니다."},"400":{"description":"요청 또는 공개 페르소나 오류","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"401":{"description":"요청 또는 공개 페르소나 오류","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"요청 또는 공개 페르소나 오류","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"422":{"description":"요청 또는 공개 페르소나 오류","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"요청 또는 공개 페르소나 오류","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"재시도 대기 초"}}},"503":{"description":"요청 또는 공개 페르소나 오류","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}},"security":[{},{"PersonaKey":[]}]}},"/api/v1/changes":{"get":{"operationId":"listPublicChanges","summary":"최근 공개 반영 기록","responses":{"200":{"description":"변경 기록","content":{"application/json":{"schema":{"type":"object","properties":{"changes":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}}}}}},"components":{"securitySchemes":{"PersonaKey":{"type":"http","scheme":"bearer","description":"개인 설정에서 발급한 무료 API 키. 서버에서만 보관합니다."}},"schemas":{"KnowledgeReference":{"type":"object","required":["id","title","version","links"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"version":{"type":"string"},"links":{"type":"object","required":["document","markdown","api"],"properties":{"document":{"type":"string"},"markdown":{"type":"string"},"api":{"type":"string"}}}}},"KnowledgeSummary":{"type":"object","required":["id","title","category","kind","summary","persona_ids","version","revision","updated_at","links"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"version":{"type":"string"},"links":{"type":"object","required":["document","markdown","api"],"properties":{"document":{"type":"string"},"markdown":{"type":"string"},"api":{"type":"string"}}},"category":{"type":"string"},"kind":{"type":"string","enum":["theory","framework","method","standard","principle"]},"summary":{"type":"string"},"persona_ids":{"type":"array","items":{"type":"string"}},"revision":{"type":"integer","minimum":1},"updated_at":{"type":"string","format":"date-time"}}},"Knowledge":{"allOf":[{"$ref":"#/components/schemas/KnowledgeSummary"},{"type":"object","required":["concepts","application","limitations","directions","sources","review","trust","editorial_note"],"properties":{"concepts":{"type":"array","items":{"type":"string"}},"application":{"type":"string"},"limitations":{"type":"string"},"directions":{"type":"array","items":{"type":"string"}},"editorial_note":{"type":"string"},"kind_label":{"type":"string"},"trust":{"type":"string","const":"reference-data"},"review":{"type":"object","required":["status","expert_reviewed"],"properties":{"status":{"type":"string","const":"source-checked-editorial"},"expert_reviewed":{"type":"boolean","const":false}}},"sources":{"type":"array","minItems":1,"items":{"type":"object","required":["title","url","publisher","edition","region","checked_at","reuse"],"properties":{"title":{"type":"string"},"url":{"type":"string","format":"uri"},"publisher":{"type":"string"},"edition":{"type":"string"},"region":{"type":"string"},"checked_at":{"type":"string","format":"date"},"reuse":{"type":"string"}}}}}}]},"Persona":{"type":"object","required":["id","name","version","links"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"job_id":{"type":"string"},"version":{"type":"string"},"updated_at":{"type":"string","format":"date-time"},"defaults":{"type":"object","additionalProperties":true},"judgment":{"type":"array","items":{"type":"object","additionalProperties":true}},"directions":{"type":"array","items":{"type":"object","additionalProperties":true}},"knowledge_references":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeReference"}},"knowledge_version":{"type":"string"},"links":{"type":"object","properties":{"document":{"type":"string"},"markdown":{"type":"string"},"context":{"type":"string"}}}}},"Context":{"type":"object","required":["persona_id","version","persona_instructions","knowledge_data"],"properties":{"persona_id":{"type":"string"},"name":{"type":"string"},"version":{"type":"string"},"updated_at":{"type":"string","format":"date-time"},"tree_version":{"type":"integer"},"persona_instructions":{"type":"array","items":{"type":"string"}},"knowledge_data":{"type":"array","items":{"type":"object","additionalProperties":true}},"knowledge_references":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeReference"},"description":"별도 조회용 메타데이터. token_budget 계산에는 포함되지 않음"},"knowledge_version":{"type":"string"},"provenance":{"type":"array","items":{"type":"object","additionalProperties":true}},"knowledge_documents":{"type":"array","items":{"$ref":"#/components/schemas/Knowledge"}},"selected_directions":{"type":"object","additionalProperties":{"type":"integer","minimum":0,"maximum":100}},"pinned_version":{"type":"string"},"context_fingerprint":{"type":"string"},"version_policy":{"type":"string"},"usage":{"type":"object","additionalProperties":true},"integration":{"type":"string"},"mode":{"type":"string","enum":["service-default","custom-directions"]}}}}}}