Key Concepts

This page introduces the core domain concepts and API design patterns that underpin the athlete-nutrition-ai API. Understanding these concepts will help you model your requests correctly, interpret responses, and build integrations that align with how the API thinks about athletes, nutrition, and training. Whether you're setting up a profile for the first time or automating shopping list generation, the abstractions described here appear throughout every workflow.

Athletes and Profiles

At the center of the API is the athlete profile — a structured representation of a person's physical attributes, dietary preferences, and nutritional goals. Every resource in the API is scoped to an athlete profile, meaning you must create a profile before you can use any other endpoint. The profile stores data that the AI uses as persistent context, including macronutrient targets, food intolerances, preferred cuisines, and body composition metrics.

An athlete can have one active profile at a time. You update the profile over time as the athlete's goals or preferences change, and the AI automatically incorporates those changes the next time it generates a meal plan or shopping list.

Training Events and the Calendar

The API models an athlete's schedule as a training calendar containing one or more training events. Each event describes a future workout or competition: its type (for example, long run, strength session, or race), its date and time, and its estimated intensity and duration.

The AI uses upcoming training events as the primary signal for generating nutrition plans. A heavy training block triggers higher carbohydrate and calorie recommendations; a rest day shifts the balance toward recovery-oriented nutrients. Because of this, the accuracy of your nutrition output is directly tied to the completeness and accuracy of the events you provide.

You connect a training calendar by either pushing events directly to the /events endpoint or by configuring a third-party calendar integration. Events can be created, updated, or deleted at any time, and meal plans regenerated accordingly.

Meal Plans

A meal plan is the AI's primary output. It is a structured document that maps specific meals — breakfast, lunch, dinner, and snacks — to each day in a requested time window, typically one to seven days ahead. Each meal includes dish names, portion sizes, and macronutrient breakdowns.

Meal plans are generated on demand; the API does not automatically create or refresh them. When you call the meal plan generation endpoint, the AI reads the athlete's current profile and all training events within the requested window and produces a tailored plan. You can regenerate a plan as many times as needed — for example, if the athlete's preferences change or a training event is added.

Meal plans are immutable once returned. If you need a different plan, you request a new one. This design makes it straightforward to store or display plans without worrying about unexpected mutations.

The AI Nutrition Advisor

The AI nutrition advisor is a conversational interface available via the /chat endpoint. It allows athletes or the applications you build to ask open-ended nutrition questions in natural language: "What should I eat the night before my marathon?" or "Can you suggest a high-protein breakfast that avoids dairy?"

The advisor operates within the context of the authenticated athlete's profile and upcoming events, so its answers are personalized rather than generic. Chat sessions are stateful within a session ID — the AI remembers earlier messages in the same session, enabling follow-up questions and clarifications. Sessions expire after a period of inactivity.

The chat endpoint is not a substitute for the meal plan generation endpoint. It is best used for exploratory questions, one-off suggestions, and explanations, while the meal plan endpoint is better suited for structured, schedulable output.

Shopping Lists

A shopping list is derived from one or more meal plans. When you request a shopping list, the API aggregates the ingredients required across all meals in the specified plans, deduplicates overlapping items, and normalizes quantities into practical purchase units (for example, combining "100g spinach" and "50g spinach" into "150g spinach").

Shopping lists are always linked to a specific meal plan or date range, so you can regenerate them if the underlying meal plan changes. The list is returned as a structured array of items, making it easy to render in a UI, export to a grocery app, or process programmatically.

Authentication and Resource Ownership

The API uses Bearer token authentication. You obtain a token by authenticating via the /auth/signin endpoint. Every subsequent request must include this token in the Authorization header.

All resources — profiles, events, meal plans, shopping lists, and chat sessions — are owned by the authenticated account. You cannot access another account's resources with your token. This ownership model is enforced at the API layer, and attempting to access a resource that does not belong to your account returns a 403 Forbidden error.

Subscriptions and Rate Limits

Access to AI-powered features — meal plan generation, the nutrition advisor, and shopping list creation — is gated by the account's subscription tier. Profile management and calendar operations are available on all tiers. If a request requires a higher subscription tier than your account holds, the API returns a 402 Payment Required error with a message indicating the required tier.

Each tier also carries rate limits on AI-intensive endpoints to ensure fair usage. Rate limit status is communicated through standard response headers so your application can back off gracefully before hitting a hard limit.

Error Handling Conventions

The API uses standard HTTP status codes consistently:

• 400 Bad Request — your request body failed validation; the response body includes field-level error details.
• 401 Unauthorized — your token is missing or expired.
• 402 Payment Required — the requested feature requires a higher subscription tier.
• 403 Forbidden — your token is valid but you do not own the requested resource.
• 404 Not Found — the requested resource does not exist.
• 422 Unprocessable Entity — the request was structurally valid but the AI could not fulfill it given the current profile or event data.
• 429 Too Many Requests — you have exceeded the rate limit for this endpoint.
• 500 Internal Server Error — an unexpected server-side error occurred.

Error responses always include a JSON body with a code field (a machine-readable string) and a message field (a human-readable explanation), making it straightforward to handle errors programmatically and surface meaningful feedback to your users.

Athlete profile object

When you fetch an athlete profile, the response body follows this shape. Notice that dietary preferences and physical metrics live together in a single resource — the AI reads both when generating plans.

GET /v1/profiles/me
Authorization: Bearer <your_token>

{
  "id": "prof_01HXYZ123",
  "display_name": "Jordan Silva",
  "body_weight_kg": 72.5,
  "primary_sport": "triathlon",
  "dietary_preferences": {
    "style": "omnivore",
    "intolerances": ["gluten"],
    "preferred_cuisines": ["mediterranean", "japanese"]
  },
  "macro_targets": {
    "calories": 2800,
    "protein_g": 160,
    "carbohydrate_g": 340,
    "fat_g": 85
  },
  "created_at": "2024-03-10T09:15:00Z",
  "updated_at": "2024-06-01T14:30:00Z"
}

Training event object

A single training event representing a long run two days from now. The intensity and duration_minutes fields are the primary inputs the AI uses to modulate calorie and carbohydrate recommendations for surrounding meals.

POST /v1/events
Authorization: Bearer <your_token>
Content-Type: application/json

{
  "type": "long_run",
  "scheduled_at": "2024-06-15T07:00:00Z",
  "duration_minutes": 120,
  "intensity": "high"
}

Response (201 Created):

{
  "id": "evt_02HABC456",
  "type": "long_run",
  "scheduled_at": "2024-06-15T07:00:00Z",
  "duration_minutes": 120,
  "intensity": "high",
  "created_at": "2024-06-13T10:00:00Z"
}

Error response

If you request meal plan generation without an active subscription, the API returns the following. Your application should check for 402 and redirect the user to the subscription upgrade flow.

HTTP/1.1 402 Payment Required

{
  "code": "subscription_required",
  "message": "Meal plan generation requires a Pro or Elite subscription. Your current tier is Free."
}

• Authentication — Detailed walkthrough of obtaining and refreshing Bearer tokens, including token expiry behavior.
• Athlete Profile API reference — Full field definitions and validation rules for the profile resource.
• Training Events API reference — Supported event types, intensity levels, and calendar integration options.
• Meal Plan generation — How to request, interpret, and store generated meal plans.
• AI Nutrition Advisor (Chat) — Session lifecycle, context limits, and best practices for prompting the advisor.
• Shopping Lists — Aggregation logic, unit normalization, and export formats.
• Subscriptions and rate limits — Tier comparison, rate limit headers, and upgrade flow.