# Public API

금융 데이터, 주가, 뉴스, 리서치 리포트에 액세스하기 위한 외부 API입니다.

## 인증

모든 Public API 엔드포인트는 API 키를 통한 인증이 필요합니다.

### API 키 발급

1. 계정에 로그인
2. 설정 > API 키로 이동
3. 필요한 스코프로 새 API 키 생성
4. 키를 안전하게 저장 (한 번만 표시됨)

### API 키 사용

`X-API-Key` 헤더에 API 키를 포함합니다:

```bash
curl -H "X-API-Key: ak_your_api_key_here" \
     https://api.alpha-lenz.com/api/public/v1/financial/companies
```

## 사용 가능한 스코프

| 스코프              | 설명                   |
| ---------------- | -------------------- |
| `read:all`       | 모든 API에 대한 전체 읽기 액세스 |
| `read:financial` | 금융 데이터 API 액세스       |
| `read:stock`     | 주가 API 액세스           |
| `read:news`      | 뉴스 API 액세스           |

## 요청 제한

기본 요청 제한: **시간당 1,000회 요청**

API 키별로 맞춤 요청 제한을 설정할 수 있습니다.

## Base URL

```
https://api.alpha-lenz.com/api/public/v1
```

## API 엔드포인트

### Basic Financial API (Twelve Data 스타일)

간단하고 직관적인 금융 데이터 액세스:

* `GET /api/v1/financial-v4/time-series` - 과거 OHLCV 가격 데이터
* `GET /api/v1/financial-v4/profile` - 기업 프로필 및 정보
* `GET /api/v1/financial-v4/fundamentals` - 재무 비율 및 지표

**참고:** Basic Financial API는 선택적 인증을 지원합니다 (trial 모드 사용 가능)

### Financial Data

* `GET /financial/companies` - 기업 목록 조회
* `GET /financial/companies/{symbol}` - 기업 상세 정보 조회
* `GET /financial/companies/{symbol}/financials` - 재무제표 조회

### Stock Prices

* `GET /stock/prices/{symbol}` - 현재 주가 조회
* `GET /stock/prices/{symbol}/history` - 과거 주가 조회

### News

* `GET /news/articles` - 뉴스 기사 목록 조회
* `GET /news/articles/{id}` - 기사 상세 정보 조회
* `GET /news/articles/{id}/content` - 전체 콘텐츠 조회

## 오류 응답

모든 오류는 다음 형식을 따릅니다:

```json
{
  "detail": "오류 메시지"
}
```

### 주요 상태 코드

| 코드  | 설명                |
| --- | ----------------- |
| 401 | API 키가 잘못되었거나 누락됨 |
| 403 | 권한 부족             |
| 404 | 리소스를 찾을 수 없음      |
| 429 | 요청 제한 초과          |
| 500 | 서버 오류             |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.alpha-lenz.com/ko/api-reference/public-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.