> ## Documentation Index
> Fetch the complete documentation index at: https://docs.byul.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Byul REST API v2 reference documentation

## REST API

Byul REST API v2 provides access to financial news data through RESTful JSON endpoints.

**Base URL:** `https://api.byul.ai/api/v2`

## Features

* Financial news data access
* Importance scoring (1-10)
* Symbol-based filtering
* Cursor-based pagination
* Real-time updates
* Date range filtering (startDate/endDate)

## Authentication

Include your API key in the request header:

```http theme={null}
X-API-Key: byul_api_key
```

## Quick Example

```bash theme={null}
curl -X GET "https://api.byul.ai/api/v2/news?limit=5&minImportance=8" \
  -H "X-API-Key: byul_api_key"
```

```json theme={null}
{
  "items": [
    {
      "_id": "67850d7b0123456789abcdef",
      "title": "Federal Reserve Raises Interest Rates by 0.25%",
      "koTitle": "연준, 기준금리 0.25% 인상",
      "content": "The Federal Open Market Committee (FOMC) announced a 0.25 percentage point increase in the federal funds rate, citing continued economic growth and persistent inflation concerns. This marks the sixth rate hike this cycle.",
      "koContent": "연방공개시장위원회(FOMC)가 지속적인 경제 성장과 인플레이션 우려를 이유로 연방기금금리를 0.25%포인트 인상한다고 발표했습니다. 이는 현 사이클에서 여섯 번째 금리 인상입니다.",
      "url": "https://www.byul.ai/news/fed-rate-decision-2024",
      "date": "2024-01-15T14:00:00.000Z",
      "importanceScore": 9,
      "category": "central_banks",
      "symbols": ["DXY", "SPY"],
      "sentiment": "neutral"
    }
  ],
  "nextCursor": "67850d7b0123456789abcde0",
  "hasMore": true
}
```

## Endpoints

### GET /news

Retrieve financial news articles.

**Parameters:**

* `limit` (integer): Articles to return (1-100, default: 20)
* `minImportance` (integer): Minimum importance score (1-10, default: 1)
* `symbol` (string): Filter by stock symbol
* `q` (string): Search query
* `cursor` (string): Pagination cursor
* `category` (string): News category filter
* `startDate` (string): Start of date range (ISO 8601)
* `endDate` (string): End of date range (ISO 8601)

## Rate Limits

| Plan        | Rate Limit          |
| ----------- | ------------------- |
| Test (Free) | 30 requests/minute  |
| Starter     | 60 requests/minute  |
| Pro         | 120 requests/minute |
| Enterprise  | Custom              |

**Headers:**

* `X-V2-RateLimit-Limit`
* `X-V2-RateLimit-Remaining`
* `X-V2-RateLimit-Used`
* `X-V2-RateLimit-Reset`

## Response Format

**Article Object:**

* `_id`: Unique article identifier
* `title`: Article title
* `url`: Source URL
* `date`: Publication date (ISO 8601)
* `importanceScore`: Market importance (1-10)
* `category`: News category
* `symbols`: Associated stock symbols (array)
* `sentiment`: Sentiment analysis result
* `content`: Article content or summary (optional; may be absent)
* `koContent`: Korean content or summary (optional; may be absent)

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" href="/rest-api/quickstart">
    Get started with REST API requests
  </Card>

  <Card title="Examples" href="/rest-api/examples/nodejs">
    Code examples in multiple languages
  </Card>

  <Card title="Authentication" href="/rest-api/authentication">
    API key setup and security
  </Card>

  <Card title="Error Handling" href="/rest-api/error-handling">
    Handle API errors and status codes
  </Card>
</CardGroup>