> For the complete documentation index, see [llms.txt](https://docs.alpha-lenz.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.alpha-lenz.com/ko/api-reference/public-api.md).

# 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 | 서버 오류             |