Skip to main content
GET
/
v1
/
fortunes
운세 목록 조회
curl --request GET \
  --url https://sajuapi.dev/v1/fortunes \
  --header 'X-API-Key: <api-key>'

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.

v1 Enterprise API (Coming Soon)이 엔드포인트는 Enterprise 버전에서 제공될 예정입니다. 현재는 v0 API를 사용하세요.
생성된 운세 목록을 조회합니다. 결과는 페이지네이션되어 반환되며, 다양한 필터를 적용할 수 있습니다.

​
Query 파라미터

​
profile_id
string
특정 프로필의 운세만 조회합니다.
​
fortune_type
string
운세 유형으로 필터링합니다. daily, yearly, monthly 중 하나입니다.
​
fortune_date
string
특정 날짜의 운세만 조회합니다. YYYY-MM-DD 형식입니다.
​
date_from
string
지정된 날짜 이후의 운세를 조회합니다. YYYY-MM-DD 형식입니다.
​
date_to
string
지정된 날짜 이전의 운세를 조회합니다. YYYY-MM-DD 형식입니다.
​
model
string
사용된 AI 모델로 필터링합니다.
​
limit
integer
default:"20"
한 페이지에 반환할 운세 수입니다. 1에서 100 사이의 값이어야 합니다.
​
cursor
string
다음 페이지를 조회하기 위한 커서입니다.

​
Response

​
성공

운세 목록 조회에 성공하면 운세 배열과 페이지네이션 정보가 반환됩니다.
필드타입설명
dataarrayFortune 객체 배열입니다.
has_moreboolean다음 페이지가 있는지 여부입니다.
next_cursorstring다음 페이지 조회를 위한 커서입니다.
total_countinteger필터 조건에 맞는 전체 운세 수입니다.

​
실패

상태 코드에러 타입설명
400validation_error쿼리 파라미터가 유효하지 않음
401authentication_errorAPI 키가 유효하지 않음
429rate_limited요청 한도 초과

​
요청 예시

curl -X GET "https://api.sajuapi.dev/v1/fortunes?profile_id=prf_abc123&fortune_type=daily&limit=10" \
  -H "X-API-Key: bs_live_xxx"

​
응답 예시

{
  "data": [
    {
      "id": "ftn_xyz789abc123",
      "profile_id": "prf_abc123def456",
      "fortune_type": "daily",
      "fortune_date": "2025-01-16",
      "model": "sonnet",
      "score": 85,
      "summary": "오늘은 새로운 기회가 찾아오는 날입니다.",
      "cached": false,
      "generated_at": "2025-01-16T09:00:00Z"
    },
    {
      "id": "ftn_abc123xyz789",
      "profile_id": "prf_abc123def456",
      "fortune_type": "daily",
      "fortune_date": "2025-01-15",
      "model": "haiku",
      "score": 72,
      "summary": "안정적인 하루가 예상됩니다.",
      "cached": true,
      "generated_at": "2025-01-15T09:00:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJpZCI6ImZ0bl9hYmMxMjN4eXo3ODkifQ==",
  "total_count": 45
}

​
날짜 범위 조회

특정 기간의 운세를 조회할 때 date_from과 date_to를 함께 사용합니다. 
// 최근 7일간의 운세 조회
const today = new Date();
const weekAgo = new Date(today);
weekAgo.setDate(weekAgo.getDate() - 7);

const params = new URLSearchParams({
  profile_id: 'prf_abc123',
  date_from: weekAgo.toISOString().split('T')[0],
  date_to: today.toISOString().split('T')[0]
});

const response = await fetch(`/v1/fortunes?${params}`, {
  headers: { 'X-API-Key': 'bs_live_xxx' }
});