The社史 - API for AI Agents

openapi: 3.1.0
info:
  title: The社史 Public Data API
  version: "3.0"
servers:
  - url: https://the-shashi.com
paths:
  /api/companies.json:
    get:
      summary: 公開エントリポイント — 全社一覧 + 公開エンドポイント目録
      responses:
        "200":
          description: |
            LLM/外部から最初に叩くエントリポイント。公開エンドポイント目録 (endpoints) と
            全公開企業の最小インデックス (contents: stock_code / name / industry / updated) を 1 リクエストで返す。
            各社の詳細は /api/{stock_code}/manifest.json から辿る。
          content:
            application/json:
              schema:
                type: object
                properties:
                  version: { type: string, example: "3" }
                  base: { type: string, example: "https://the-shashi.com" }
                  endpoints:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        method: { type: string, example: "GET" }
                        path: { type: string }
                        label: { type: string }
                        description: { type: string }
                        format: { type: string, enum: ["json", "csv"] }
                        scope: { type: string, enum: ["global", "company"] }
                      additionalProperties: false
                  contents:
                    type: array
                    items:
                      type: object
                      properties:
                        stock_code: { type: string, example: "1332" }
                        name: { type: string }
                        industry: { type: string, nullable: true }
                      additionalProperties: false
                additionalProperties: false

  /api/{stock_code}/manifest.json:
    get:
      summary: リソース目録 + プロファイル
      parameters:
        - in: path
          name: stock_code
          required: true
          schema: { type: string, example: "7203" }
      responses:
        "200":
          description: 会社プロファイル（社名/業種/上場日/カラー等）とリソース目録
          content:
            application/json:
              schema:
                type: object
                properties:
                  version: { type: string, example: "3" }
                  stock_code: { type: string }
                  company_name: { type: string }
                  profile:
                    type: object
                    properties:
                      company_color: { type: string }
                      industry: { type: string }
                      published: { type: string, format: date }
                      updated: { type: string, format: date }
                      found:
                        type: object
                        properties:
                          year: { type: integer }
                          location: { type: string }
                          founder: { type: string }
                      listing:
                        type: object
                        properties:
                          listed_year: { type: integer, nullable: true }
                          delisted_year: { type: integer, nullable: true }
                          unlisted: { type: boolean }
                      old_name: { type: string }
                      name_kana: { type: string }
                      old_name_kana: { type: string }
                  resources:
                    type: object
                    additionalProperties:
                      type: object
                      properties:
                        is_active: { type: boolean }
                        url: { type: string }
                        format: { type: string }
                        description: { type: string }
                        chars_ja: { type: integer }

  /api/{stock_code}/history.json:
    get:
      summary: 歴史概略
      parameters:
        - in: path
          name: stock_code
          required: true
          schema: { type: string, example: "7203" }
      responses:
        "200":
          description: 章立て歴史エッセイ + サマリー + 筆者所感 + 直近の動向と展望 + 出典・引用
          content:
            application/json:
              schema:
                type: object
                properties:
                  title: { type: string }
                  sections:
                    type: array
                    items: { type: object, additionalProperties: true }
                  summary:
                    type: object
                    properties:
                      title: { type: string }
                      text: { type: string }
                      sections:
                        type: array
                        items: { type: object, additionalProperties: true }
                  author_note: { type: array, items: { type: string } }
                  outlook:
                    type: object
                    properties:
                      title: { type: string }
                      subsections:
                        type: array
                        items: { type: object, additionalProperties: true }
                  references: { type: array, items: { type: object, additionalProperties: true } }
                  quotes: { type: array, items: { type: object, additionalProperties: true } }
                additionalProperties: true

  /api/{stock_code}/timeline.json:
    get:
      summary: 沿革
      parameters:
        - in: path
          name: stock_code
          required: true
          schema: { type: string, example: "7203" }
      responses:
        "200":
          description: 沿革年表 + 経営判断カード
          content:
            application/json:
              schema:
                type: object
                properties:
                  timeline: { type: array, items: { type: object, additionalProperties: true } }
                  decisions: { type: array, items: { type: object, additionalProperties: true } }
                additionalProperties: true

  /api/{stock_code}/executives.json:
    get:
      summary: 役員
      parameters:
        - in: path
          name: stock_code
          required: true
          schema: { type: string, example: "7203" }
      responses:
        "200":
          description: 役員データ全件（経歴・専門性・報酬）+ 歴代経営者
          content:
            application/json:
              schema:
                type: object
                properties:
                  commentary: { type: string }
                  executives: { type: array, items: { type: object, additionalProperties: true } }
                  careers: { type: array, items: { type: object, additionalProperties: true } }
                  officer: { type: array, items: { type: object, additionalProperties: true } }
                  ceo_history: { type: array, items: { type: object, additionalProperties: true } }
                  ceo_commentary: { type: string }
                additionalProperties: true

  /api/{stock_code}/shareholders.json:
    get:
      summary: 大株主
      parameters:
        - in: path
          name: stock_code
          required: true
          schema: { type: string, example: "7203" }
      responses:
        "200":
          description: 大株主データ（FY×rank、長期株主含む）
          content:
            application/json:
              schema:
                type: object
                properties:
                  commentary: { type: string }
                  shareholders: { type: array, items: { type: object, additionalProperties: true } }
                  categories: { type: array, items: { type: object, additionalProperties: true } }
                  long_term: { type: array, items: { type: object, additionalProperties: true } }
                additionalProperties: true

  /api/{stock_code}/financials.json:
    get:
      summary: 財務三表
      parameters:
        - in: path
          name: stock_code
          required: true
          schema: { type: string, example: "7203" }
      responses:
        "200":
          description: FY01以降の純粋 PL/BS/CF
          content:
            application/json:
              schema:
                type: object
                properties:
                  commentary: { type: string }
                  financials: { type: array, items: { type: object, additionalProperties: true } }
                  cf: { type: array, items: { type: object, additionalProperties: true } }
                  bs: { type: array, items: { type: object, additionalProperties: true } }
                  pl_detail: { type: array, items: { type: object, additionalProperties: true } }
                  bs_detail: { type: array, items: { type: object, additionalProperties: true } }
                additionalProperties: true

  /api/{stock_code}/financials-longterm.json:
    get:
      summary: 長期業績
      parameters:
        - in: path
          name: stock_code
          required: true
          schema: { type: string, example: "7203" }
      responses:
        "200":
          description: 創業〜現在の長期業績時系列（売上・利益・従業員）
          content:
            application/json:
              schema:
                type: object
                properties:
                  history: { type: array, items: { type: object, additionalProperties: true } }
                additionalProperties: true

  /api/{stock_code}/segments.json:
    get:
      summary: 事業セグメント
      parameters:
        - in: path
          name: stock_code
          required: true
          schema: { type: string, example: "7203" }
      responses:
        "200":
          description: 事業セグメント別の財務データ
          content:
            application/json:
              schema:
                type: object
                properties:
                  segment: { type: array, items: { type: object, additionalProperties: true } }

  /api/{stock_code}/regions.json:
    get:
      summary: 地域別売上
      parameters:
        - in: path
          name: stock_code
          required: true
          schema: { type: string, example: "7203" }
      responses:
        "200":
          description: 地域別売上
          content:
            application/json:
              schema:
                type: object
                properties:
                  region: { type: array, items: { type: object, additionalProperties: true } }

  /api/{stock_code}/workforce.json:
    get:
      summary: 従業員
      parameters:
        - in: path
          name: stock_code
          required: true
          schema: { type: string, example: "7203" }
      responses:
        "200":
          description: 従業員データ（人数・年収・平均年齢）
          content:
            application/json:
              schema:
                type: object
                properties:
                  employee: { type: array, items: { type: object, additionalProperties: true } }

  /api/{stock_code}/financials.csv:
    get:
      summary: 財務 CSV
      parameters:
        - in: path
          name: stock_code
          required: true
          schema: { type: string, example: "7203" }
      responses:
        "200":
          description: 財務三表（PL/BS/CF）の CSV ダウンロード
          content:
            text/csv:
              schema: { type: string, format: binary }

  /api/{stock_code}/financials_history.csv:
    get:
      summary: 長期業績 CSV
      parameters:
        - in: path
          name: stock_code
          required: true
          schema: { type: string, example: "7203" }
      responses:
        "200":
          description: 創業〜現在の長期業績時系列の CSV ダウンロード
          content:
            text/csv:
              schema: { type: string, format: binary }

  /api/{stock_code}/segments.csv:
    get:
      summary: セグメント CSV
      parameters:
        - in: path
          name: stock_code
          required: true
          schema: { type: string, example: "7203" }
      responses:
        "200":
          description: 事業セグメント別財務データの CSV ダウンロード
          content:
            text/csv:
              schema: { type: string, format: binary }