openapi: "3.1.0"
info:
  title: BASE REST API
  version: "1.0.0"
  description: |
    クラウド型ナレッジベース BASE の読み取り API。
    Base 内のページ一覧取得、個別ページ取得、キーワード検索、階層ツリー取得、Base 情報取得が可能です。
servers:
  - url: https://base.kodama.com/api/v1
    description: Production
security:
  - bearerAuth: []
paths:
  /bases/{base_id}/info:
    get:
      operationId: getBaseInfo
      summary: Base の概要情報を取得
      description: Base の名前、公開設定、総ページ数を返します。
      parameters:
        - name: base_id
          in: path
          required: true
          description: Base ID
          schema:
            type: string
      responses:
        "200":
          description: Base 情報
          content:
            application/json:
              schema:
                type: object
                properties:
                  base_id:
                    type: string
                    description: Base ID
                  description:
                    type: string
                    description: Base の説明
                  view:
                    type: string
                    enum: ["O", "L", "I"]
                    description: "公開設定（O: 公開, L: メンバー限定, I: ログインユーザー限定）"
                  total_pages:
                    type: integer
                    description: 総ページ数
                required:
                  - base_id
                  - description
                  - view
                  - total_pages

  /bases/{base_id}/pages:
    get:
      operationId: listPages
      summary: ページ一覧を取得
      description: Base 内の全ページを表示順で返します。
      parameters:
        - name: base_id
          in: path
          required: true
          description: Base ID
          schema:
            type: string
      responses:
        "200":
          description: ページ一覧
          content:
            application/json:
              schema:
                type: object
                properties:
                  pages:
                    type: array
                    items:
                      type: object
                      properties:
                        content_id:
                          type: string
                          description: コンテンツ ID
                        title:
                          type: string
                          description: ページタイトル
                        type:
                          type: string
                          description: コンテンツ種別
                        level:
                          type: integer
                          description: 階層レベル（0 がルート）
                        order:
                          type: integer
                          description: 表示順序
                        lang:
                          type: string
                          description: 言語コード
                        updated_at:
                          type: string
                          description: 最終更新日時（UTC ISO 8601）
                  total:
                    type: integer
                    description: 総ページ数
                required:
                  - pages
                  - total

  /bases/{base_id}/pages/{content_id}:
    get:
      operationId: getPage
      summary: ページ詳細を取得
      description: 指定ページの本文（Markdown）とメタ情報を返します。
      parameters:
        - name: base_id
          in: path
          required: true
          description: Base ID
          schema:
            type: string
        - name: content_id
          in: path
          required: true
          description: コンテンツ ID（英数字6文字）
          schema:
            type: string
      responses:
        "200":
          description: ページ詳細
          content:
            application/json:
              schema:
                type: object
                properties:
                  content_id:
                    type: string
                    description: コンテンツ ID
                  title:
                    type: string
                    description: ページタイトル
                  body:
                    type: string
                    description: ページ本文（Markdown ソース）
                  type:
                    type: string
                    description: コンテンツ種別
                  level:
                    type: integer
                    description: 階層レベル
                  path:
                    type: array
                    items:
                      type: string
                    description: ルートからのパス（タイトル配列）
                  lang:
                    type: string
                    description: 言語コード
                  created_at:
                    type: string
                    description: 作成日時（UTC ISO 8601）
                  updated_at:
                    type: string
                    description: 最終更新日時（UTC ISO 8601）
                required:
                  - content_id
                  - title
                  - body
                  - type
                  - level
                  - path
                  - lang
                  - created_at
                  - updated_at

  /bases/{base_id}/search:
    get:
      operationId: searchPages
      summary: ページを検索
      description: キーワードでページのタイトル・本文を検索し、スコア順で返します。
      parameters:
        - name: base_id
          in: path
          required: true
          description: Base ID
          schema:
            type: string
        - name: q
          in: query
          required: true
          description: 検索キーワード
          schema:
            type: string
      responses:
        "200":
          description: 検索結果
          content:
            application/json:
              schema:
                type: object
                properties:
                  pages:
                    type: array
                    items:
                      type: object
                      properties:
                        content_id:
                          type: string
                          description: コンテンツ ID
                        title:
                          type: string
                          description: ページタイトル
                        type:
                          type: string
                          description: コンテンツ種別
                        level:
                          type: integer
                          description: 階層レベル（0 がルート）
                        order:
                          type: integer
                          description: 表示順序
                        lang:
                          type: string
                          description: 言語コード
                        updated_at:
                          type: string
                          description: 最終更新日時（UTC ISO 8601）
                  total:
                    type: integer
                    description: 検索結果件数
                  keywords:
                    type: string
                    description: 検索に使用したキーワード
                required:
                  - pages
                  - total
                  - keywords

  /bases/{base_id}/tree:
    get:
      operationId: getPageTree
      summary: ページツリーを取得
      description: ページの階層構造をネストされたツリー形式で返します。各ノードは content_id, title, level, children を持ちます。children は同じ構造の配列です（最大3階層）。
      parameters:
        - name: base_id
          in: path
          required: true
          description: Base ID
          schema:
            type: string
      responses:
        "200":
          description: ページツリー
          content:
            application/json:
              schema:
                type: object
                properties:
                  tree:
                    type: array
                    items:
                      type: object
                      properties:
                        content_id:
                          type: string
                          description: コンテンツ ID
                        title:
                          type: string
                          description: ページタイトル
                        level:
                          type: integer
                          description: 階層レベル
                        children:
                          type: array
                          description: 子ページ
                          items:
                            type: object
                            properties:
                              content_id:
                                type: string
                              title:
                                type: string
                              level:
                                type: integer
                              children:
                                type: array
                                description: 孫ページ
                                items:
                                  type: object
                                  properties:
                                    content_id:
                                      type: string
                                    title:
                                      type: string
                                    level:
                                      type: integer
                                    children:
                                      type: array
                                      items:
                                        type: object
                required:
                  - tree

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: KID で発行した API トークン
  schemas: {}
