{
  "openapi": "3.1.0",
  "info": {
    "title": "ComePass Agents API",
    "version": "0.1.0",
    "description": "Source-verified reference intelligence for AI agents. Every item includes source_url and verified_at."
  },
  "servers": [
    {
      "url": "https://agents.comepass.xyz"
    }
  ],
  "paths": {
    "/api/v1/kr-companies": {
      "get": {
        "operationId": "list_kr_companies",
        "summary": "List items in Korean Company Facts (KOSPI)",
        "description": "English company profiles, annual financial statements in KRW, and recent 90-day DART filings for KOSPI-listed Korean companies, plus National Tax Service business registration status verification.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Optional case-insensitive search query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum items to return (1..500)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Items for module kr-companies",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "module",
                    "count",
                    "source_url",
                    "verified_at",
                    "items"
                  ],
                  "properties": {
                    "module": {
                      "type": "string",
                      "const": "kr-companies"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "source_url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "verified_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/kr-companies_item"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/kr-companies/{itemId}": {
      "get": {
        "operationId": "get_kr_companies_item",
        "summary": "Get a single item in Korean Company Facts (KOSPI)",
        "description": "Returns structured item data with source_url and verified_at for Korean Company Facts (KOSPI).",
        "parameters": [
          {
            "name": "itemId",
            "in": "path",
            "required": true,
            "description": "Item identifier",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Single item from kr-companies",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/kr-companies_item"
                }
              }
            }
          },
          "404": {
            "description": "Item not found"
          }
        }
      }
    },
    "/api/v1/kr-companies/{corp_code}/filings": {
      "get": {
        "summary": "List recent DART filings for a KOSPI company",
        "description": "Returns stored recent filings (up to 90 days / 20 filings) optionally filtered by since=YYYY-MM-DD.",
        "parameters": [
          {
            "name": "corp_code",
            "in": "path",
            "required": true,
            "description": "8-digit DART corp_code",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "description": "Filter filings on or after YYYY-MM-DD",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List recent DART filings for a KOSPI company"
          }
        }
      }
    },
    "/api/v1/kr-business-status": {
      "get": {
        "operationId": "check_kr_business_status",
        "summary": "Check Korean business registration status (NTS)",
        "description": "Queries the National Tax Service (NTS) business registration status API for 1 to 10 Korean 10-digit business numbers.",
        "parameters": [
          {
            "name": "b_no",
            "in": "query",
            "required": true,
            "description": "Comma-separated 1..10 Korean 10-digit business registration numbers",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Business registration status results"
          },
          "400": {
            "description": "Invalid business number input"
          },
          "503": {
            "description": "NTS API key not configured"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "kr-companies_item": {
        "type": "object",
        "required": [
          "module",
          "itemId",
          "title",
          "summary",
          "data",
          "source_url",
          "verified_at",
          "updated_at"
        ],
        "properties": {
          "module": {
            "type": "string",
            "const": "kr-companies"
          },
          "itemId": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "required": [
              "corp_code",
              "stock_code",
              "name_ko",
              "alternate_names",
              "market",
              "verified_at",
              "notice"
            ],
            "properties": {
              "corp_code": {
                "type": "string"
              },
              "stock_code": {
                "type": "string"
              },
              "name_en": {
                "type": "string",
                "description": "English name (as registered with DART)"
              },
              "name_ko": {
                "type": "string",
                "description": "Korean legal name"
              },
              "alternate_names": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Other DART English names and KRX stock name"
              },
              "market": {
                "type": "string",
                "const": "KOSPI"
              },
              "business_registration_no": {
                "type": "string"
              },
              "industry_code": {
                "type": "string"
              },
              "verified_at": {
                "type": "string",
                "format": "date-time"
              },
              "notice": {
                "type": "string"
              }
            }
          },
          "source_url": {
            "type": "string",
            "format": "uri"
          },
          "verified_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  }
}