{ "openapi": "3.1.1", "info": { "title": "reopt Inc. 핸드북 공개 조회 API", "version": "1.0.0", "description": "리옵트 핸드북의 공개 REST 조회 API. API 키가 필요하지 않습니다. 계정·책장·인증 API와 MCP JSON-RPC는 이 명세의 대상이 아닙니다. 문서 PUT은 개발용으로 별도 운영되며 공개 통합에는 사용하지 마세요.", "contact": { "url": "https://handbook.reopt.ai/contact" } }, "servers": [ { "url": "https://handbook.reopt.ai" } ], "security": [], "externalDocs": { "url": "https://handbook.reopt.ai/developers", "description": "인증 범위, 빠른 시작, 읽기 전용 테스트" }, "paths": { "/api/search": { "get": { "operationId": "searchHandbook", "summary": "핸드북 본문을 검색합니다. 빈 검색어는 빈 배열을 반환합니다.", "description": "핸드북 본문을 검색합니다. 빈 검색어는 빈 배열을 반환합니다.", "parameters": [ { "name": "query", "in": "query", "required": false, "description": "검색어. 공백을 제거한 뒤 검색합니다.", "schema": { "type": "string" } }, { "name": "locale", "in": "query", "required": false, "description": "언어. 생략 시 한국어.", "schema": { "type": "string", "enum": ["ko", "en"], "default": "ko" } }, { "name": "limit", "in": "query", "required": false, "description": "양의 정수는 최대 100으로 제한하며, 생략하거나 유효하지 않으면 20을 사용합니다.", "schema": { "type": "integer", "minimum": 1, "default": 20 } }, { "name": "tag", "in": "query", "required": false, "description": "쉼표로 구분한 검색 태그", "schema": { "type": "string" } } ], "responses": { "200": { "description": "성공", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": ["id", "url", "content", "type"], "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "content": { "type": "string" }, "type": { "type": "string", "enum": ["page", "heading", "text"] }, "breadcrumbs": { "type": "array", "items": { "type": "string" } } } } } } } }, "500": { "description": "서버 오류", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "지원하지 않는 메서드. Allow 헤더에 허용된 메서드가 있습니다.", "headers": { "Allow": { "schema": { "type": "string" }, "description": "허용된 HTTP 메서드" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/docs/{slug}": { "get": { "operationId": "getHandbookDocument", "summary": "MDX 원문과 수정 시각을 조회합니다. slug는 책 또는 책/챕터 경로이며 ko/ 또는 en/ 접두사가 locale보다 우선합니다.", "description": "MDX 원문과 수정 시각을 조회합니다. slug는 책 또는 책/챕터 경로이며 ko/ 또는 en/ 접두사가 locale보다 우선합니다.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "책 또는 책/챕터 경로. 예: agentic-mvp", "schema": { "type": "string" } }, { "name": "locale", "in": "query", "required": false, "description": "언어. 생략 시 한국어.", "schema": { "type": "string", "enum": ["ko", "en"], "default": "ko" } } ], "responses": { "200": { "description": "성공", "content": { "application/json": { "schema": { "type": "object", "required": ["content", "path", "modifiedAt"], "properties": { "content": { "type": "string" }, "path": { "type": "string" }, "modifiedAt": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "요청 오류", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "요청 오류", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "서버 오류", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "지원하지 않는 메서드. Allow 헤더에 허용된 메서드가 있습니다.", "headers": { "Allow": { "schema": { "type": "string" }, "description": "허용된 HTTP 메서드" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/home-books/chapters/{slug}": { "get": { "operationId": "listHandbookChapters", "summary": "핸드북의 챕터 제목을 순서대로 반환합니다.", "description": "핸드북의 챕터 제목을 순서대로 반환합니다.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "핸드북 식별자. 예: agentic-mvp", "schema": { "type": "string" } }, { "name": "locale", "in": "query", "required": false, "description": "언어. 생략 시 한국어.", "schema": { "type": "string", "enum": ["ko", "en"], "default": "ko" } } ], "responses": { "200": { "description": "성공", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "404": { "description": "요청 오류", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "서버 오류", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "지원하지 않는 메서드. Allow 헤더에 허용된 메서드가 있습니다.", "headers": { "Allow": { "schema": { "type": "string" }, "description": "허용된 HTTP 메서드" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/graph": { "get": { "operationId": "getHandbookGraph", "summary": "문서 노드와 링크·폴더·키워드 관계를 반환합니다.", "description": "문서 노드와 링크·폴더·키워드 관계를 반환합니다.", "parameters": [ { "name": "locale", "in": "query", "required": false, "description": "언어. 생략 시 한국어.", "schema": { "type": "string", "enum": ["ko", "en"], "default": "ko" } } ], "responses": { "200": { "description": "성공", "content": { "application/json": { "schema": { "type": "object", "required": ["nodes", "links"], "properties": { "nodes": { "type": "array", "items": { "type": "object", "required": ["id", "title", "group"], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "group": { "type": "string" }, "description": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } } } } }, "links": { "type": "array", "items": { "type": "object", "required": ["source", "target", "type"], "properties": { "source": { "type": "string" }, "target": { "type": "string" }, "type": { "type": "string", "enum": ["link", "folder", "keyword"] } } } } } } } } }, "500": { "description": "서버 오류", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "지원하지 않는 메서드. Allow 헤더에 허용된 메서드가 있습니다.", "headers": { "Allow": { "schema": { "type": "string" }, "description": "허용된 HTTP 메서드" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "required": ["type", "title", "status", "detail", "error", "code", "resolution"], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "detail": { "type": "string" }, "error": { "type": "string" }, "code": { "type": "string" }, "resolution": { "type": "string" }, "status": { "type": "integer", "minimum": 400, "maximum": 599 } } } } } }