새 확언 API

새 확언 API

무한 루프에서 즉각적인 웰니스로: 확언 API가 마찰 없는 개인화된 매일의 긍정을 전달하도록 새롭게 만들어졌습니다. 이제 모든 확언은 안정적인 ID, 깔끔하게 정리된 데이터, 풍부한 스키마와 함께 제공되며, 검색, 페이지네이션, 배치 및 일일 엔드포인트, 완전한 웰니스 툴킷, SMS와 음성 비서를 위한 일반 텍스트 응답까지 갖추었습니다.

🚀 새로운 기능

  • 안정적인 ID – 모든 확언은 일관된 해시 기반 id를 가지므로 위젯, 알림, 캐시가 항상 동기화 상태를 유지합니다.
  • 자동으로 깔끔해지는 데이터 – 텍스트와 카테고리 필드는 앱에 도달하기 전에 불필요한 공백이 제거됩니다.
  • 똑똑한 카테고리 – 19개 카테고리는 데이터셋에서 직접 도출되어 정렬되며, 하드코딩된 불일치가 없습니다.
  • 친절한 오류 – 알 수 없는 카테고리는 멈추거나 반복되지 않고 명확한 404를 반환합니다.
  • 더 풍부해진 스키마 – 각 확언은 id, text, category, mood, lang, length를 반환합니다.
  • 필요한 것을 바로 찾기 – 목록 엔드포인트의 검색과 페이지네이션, 그리고 설정 가능한 배치 엔드포인트.
  • 결정론적 일일 추천 – /today는 모든 사용자에게 동일한 오늘의 확언을 반환합니다.
  • 웰니스 툴킷 – 이름으로 개인화하고, 부정적인 생각을 재구성하며, 확언을 호흡 운동과 함께 사용할 수 있습니다.

🛠 API 엔드포인트

1. 확언 목록

GET /v1/affirmations

파라미터:

  • category (선택): confidence, self-love 같은 카테고리로 목록을 필터링합니다.
  • search (선택): 확언 텍스트 전체에서 전문 검색합니다.
  • page (기본값: 1): 페이지네이션을 위한 페이지 번호입니다.
  • limit (기본값: 10): 페이지당 결과 수이며, 최대 50까지 가능합니다.
  • lang (기본값: en): 언어 코드입니다. 이번 릴리스에서는 영어 콘텐츠가 반환됩니다.

2. 랜덤 확언

GET /v1/affirmations/random

파라미터:

  • category (선택): 특정 카테고리에서 랜덤 확언을 반환합니다.
  • lang (기본값: en): 언어 코드입니다. 이번 릴리스에서는 영어 콘텐츠가 반환됩니다.
  • format (기본값: json): 전체 객체에는 json, 일반 텍스트 응답에는 text를 사용하세요.

3. 카테고리별 랜덤 확언

GET /v1/affirmations/categories/{category}/random

파라미터:

  • category (필수): 선택할 카테고리입니다. 예: sleep. 알 수 없는 카테고리는 명확한 404를 반환합니다.

4. 카테고리 목록

GET /v1/affirmations/categories

정렬된 전체 카테고리 목록을 반환합니다. anxiety-relief와 calm부터 confidence, focus, gratitude, parenting, resilience, self-love, sleep, success 등까지 아우릅니다.

5. 배치 확언

GET /v1/affirmations/batch

파라미터:

  • category (선택): 카테고리별로 배치를 필터링합니다.
  • limit (기본값: 10): 반환할 확언 수이며, 최대 50까지 가능합니다.
  • lang (기본값: en): 언어 코드입니다. 이번 릴리스에서는 영어 콘텐츠가 반환됩니다.

6. 오늘의 확언

GET /v1/affirmations/today

파라미터:

  • category (선택): 카테고리 내에서 결정론적인 일일 추천을 반환합니다.
  • lang (기본값: en): 언어 코드입니다. 이번 릴리스에서는 영어 콘텐츠가 반환됩니다.

/daily 별칭은 동일한 오늘의 확언을 반환합니다.

7. 개인화

POST /v1/affirmations/personalize

요청 본문:

  • mood (선택): 참조할 기분 또는 카테고리입니다. 예: confidence. 기본값은 happiness입니다.
  • goal (선택): 확언에 담을 의도입니다.
  • name (선택): 확언에 녹여낼 이름입니다. 예: “I am confident, Ava.”

8. 부정적인 생각 재구성

POST /v1/affirmations/reframe

요청 본문:

  • negativeThought (필수): 재구성할 생각입니다. 예: “I always fail”.

재구성된 문장과 함께 어울리는 resilience 확언을 반환합니다.

9. 확언 + 호흡 번들

GET /v1/affirmations/bundle

파라미터:

  • category (선택): 참조할 카테고리입니다. sleep 카테고리는 4-7-8 호흡 운동을 반환하고, 그 밖의 모든 카테고리는 박스 호흡을 반환합니다.

10. 추천 스케줄

GET /v1/affirmations/schedule

파라미터:

  • timezone (선택): 추천 시간대를 위한 타임존 라벨입니다. 예: Europe/Berlin. 기본값은 UTC입니다.

📦 응답 예시

랜덤 확언:

{
  "id": 1874329517,
  "text": "I am confident, capable, and ready for today.",
  "category": "confidence",
  "mood": "confidence",
  "lang": "en",
  "length": 42
}

개인화된 확언:

{
  "id": 55123874,
  "text": "I am confident, Ava.",
  "category": "confidence",
  "mood": "confidence",
  "lang": "en",
  "length": 20
}

재구성된 생각:

{
  "reframe": "Even though \"I always fail\", I choose to believe: I am learning and growing every day.",
  "affirmation": {
    "id": 912345678,
    "text": "I am learning and growing every day.",
    "category": "resilience",
    "mood": "resilience",
    "lang": "en",
    "length": 36
  }
}

웰니스 번들:

{
  "affirmation": {
    "id": 44556677,
    "text": "I release the day and welcome rest.",
    "category": "sleep",
    "mood": "sleep",
    "lang": "en",
    "length": 36
  },
  "breathing": {
    "name": "4-7-8",
    "steps": ["Inhale 4s", "Hold 7s", "Exhale 8s"]
  }
}

추천 스케줄:

{
  "morning": "08:00 Europe/Berlin",
  "evening": "21:00 Europe/Berlin",
  "timezone": "Europe/Berlin"
}

✨ 다양한 형식의 응답

랜덤 엔드포인트는 JSON과 일반 텍스트를 모두 지원합니다. 웹과 모바일 앱에서는 구조화된 전체 객체를 위해 ?format=json(기본값)을 사용하고, SMS 흐름이나 음성 비서, 위젯에서는 바로 전송할 수 있는 문자열을 위해 ?format=text를 사용하세요.

🎯 이런 분들을 위해 만들었습니다

  • 개발자 – 안정적이고 문서화가 잘 된 API를 원하며 웰니스 앱, 챗봇, 동기 부여 기능을 만드는 분.
  • 프로덕트 매니저 – 일일 알림, 연속 기록, 결정론적인 일일 콘텐츠로 참여도를 높이려는 분.
  • 웰니스 앱 제작자 – 대규모로 신뢰할 수 있는 카테고리별 확언 콘텐츠가 필요한 분.
  • 엔터프라이즈 팀 – Postman으로 바로 시작할 수 있는 확장 가능한 SDK 스타일 엔드포인트를 기대하는 팀.

🌟 왜 확언 API를 선택해야 할까요?

  • 설계부터 믿을 수 있게: 안정적인 ID, 정리된 데이터, 명확한 404 덕분에 운영 환경에서 예상치 못한 일이 줄어듭니다.
  • 필요할 때 깊이 있게: 불안 완화부터 자기애까지 아우르는 19개 카테고리.
  • 단일 호출 그 이상: 개인화, 재구성, 호흡 번들, 스케줄링을 하나의 API에서.
  • 개발자 친화적: 검색, 페이지네이션, 배치, 다양한 형식의 응답, 바로 쓸 수 있는 스니펫.
  • 웰니스에 최적화: 일상의 긍정적인 순간을 위한 99.99% 업타임과 낮은 지연 시간의 응답.

🚀 시작하기

  • Postman 컬렉션: docs/affirmations-postman.json을 가져와 클릭 한 번으로 모든 엔드포인트를 살펴보세요.
  • 코드 스니펫: docs/affirmations-snippets.md에서 cURL, JavaScript, Python용 바로 실행 가능한 예제를 복사하세요.
  • LLM 지원: docs/llms.txt가 AI 에이전트에게 API의 구조화된 요약을 제공합니다.

오늘 바로 긍정적인 순간을 만들어 보세요 — today 엔드포인트를 호출해 결정론적인 일일 확언을 받은 다음, 개인화와 호흡 번들을 더해 완성된 웰니스 경험을 만들 수 있습니다.