Ask the AI Coach for swap options

curl --request POST \
  --url https://sandbox.rx.tera.health/v1/patient/meal-plan/items/{item_id}/swap-options \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "reason": "I don't like fish",
  "avoid": [
    "fish"
  ]
}
EOF

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({reason: 'I don\'t like fish', avoid: ['fish']})
};

fetch('https://sandbox.rx.tera.health/v1/patient/meal-plan/items/{item_id}/swap-options', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://sandbox.rx.tera.health/v1/patient/meal-plan/items/{item_id}/swap-options"

payload = {
    "reason": "I don't like fish",
    "avoid": ["fish"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "item_id": "4d2f9a31-6c8b-4e0d-9f72-1b3c5d7e9f02",
  "options": [
    {
      "option_id": "opt_1",
      "title": "Chicken and quinoa bowl",
      "description": "Grilled chicken, quinoa, roasted vegetables",
      "protein_g": 38,
      "calories_kcal": 480,
      "details": {
        "prep_minutes": 25
      }
    },
    {
      "option_id": "opt_2",
      "title": "Tofu stir-fry with edamame",
      "description": "Firm tofu, edamame, broccoli and brown rice",
      "protein_g": 34,
      "calories_kcal": 460,
      "details": {
        "prep_minutes": 20
      }
    }
  ],
  "note": null,
  "expires_at": "2026-10-26T11:30:00Z"
}

Meal swap

Ask the AI Coach for swap options

The AI Coach proposes replacements for one meal and keeps only those that stay within the protocol’s targets and the brand’s rule matrix (allergies, foods to avoid, calorie floor). Takes a few seconds. Options expire after 30 minutes. Counts toward the plan’s daily AI Coach cap.

Error codes: ai_paused (409) when the AI Coach is paused for the plan, daily_message_cap_reached (429), ai_unavailable (503).

Plans: AI + health and fitness coaches (ai_health_fitness), AI only (ai_only).

POST

/

v1

/

patient

/

meal-plan

/

items

/

{item_id}

/

swap-options

Ask the AI Coach for swap options

curl --request POST \
  --url https://sandbox.rx.tera.health/v1/patient/meal-plan/items/{item_id}/swap-options \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "reason": "I don't like fish",
  "avoid": [
    "fish"
  ]
}
EOF

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({reason: 'I don\'t like fish', avoid: ['fish']})
};

fetch('https://sandbox.rx.tera.health/v1/patient/meal-plan/items/{item_id}/swap-options', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://sandbox.rx.tera.health/v1/patient/meal-plan/items/{item_id}/swap-options"

payload = {
    "reason": "I don't like fish",
    "avoid": ["fish"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "item_id": "4d2f9a31-6c8b-4e0d-9f72-1b3c5d7e9f02",
  "options": [
    {
      "option_id": "opt_1",
      "title": "Chicken and quinoa bowl",
      "description": "Grilled chicken, quinoa, roasted vegetables",
      "protein_g": 38,
      "calories_kcal": 480,
      "details": {
        "prep_minutes": 25
      }
    },
    {
      "option_id": "opt_2",
      "title": "Tofu stir-fry with edamame",
      "description": "Firm tofu, edamame, broccoli and brown rice",
      "protein_g": 34,
      "calories_kcal": 460,
      "details": {
        "prep_minutes": 20
      }
    }
  ],
  "note": null,
  "expires_at": "2026-10-26T11:30:00Z"
}

Authorizations

Authorization

string

header

default:Bearer sandbox_any_token_works

required

A 15-minute token bound to one patient and one enrollment, issued by POST /v1/oauth/token with the token-exchange grant. Treat it as opaque. When it expires, exchange a fresh assertion; there is no refresh token.

Headers

Idempotency-Key

string

Optional on this action. When sent, it works as on creating requests (24 hours, same body).

Required string length: 8 - 255

Path Parameters

item_id

string<uuid>

required

Body

application/json

reason

string

Why the patient wants a swap, in their words. The AI Coach uses it to choose options.

Maximum string length: 500

Example:

"I don't like fish"

avoid

string[]

Maximum array length: 20

Example:

["fish"]

Response

Options checked against the plan's constraints.

item_id

string<uuid>

required

Example:

"3c1e8f20-5b7a-4d9c-8e61-0a2b4c6d8e01"

options

object[]

required

Only options that keep the protocol's targets and the rule-matrix constraints (allergies, foods to avoid, calorie floor). Empty when none does; note then says why.

Show child attributes

expires_at

string<date-time>

required

ISO 8601 in UTC.

Example:

"2026-10-26T14:05:00Z"

note

string | null

Example:

null