{
  "openapi": "3.1.0",
  "info": {
    "title": "K-Data Gate API",
    "version": "0.1.0",
    "description": "Korean data, agent-ready. No-payment pilot now, Paddle later."
  },
  "servers": [
    {
      "url": "http://localhost:3000/api"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerApiKey": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "paths": {
    "/api/v1/products": {
      "get": {
        "summary": "Query products",
        "security": [
          {
            "bearerApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "preview",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "source",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dataset response with data and meta."
          },
          "400": {
            "description": "Bad parameters."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "402": {
            "description": "Insufficient credits."
          },
          "429": {
            "description": "Rate limited."
          }
        }
      }
    },
    "/api/v1/realestate": {
      "get": {
        "summary": "Query realestate",
        "security": [
          {
            "bearerApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "preview",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "region",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "yyyymm",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "min_price_usd",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "max_price_usd",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dataset response with data and meta."
          },
          "400": {
            "description": "Bad parameters."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "402": {
            "description": "Insufficient credits."
          },
          "429": {
            "description": "Rate limited."
          }
        }
      }
    },
    "/api/v1/companies": {
      "get": {
        "summary": "Query companies",
        "security": [
          {
            "bearerApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "preview",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "corp",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "report",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "year",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dataset response with data and meta."
          },
          "400": {
            "description": "Bad parameters."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "402": {
            "description": "Insufficient credits."
          },
          "429": {
            "description": "Rate limited."
          }
        }
      }
    },
    "/api/v1/stocks": {
      "get": {
        "summary": "Query stocks",
        "security": [
          {
            "bearerApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "preview",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "ticker",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "market",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sector",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dataset response with data and meta."
          },
          "400": {
            "description": "Bad parameters."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "402": {
            "description": "Insufficient credits."
          },
          "429": {
            "description": "Rate limited."
          }
        }
      }
    },
    "/api/v1/stocks/prices": {
      "get": {
        "summary": "Query stock-prices",
        "security": [
          {
            "bearerApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "preview",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "ticker",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "market",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "date_from",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "date_to",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "adjusted",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dataset response with data and meta."
          },
          "400": {
            "description": "Bad parameters."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "402": {
            "description": "Insufficient credits."
          },
          "429": {
            "description": "Rate limited."
          }
        }
      }
    },
    "/api/v1/stocks/fundamentals": {
      "get": {
        "summary": "Query stock-fundamentals",
        "security": [
          {
            "bearerApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "preview",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "ticker",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "corp",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "year",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "quarter",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "metric",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dataset response with data and meta."
          },
          "400": {
            "description": "Bad parameters."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "402": {
            "description": "Insufficient credits."
          },
          "429": {
            "description": "Rate limited."
          }
        }
      }
    },
    "/api/v1/stocks/disclosures": {
      "get": {
        "summary": "Query stock-disclosures",
        "security": [
          {
            "bearerApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "preview",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "ticker",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "corp",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "report",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "date_from",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "date_to",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dataset response with data and meta."
          },
          "400": {
            "description": "Bad parameters."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "402": {
            "description": "Insufficient credits."
          },
          "429": {
            "description": "Rate limited."
          }
        }
      }
    },
    "/api/v1/stocks/flows": {
      "get": {
        "summary": "Query stock-flows",
        "security": [
          {
            "bearerApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "preview",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "ticker",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "market",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "investor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "date_from",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "date_to",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dataset response with data and meta."
          },
          "400": {
            "description": "Bad parameters."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "402": {
            "description": "Insufficient credits."
          },
          "429": {
            "description": "Rate limited."
          }
        }
      }
    },
    "/api/v1/stocks/screeners": {
      "get": {
        "summary": "Query stock-screeners",
        "security": [
          {
            "bearerApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "preview",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "preset",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "market",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sector",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "min_volume",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dataset response with data and meta."
          },
          "400": {
            "description": "Bad parameters."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "402": {
            "description": "Insufficient credits."
          },
          "429": {
            "description": "Rate limited."
          }
        }
      }
    },
    "/api/v1/fx-macro": {
      "get": {
        "summary": "Query fx-macro",
        "security": [
          {
            "bearerApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "preview",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "indicator",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "period",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dataset response with data and meta."
          },
          "400": {
            "description": "Bad parameters."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "402": {
            "description": "Insufficient credits."
          },
          "429": {
            "description": "Rate limited."
          }
        }
      }
    },
    "/api/v1/trends": {
      "get": {
        "summary": "Query trends",
        "security": [
          {
            "bearerApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "preview",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "keyword",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "period",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dataset response with data and meta."
          },
          "400": {
            "description": "Bad parameters."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "402": {
            "description": "Insufficient credits."
          },
          "429": {
            "description": "Rate limited."
          }
        }
      }
    },
    "/api/v1/tourism": {
      "get": {
        "summary": "Query tourism",
        "security": [
          {
            "bearerApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "preview",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "area",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dataset response with data and meta."
          },
          "400": {
            "description": "Bad parameters."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "402": {
            "description": "Insufficient credits."
          },
          "429": {
            "description": "Rate limited."
          }
        }
      }
    },
    "/api/v1/weather": {
      "get": {
        "summary": "Query weather",
        "security": [
          {
            "bearerApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "preview",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "city",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dataset response with data and meta."
          },
          "400": {
            "description": "Bad parameters."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "402": {
            "description": "Insufficient credits."
          },
          "429": {
            "description": "Rate limited."
          }
        }
      }
    }
  }
}