新しいAffirmations API

新しいAffirmations API

無限ループから即座のウェルネスへ。Affirmations 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): 1ページあたりの結果数。最大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呼吸エクササイズを返し、それ以外のすべてのカテゴリはbox呼吸を返します。

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"
}

✨ マルチフォーマットのレスポンス

randomエンドポイントはJSONとプレーンテキストの両方に対応します。Webアプリやモバイルアプリで完全な構造化オブジェクトを取得するには?format=json(デフォルト)を、SMSフロー、音声アシスタント、ウィジェットですぐに送信できる文字列には?format=textを使用してください。

🎯 こんな方のために

  • 開発者: 安定した、十分に文書化されたAPIを求める、ウェルネスアプリ、チャットボット、モチベーション機能を構築する方。
  • プロダクトマネージャー: 毎日の通知、ストリーク、決定的なデイリーコンテンツでエンゲージメントを高めたい方。
  • ウェルネスアプリの制作者: 大規模に信頼できる、カテゴリ分けされたアファメーションコンテンツを必要とする方。
  • エンタープライズチーム: Postman対応のオンボーディングを備えた、スケーラブルでSDKスタイルのエンドポイントを期待する方。

🌟 なぜAffirmations APIを選ぶのか?

  • 設計からして信頼できる: 安定したID、整えられたデータ、明確な404が、本番環境での予期せぬ事態を減らします。
  • 必要なときに深みを: anxiety reliefからself-loveまで幅広くカバーする19のカテゴリ。
  • 1回の呼び出し以上の価値: パーソナライズ、リフレーミング、呼吸バンドル、スケジューリングを1つのAPIで。
  • 開発者に優しい: 検索、ページネーション、バッチ処理、マルチフォーマットのレスポンス、すぐに使えるスニペット。
  • ウェルネス対応: 99.99%の稼働率と、日々のポジティブな瞬間のための低レイテンシなレスポンス。

🚀 はじめよう

  • Postmanコレクション: docs/affirmations-postman.jsonをインポートして、ワンクリックですべてのエンドポイントを試せます。
  • コードスニペット: docs/affirmations-snippets.mdから、cURL、JavaScript、Pythonのすぐに実行できるサンプルをコピーできます。
  • LLM対応: docs/llms.txtが、AIエージェントにAPIの構造化された概要を提供します。

今日からポジティブな瞬間づくりを始めましょう — todayエンドポイントを呼び出して決定的なデイリーアファメーションを取得し、パーソナライズと呼吸バンドルを加えてウェルネス体験を完成させましょう。