API Documentation

key Authentication

DataBody uses Bearer token authentication. Include your token in the Authorization header:

Authorization: Bearer YOUR_TOKEN

Obtain a token by logging in via POST /api/v1/session or registering via POST /api/v1/registration.

OAuth 2.0: For third-party integrations, DataBody supports OAuth 2.0 with PKCE via Doorkeeper. See MCP documentation for details.

link Base URL

https://databody.app/api/v1

All API requests should be made to this base URL. Requests must include Content-Type: application/json for POST/PATCH requests.

error Error Handling

The API returns standard HTTP status codes:

Code	Description
`200`	Success
`201`	Created
`401`	Unauthorized - Invalid or missing token
`402`	Payment Required - Subscription needed for AI features
`404`	Not Found
`422`	Unprocessable Entity - Validation errors
`429`	Too Many Requests - Token limit exceeded

{
  "error": "Invalid email or password",
  "errors": ["Email address can't be blank"]
}

Register

POST /api/v1/registration

Create a new user account and receive an authentication token.

Request Body

Parameter	Type	Required	Description
`email_address`	string	Yes	User's email
`password`	string	Yes	Password (min 8 chars)
`password_confirmation`	string	Yes	Password confirmation
`height_cm`	number	No	Height in centimeters
`sex`	string	No	"male" or "female"
`birth_date`	string	No	YYYY-MM-DD format
`activity_level`	string	No	sedentary, light, moderate, active, very_active

Response

{
  "token": "abc123...",
  "user": {
    "id": 1,
    "email_address": "user@example.com",
    "height_cm": 175.5,
    "sex": "male",
    "activity_level": "moderate"
  }
}

Login

POST /api/v1/session

Authenticate and receive an access token.

Request Body

Parameter	Type	Description
`email_address`	string	User's email
`password`	string	User's password

Response

{
  "token": "abc123...",
  "user": {
    "id": 1,
    "email_address": "user@example.com"
  }
}

Logout

DELETE /api/v1/session

Invalidate the current access token.

Sign in with Apple

POST /api/v1/auth/apple

Authenticate using Apple identity token.

Request Body

`identity_token`	string	Apple ID token from Sign in with Apple
`user_identifier`	string	Apple user identifier
`email`	string	User email (first login only)
`full_name`	string	User's name (first login only)

Guest Users

POST /api/v1/guests

Create a guest account tied to a device. Returns existing guest if device already registered.

`device_id`	string	Required. Unique device identifier
`timezone`	string	Optional. User's timezone (e.g., "America/Los_Angeles")

POST /api/v1/guests/upgrade

Upgrade a guest account to a full account with email/password.

Get User Profile

GET /api/v1/users/me

Get the authenticated user's profile.

Response

{
  "id": 1,
  "email_address": "user@example.com",
  "name": "John Doe",
  "username": "johndoe",
  "height_cm": 180.0,
  "sex": "male",
  "age": 30,
  "activity_level": "moderate",
  "activity_multiplier": 1.55,
  "timezone": "America/New_York"
}

Update User Profile

PATCH /api/v1/users/me

Update profile fields like height, activity level, etc.

Request Body (all fields optional)

`name`	string	Display name
`username`	string	Unique username
`height_cm`	number	Height in cm
`sex`	string	"male" or "female"
`birth_date`	string	YYYY-MM-DD
`activity_level`	string	Activity level
`timezone`	string	IANA timezone

Delete Account

DELETE /api/v1/users/me

Initiate account deletion. Fails if user has active subscription (must cancel first). Data is scheduled for permanent deletion.

Sync Health Data

POST /api/v1/health_sync

Sync health snapshots and workouts from HealthKit or other sources.

Request Body

{
  "snapshots": [
    {
      "recorded_at": "2024-01-15",
      "weight_kg": 80.5,
      "body_fat_percentage": 20.0,
      "steps": 8000
    }
  ],
  "workouts": [
    {
      "healthkit_uuid": "uuid-123",
      "workout_type": "running",
      "started_at": "2024-01-15T10:00:00Z",
      "ended_at": "2024-01-15T11:00:00Z",
      "duration_minutes": 60,
      "calories_burned": 500
    }
  ]
}

Health Summary

GET /api/v1/health/summary

Get dashboard data including today's macros, body stats, weight trends, and recent workouts.

Response

{
  "today": {
    "calories": 1500,
    "protein": 120,
    "carbs": 150,
    "fat": 50
  },
  "latest_snapshot": {
    "weight_kg": 80.5,
    "body_fat_percentage": 20.0
  },
  "weight_trend": [...],
  "recent_workouts": [...],
  "subscription": {...}
}

Health History

GET /api/v1/health/history

Get health snapshots for a date range.

Query Parameters

`start_date`	YYYY-MM-DD
`end_date`	YYYY-MM-DD

Today's Nutrition

GET /api/v1/nutrition/today

Get today's nutrition logs with totals and remaining macros.

Response

{
  "logs": [...],
  "totals": {
    "calories": 1500,
    "protein": 120,
    "carbs": 150,
    "fat": 50
  },
  "remaining": {
    "calories": 500,
    "protein": 30
  }
}

Nutrition History

GET /api/v1/nutrition/history

Get nutrition logs for a date range. Up to 30 days of history.

Query Parameters

`start_date`	YYYY-MM-DD
`end_date`	YYYY-MM-DD

Log Meal

POST /api/v1/nutrition

Create a new nutrition log with food items.

Request Body

{
  "meal_type": "lunch",
  "logged_at": "2024-01-15T12:30:00Z",
  "caption": "Healthy lunch!",
  "visibility": "meal_public",
  "nutrition_items_attributes": [
    {
      "name": "Chicken Breast",
      "calories": 165,
      "protein_grams": 31,
      "carbs_grams": 0,
      "fat_grams": 3.6,
      "serving_quantity": 1.5
    }
  ]
}

meal_type: breakfast, lunch, dinner, snack
visibility: meal_private (default), meal_public

Add Item to Meal

POST /api/v1/nutrition/:id/items

Add a food item to an existing nutrition log.

`name`	string	Required
`calories`	number	Calories
`protein_grams`	number	Protein in grams
`carbs_grams`	number	Carbs in grams
`fat_grams`	number	Fat in grams
`serving_quantity`	number	Number of servings

Current Goal

GET /api/v1/goals/current

Get the user's active fitness goal with macro targets.

{
  "id": 1,
  "mode": "cut",
  "target_body_fat_percentage": 15.0,
  "daily_calorie_target": 2000,
  "daily_protein_grams": 180,
  "daily_carbs_grams": 200,
  "daily_fat_grams": 67,
  "strategy": "moderate",
  "active": true
}

Create Goal

POST /api/v1/goals

Create a new fitness goal. Supports both cut and bulk modes.

Cut Mode

`mode`	"cut"
`target_body_fat_percentage`	Target body fat %
`strategy`	conservative, moderate, aggressive

Bulk Mode

`mode`	"bulk"
`target_lean_mass_lbs`	Target lean mass in pounds
`weekly_weight_gain_percentage`	Weekly gain rate (e.g., 0.35)

Calculate Macros

POST /api/v1/goals/:id/calculate

Calculate macro targets based on current health data. Returns TDEE, deficit/surplus, and projected timeline.

Recent Workouts

GET /api/v1/workouts/recent

Get last 7 days of workouts with summary statistics.

{
  "workouts": [...],
  "summary": {
    "total_workouts": 5,
    "total_calories": 2500,
    "total_duration_minutes": 300
  }
}

Log Workout

POST /api/v1/workouts

Log a manual workout. Calories auto-estimated using MET values if not provided.

`workout_type`	running, cycling, strength_training, etc.
`started_at`	ISO 8601 timestamp
`ended_at`	ISO 8601 timestamp
`duration_minutes`	Duration in minutes
`calories_burned`	Optional. Auto-calculated if omitted

Search Foods

GET /api/v1/foods/search

Search food databases (FatSecret, USDA, OpenFoodFacts) for nutrition data.

`query`	Required. Search term (e.g., "chicken breast")
`source`	Optional. fatsecret, usda, openfoodfacts

{
  "query": "chicken",
  "source": "fatsecret",
  "results": [
    {
      "id": "1641",
      "name": "Chicken Breast",
      "calories": 165,
      "protein": 31,
      "carbs": 0,
      "fat": 3.6
    }
  ]
}

Barcode Lookup

GET /api/v1/foods/barcode/:barcode

Look up product by UPC/EAN barcode. Returns 404 if not found.

Favorites

GET /api/v1/foods/favorites

Get user's saved favorite foods.

POST /api/v1/foods/favorites

Add a food to favorites.

DELETE /api/v1/foods/favorites/:id

Remove food from favorites.

AI Chat

Subscription Required: AI endpoints require an active subscription or trial period.

POST /api/v1/ai/chat

Send a message to the AI coach. Returns complete response.

`message`	Required. User's message
`thread_id`	Optional. Chat thread ID for context

POST /api/v1/ai/chat_stream

Stream AI response using Server-Sent Events (SSE).

Analyze Photo

POST /api/v1/ai/analyze_photo

Analyze a food photo and estimate nutrition information.

Send image as base64 or multipart form data.

image Required. Base64 encoded image or file upload

Meal Suggestions

GET /api/v1/ai/suggestions

Get AI-generated meal suggestions based on remaining macros and preferences.

{
  "remaining_macros": {
    "calories": 800,
    "protein": 50
  },
  "suggestions": [
    {
      "name": "Grilled Salmon with Vegetables",
      "calories": 450,
      "protein": 35,
      "carbs": 20,
      "fat": 25
    }
  ]
}

Chat Threads

GET /api/v1/chat_threads

List all chat threads.

POST /api/v1/chat_threads

Create a new chat thread.

GET /api/v1/chat_threads/:id

Get thread with all messages.

Friend Feed

GET /api/v1/feed

Get public posts from followed users. Supports cursor-based pagination.

`limit`	Number of posts (default 20)
`cursor`	Pagination cursor from previous response

{
  "posts": [
    {
      "id": 1,
      "user": {"username": "friend"},
      "meal_type": "lunch",
      "items": [...],
      "photos": [{"url": "..."}],
      "reactions": {"heart": 5},
      "comments_count": 3
    }
  ],
  "next_cursor": "abc123"
}

Follows

GET /api/v1/follows/following

Get list of users you follow.

GET /api/v1/follows/followers

Get list of your followers.

POST /api/v1/follows

Send follow request. Params: user_id or username

DELETE /api/v1/follows/:user_id

Unfollow a user.

Reactions

POST /api/v1/feed/:post_id/reactions

Add reaction to a post. Params: emoji

DELETE /api/v1/feed/:post_id/reactions/:emoji

Remove your reaction from a post.

Grocery Lists

GET /api/v1/grocery_lists

Get all grocery lists. Filter by status (active, completed, archived).

GET /api/v1/grocery_lists/current

Get the most recent active list with items grouped by category.

Create Grocery List

POST /api/v1/grocery_lists

Create a new grocery list with optional store and budget.

`name`	Required. List name
`store`	Optional. Store name
`budget`	Optional. Budget amount

Grocery Items

POST /api/v1/grocery_lists/:id/grocery_items

Add item. Auto-categorized by AI (produce, dairy, meat, etc.).

POST /api/v1/grocery_lists/:list_id/grocery_items/:id/toggle

Toggle item completion status.

Recipes

GET /api/v1/recipes

List all your saved recipes.

[
  {
    "id": 1,
    "name": "Chicken Salad",
    "description": "A healthy salad",
    "servings": 4,
    "calories_per_serving": 250,
    "protein_per_serving": 30
  }
]

Create Recipe

POST /api/v1/recipes

Save a new recipe with nutrition info.

`name`	Required. Recipe name
`description`	Optional. Description
`servings`	Number of servings
`calories_per_serving`	Calories per serving
`protein_per_serving`	Protein in grams
`carbs_per_serving`	Carbs in grams
`fat_per_serving`	Fat in grams

Subscription Status

GET /api/v1/subscription

Get current subscription status, plan details, and AI availability.

{
  "status": "active",
  "plan": "pro_monthly",
  "provider": "app_store",
  "ai_available": true,
  "expires_at": "2024-02-15T00:00:00Z",
  "usage": {
    "tokens_used": 50000,
    "tokens_limit": 100000
  }
}

Verify Purchase

POST /api/v1/subscription/verify_app_store

Verify and activate an App Store subscription.

`original_transaction_id`	Required. Transaction ID from StoreKit
`product_id`	Required. Product identifier

POST /api/v1/subscription/restore

Restore purchases from App Store.