{
  "openapi": "3.1.0",
  "info": {
    "title": "Byul AI Financial Data API v2",
    "description": "Real-time financial news API providing global economic news and market updates",
    "version": "2.0.0",
    "contact": {
      "name": "Byul Support",
      "url": "https://www.byul.ai/contact"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://www.byul.ai/terms"
    }
  },
  "servers": [
    {
      "url": "https://api.byul.ai/api/v2",
      "description": "Production server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/news": {
      "get": {
        "summary": "Fetch",
        "description": "Retrieve the latest financial news articles with filtering and pagination support",
        "operationId": "fetchNews",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Number of articles to return",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 10
            },
            "example": 20
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Pagination cursor for next page",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "67850d7b0123456789abcde0"
          },
          {
            "name": "sinceId",
            "in": "query",
            "description": "Fetch articles after this ID",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "67850d7b0123456789abcdef"
          },
          {
            "name": "minImportance",
            "in": "query",
            "description": "Minimum importance level",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10,
              "default": 1
            },
            "example": 5
          },
          {
            "name": "q",
            "in": "query",
            "description": "Search query for filtering articles",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "tesla earnings"
          },
          {
            "name": "startDate",
            "in": "query",
            "description": "Start of date range (ISO 8601)",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2024-01-01T00:00:00.000Z"
          },
          {
            "name": "endDate",
            "in": "query",
            "description": "End of date range (ISO 8601)",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2024-01-31T23:59:59.999Z"
          },
          {
            "name": "symbol",
            "in": "query",
            "description": "Stock symbol filter",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "AAPL"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved news articles",
            "headers": {
              "X-V2-RateLimit-Limit": {
                "description": "Request limit per minute",
                "schema": {
                  "type": "integer"
                }
              },
              "X-V2-RateLimit-Remaining": {
                "description": "Requests remaining in current window",
                "schema": {
                  "type": "integer"
                }
              },
              "X-V2-RateLimit-Used": {
                "description": "Requests used in current window",
                "schema": {
                  "type": "integer"
                }
              },
              "X-V2-RateLimit-Reset": {
                "description": "Unix timestamp when rate limit resets",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NewsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - Invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - API key required or invalid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required - Plan expired",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - Feature not available on current plan",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests - Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "NewsResponse": {
        "type": "object",
        "required": ["items", "hasMore"],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/NewsArticle"
            },
            "description": "Array of news articles"
          },
          "nextCursor": {
            "type": "string",
            "nullable": true,
            "description": "Cursor for next page (only when hasMore is true, can be null)",
            "example": "67850d7b0123456789abcde0"
          },
          "hasMore": {
            "type": "boolean",
            "description": "Whether additional pages are available",
            "example": true
          }
        }
      },
      "NewsArticle": {
        "type": "object",
        "required": ["_id", "title", "url", "date", "createdAt", "source", "timestamp", "importanceScore", "category"],
        "properties": {
          "_id": {
            "type": "string",
            "description": "Unique article ID",
            "example": "67850d7b0123456789abcdef"
          },
          "title": {
            "type": "string",
            "description": "Article title (primary, usually English)",
            "example": "Tesla Stock Surges After Q4 Earnings Beat"
          },
          "koTitle": {
            "type": "string",
            "description": "Korean title (optional)",
            "example": "테슬라 4분기 실적 발표 후 주가 급등"
          },
          "content": {
            "type": "string",
            "description": "Article content or summary (optional)",
            "example": "Tesla Inc. reported stronger-than-expected Q4 2024 earnings, with revenue beating analyst estimates by 8%. The electric vehicle maker delivered 484,507 vehicles in Q4, up 15% year-over-year, driving shares up 12% in after-hours trading." 
          },
          "koContent": {
            "type": "string",
            "description": "Korean content or summary (optional)",
            "example": "테슬라가 2024년 4분기 실적에서 애널리스트 예상치를 8% 상회하는 매출을 기록했습니다. 이 전기차 제조업체는 4분기에 484,507대를 인도하며 전년 대비 15% 증가했고, 시간외 거래에서 주가가 12% 상승했습니다."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Original article URL",
            "example": "https://www.byul.ai/news/tesla-earnings-q4-2024"
          },
          "date": {
            "type": "string",
            "format": "date-time",
            "description": "Article date (ISO 8601 format)",
            "example": "2024-01-15T10:30:00.000Z"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "Creation time (ISO 8601 format)",
            "example": "2024-01-15T10:30:00.000Z"
          },
          "source": {
            "type": "string",
            "description": "News source name (always 'byul.ai')",
            "example": "byul.ai"
          },
          "timestamp": {
            "type": "integer",
            "description": "Unix timestamp",
            "example": 1705401000
          },
          "importanceScore": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10,
            "description": "Market importance (0-10, higher = more important)",
            "example": 8
          },
          "category": {
            "type": "string",
            "description": "News category",
            "example": "earnings"
          },
          "symbols": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Related stock symbols array (optional)",
            "example": ["TSLA"]
          },
          "sentiment": {
            "type": "string",
            "enum": ["positive", "negative", "neutral"],
            "description": "Sentiment analysis result (optional)",
            "example": "positive"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["statusCode", "message", "error", "timestamp", "path"],
        "properties": {
          "statusCode": {
            "type": "integer",
            "description": "HTTP status code",
            "example": 401
          },
          "message": {
            "type": "string",
            "description": "Error message",
            "example": "API key is required. Please provide a valid V2 API key in the X-API-Key header."
          },
          "error": {
            "type": "string",
            "description": "Error type",
            "example": "Unauthorized"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Error timestamp",
            "example": "2024-01-15T10:30:00.123Z"
          },
          "path": {
            "type": "string",
            "description": "API endpoint path",
            "example": "/api/v2/news"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "API key authentication. Get your API key from https://www.byul.ai/api/dashboard"
      }
    }
  }
}