> ## 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.

# 오늘의 운세 조회

<Info>
  **v1 Enterprise API (Coming Soon)**

  이 엔드포인트는 Enterprise 버전에서 제공될 예정입니다.
  현재는 [v0 API](/api-reference/v0/overview)를 사용하세요.
</Info>

특정 프로필의 오늘 운세를 조회합니다. 오늘 생성된 운세가 없으면 자동으로 생성됩니다.

<Note>
  이 엔드포인트는 오늘의 운세를 간편하게 조회하기 위한 단축 API입니다. 운세가 없으면 `haiku` 모델로 자동 생성됩니다. 다른 모델을 사용하려면 [운세 생성](/api-reference/fortunes/create) 엔드포인트를 사용하세요.
</Note>

***

## Path 파라미터

<ParamField path="profile_id" type="string" required>
  운세를 조회할 프로필의 ID입니다. `prf_` 접두사로 시작합니다.
</ParamField>

***

## Query 파라미터

<ParamField query="auto_generate" type="boolean" default="true">
  오늘의 운세가 없을 때 자동으로 생성할지 여부입니다. `false`로 설정하면 운세가 없을 때 404를 반환합니다.
</ParamField>

<ParamField query="model" type="string" default="haiku">
  자동 생성 시 사용할 AI 모델입니다. `auto_generate`가 `true`일 때만 적용됩니다.
</ParamField>

***

## Response

### 성공

오늘의 운세 조회에 성공하면 Fortune 객체가 반환됩니다.

### 실패

| 상태 코드 | 에러 타입                  | 설명                                                |
| ----- | ---------------------- | ------------------------------------------------- |
| 401   | `authentication_error` | API 키가 유효하지 않음                                    |
| 404   | `not_found`            | 프로필을 찾을 수 없거나, `auto_generate=false`이고 오늘의 운세가 없음 |
| 429   | `rate_limited`         | 요청 한도 초과                                          |
| 503   | `service_unavailable`  | AI 모델 서비스 일시 불가 (자동 생성 시)                         |

***

## 요청 예시

<CodeGroup>
  ```bash cURL theme={null}
  # 기본 요청 (자동 생성 활성화)
  curl -X GET https://api.sajuapi.dev/v1/fortunes/daily/prf_abc123def456 \
    -H "X-API-Key: bs_live_xxx"

  # 자동 생성 비활성화
  curl -X GET "https://api.sajuapi.dev/v1/fortunes/daily/prf_abc123def456?auto_generate=false" \
    -H "X-API-Key: bs_live_xxx"

  # 자동 생성 시 sonnet 모델 사용
  curl -X GET "https://api.sajuapi.dev/v1/fortunes/daily/prf_abc123def456?model=sonnet" \
    -H "X-API-Key: bs_live_xxx"
  ```

  ```javascript JavaScript theme={null}
  // 기본 요청
  const response = await fetch(
    'https://api.sajuapi.dev/v1/fortunes/daily/prf_abc123def456',
    {
      headers: {
        'X-API-Key': 'bs_live_xxx'
      }
    }
  );

  const fortune = await response.json();

  // 자동 생성 비활성화
  const responseNoAuto = await fetch(
    'https://api.sajuapi.dev/v1/fortunes/daily/prf_abc123def456?auto_generate=false',
    {
      headers: {
        'X-API-Key': 'bs_live_xxx'
      }
    }
  );

  if (responseNoAuto.status === 404) {
    console.log('오늘의 운세가 아직 생성되지 않았습니다.');
  }
  ```

  ```python Python theme={null}
  import requests

  # 기본 요청
  response = requests.get(
      'https://api.sajuapi.dev/v1/fortunes/daily/prf_abc123def456',
      headers={'X-API-Key': 'bs_live_xxx'}
  )

  fortune = response.json()

  # 자동 생성 비활성화
  response_no_auto = requests.get(
      'https://api.sajuapi.dev/v1/fortunes/daily/prf_abc123def456',
      headers={'X-API-Key': 'bs_live_xxx'},
      params={'auto_generate': 'false'}
  )

  if response_no_auto.status_code == 404:
      print('오늘의 운세가 아직 생성되지 않았습니다.')
  ```
</CodeGroup>

***

## 응답 예시

```json theme={null}
{
  "id": "ftn_xyz789abc123",
  "profile_id": "prf_abc123def456",
  "fortune_type": "daily",
  "fortune_date": "2025-01-16",
  "model": "haiku",
  "score": 78,
  "summary": "오늘은 안정적인 하루가 예상됩니다. 급한 결정은 피하고 차분하게 하루를 보내세요.",
  "categories": {
    "overall": {
      "score": 78,
      "description": "무난한 하루가 예상됩니다."
    },
    "wealth": {
      "score": 70,
      "description": "재물운은 평범합니다."
    },
    "love": {
      "score": 82,
      "description": "가까운 사람과의 관계가 좋습니다."
    },
    "health": {
      "score": 75,
      "description": "충분한 휴식이 필요합니다."
    },
    "career": {
      "score": 80,
      "description": "업무가 순조롭게 진행됩니다."
    }
  },
  "lucky_items": {
    "number": 3,
    "color": "파랑",
    "direction": "동쪽",
    "time": "오전 10시-12시"
  },
  "advice": "오늘은 새로운 도전보다 기존 일에 집중하세요.",
  "cached": true,
  "generated_at": "2025-01-16T00:05:00Z"
}
```

***

## 자동 생성 동작

`auto_generate=true`(기본값)일 때:

1. 오늘 날짜의 운세가 이미 존재하면 캐시된 결과 반환
2. 운세가 없으면 지정된 모델로 새로 생성
3. 생성된 운세는 자동으로 저장되어 다음 요청 시 캐시됨

```
요청 → 오늘 운세 있음? → 있으면 반환
                    ↓
                 없으면
                    ↓
              운세 생성 (haiku)
                    ↓
                저장 후 반환
```

***

## 타임존

운세 날짜는 한국 표준시(KST, UTC+9) 기준입니다. 매일 자정(KST)에 새로운 날의 운세가 생성됩니다.

```
2025-01-16 00:00 KST = 2025-01-15 15:00 UTC
```