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

# API 개요

> 사주 API 전체 레퍼런스

## 기본 URL

모든 API 요청은 다음 주소로 보내야 합니다:

```
https://api.sajuapi.dev
```

## 엔드포인트

| 메서드  | 엔드포인트                       | 설명            |
| ---- | --------------------------- | ------------- |
| POST | `/api/daily-fortune`        | 개인화된 일일 운세 조회 |
| POST | `/api/daily-fortune-stream` | SSE로 운세 스트리밍  |
| POST | `/api/saju`                 | 생년월일로 사주 계산   |

## 요청 형식

모든 요청은 다음 조건을 충족해야 합니다:

* `POST` 메서드 사용
* `Content-Type: application/json` 헤더 포함
* `X-API-Key` 헤더에 API 키 포함
* JSON 본문 전송

```bash theme={null}
curl -X POST https://api.sajuapi.dev/api/daily-fortune \
  -H "Content-Type: application/json" \
  -H "X-API-Key: bs_live_xxx" \
  -d '{"saju": {...}, "userName": "홍길동"}'
```

## 응답 형식

모든 응답은 다음 구조를 따릅니다:

### 성공 응답

```json theme={null}
{
  "success": true,
  "data": {
    // 엔드포인트별 데이터
  },
  "meta": {
    "requestId": "req_abc123",
    "model": "haiku",
    "cached": true,
    "cost": 0.013,
    "latency": 1234
  }
}
```

### 에러 응답

```json theme={null}
{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "사람이 읽을 수 있는 에러 메시지",
    "hint": "에러 수정을 위한 제안",
    "field": "saju.pillars.day"  // 선택: 에러가 발생한 특정 필드
  },
  "meta": {
    "requestId": "req_abc123"
  }
}
```

## 공통 파라미터

### 사주 객체

`saju` 파라미터는 운세 엔드포인트에 필수이며 사주팔자를 포함해야 합니다:

```typescript theme={null}
interface Saju {
  pillars: {
    year: Pillar;
    month: Pillar;
    day: Pillar;
    hour: Pillar;  // 출생 시간을 모르면 null 가능
  };
  dayMaster?: {
    element: 'wood' | 'fire' | 'earth' | 'metal' | 'water';
    name: string;  // 예: "병화"
  };
}

interface Pillar {
  stem: {
    hangul: string;  // 예: "갑", "을", "병"...
    hanja?: string;  // 예: "甲", "乙", "丙"...
  };
  branch: {
    hangul: string;  // 예: "자", "축", "인"...
    hanja?: string;
  };
}
```

### 모델 선택

운세 생성을 위한 AI 모델 선택:

| 모델            | 파라미터     | 속도   | 품질    | 비용      |
| ------------- | -------- | ---- | ----- | ------- |
| Claude Haiku  | `haiku`  | \~2초 | 좋음    | \$0.013 |
| Claude Sonnet | `sonnet` | \~5초 | 우수    | \$0.031 |
| GPT-4o        | `gpt4o`  | \~4초 | 매우 좋음 | \$0.025 |

```json theme={null}
{
  "saju": {...},
  "userName": "홍길동",
  "model": "haiku"
}
```

## 응답 타입

### 운세 타입

`type` 파라미터로 특정 운세 타입을 요청합니다:

| 타입             | 설명       | 함수 호출 횟수        |
| -------------- | -------- | --------------- |
| `all` (기본값)    | 전체 운세 분석 | 3 (성격, 성향, 운세)  |
| `fortune_only` | 일일 운세만   | 1               |
| `character`    | 성격 분석만   | 1               |
| `compare`      | 모든 모델 비교 | 9 (3 함수 × 3 모델) |

<Warning>
  `compare` 타입은 9번의 API 호출을 하며 비용이 3배입니다. 신중하게 사용하세요.
</Warning>

## 페이지네이션

목록을 반환하는 엔드포인트는 페이지네이션을 지원합니다:

```json theme={null}
{
  "page": 1,
  "limit": 20,
  "sort": "createdAt",
  "order": "desc"
}
```

응답에 페이지네이션 메타데이터가 포함됩니다:

```json theme={null}
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}
```

## 버전 관리

API는 URL 경로를 통해 버전 관리됩니다. 현재 버전: **v1** (기본값)

```
https://api.sajuapi.dev/v1/api/daily-fortune
```

<Note>
  `/v1` 접두사는 선택 사항입니다. 버전 접두사가 없는 요청은 최신 안정 버전을 사용합니다.
</Note>