Introduction

Welcome to the January AI Enterprise API documentation. January AI offers a comprehensive suite of RESTful APIs that enable B2B partners to integrate advanced nutritional intelligence and metabolic health insights into their own platforms. January’s APIs are built on top of a proprietary food database enhanced by AI/ML for precision—covering 54 million verified items, including branded foods, common grocery items, and restaurant meals. These APIs support the most accurate logging, glucose prediction, and food intelligence tools on the market.

With January’s APIs, developers can:

🔍 Search: Access millions of curated food items by name, barcode, or via natural language (e.g., “milkshake with banana”).
📸 Scan: Use January’s market-leading vision model to analyze food photos for nutrient detection—with industry-best accuracy.
🍽️ Restaurant Search: Discover meals from local and chain restaurants based on name and location.
📝 Food Logging: Create, retrieve, and manage precise food logs for your users.
🧬 Glucose Predictions: Predict two-hour post-meal glucose curves using food intake, demographics, and health data—no sensor required.
🔄 Food Alternatives: Get healthy, semantically-similar food recommendations that respect dietary restrictions and preferences.
⏱️ Meal Time Detection: Detect eating events using CGM and heart rate data.

Authentication

import requests
import json

# Replace YOUR_API_KEY with your actual API key
api_key = 'YOUR_API_KEY'
headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

# With shell, you can just pass the correct header with each request
curl "https://partners.january.ai/v1.1/endpoint" \
  -H "Authorization: Bearer YOUR_API_KEY"

const axios = require('axios');

// Replace YOUR_API_KEY with your actual API key
const apiKey = 'YOUR_API_KEY';
const headers = {
  'Authorization': `Bearer ${apiKey}`,
  'Content-Type': 'application/json'
};

The January AI API uses bearer tokens for authentication. To obtain an API key, please send an email with your request.

The API key must be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer YOUR_API_KEY

You must replace YOUR_API_KEY with your personal API key.

Nutritional Intelligence APIs

The Nutritional Intelligence APIs provide comprehensive food search and analysis capabilities.

Food Search (By Name or Barcode)

import requests

url = 'https://partners.january.ai/v1.1/search/foods'
params = {
    'query': 'banana',
    'category': 'branded'
}
headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get(url, params=params, headers=headers)
print(response.json())

curl --location 'https://partners.january.ai/v1.1/search/foods?query=banana&category=branded' \
--header 'Authorization: Bearer YOUR_API_KEY'

const axios = require('axios');

const config = {
  method: 'get',
  url: 'https://partners.january.ai/v1.1/search/foods',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  params: {
    query: 'banana',
    category: 'branded'
  }
};

axios(config)
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.log(error);
  });

{
  "totalCount": 150,
  "items": [
    {
      "food": {
        "name": "Banana",
        "id": 123456,
        "brandName": "Dole",
        "nutrients": {
          "calories": {
            "value": 105,
            "unit": "kcal"
          },
          "carbs": {
            "value": 27,
            "unit": "g"
          },
          "fiber": {
            "value": 3.1,
            "unit": "g"
          }
        },
        "servings": [
          {
            "id": 78901,
            "quantity": 1,
            "unit": "medium banana"
          }
        ]
      }
    }
  ]
}

This endpoint allows clients to lookup foods by keyword and barcode across January’s 54 million-item, verified food database.

HTTP Request

GET https://partners.january.ai/v1.1/search/foods

Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication

Query Parameters

Parameter	Required	Description
query	Optional	The search term for food items
category	Optional	The category of food items to filter results ('branded' or 'general')
upc	Optional	The UPC representing the barcode of a food item

- Either query or upc must be provided.
- category defaults to 'general'

Response Structure

The response includes:

totalCount: Total number of matching food items
items: Array of food items with detailed nutritional information
food: Contains name, id, brandName, nutrients, and servings information

NLP Food Search

import requests

url = 'https://partners.january.ai/v1.1/search/foods/nlp'
params = {
    'query': '1 banana, 1 bowl of oatmeal, glass of orange juice'
}
headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get(url, params=params, headers=headers)
print(response.json())

curl --location 'https://partners.january.ai/v1.1/search/foods/nlp?query=1%20banana%2C%201%20bowl%20of%20oatmeal%2C%20glass%20of%20orange%20juice' \
--header 'Authorization: Bearer YOUR_API_KEY'

const axios = require('axios');

const config = {
  method: 'get',
  url: 'https://partners.january.ai/v1.1/search/foods/nlp',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  params: {
    query: '1 banana, 1 bowl of oatmeal, glass of orange juice'
  }
};

axios(config)
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.log(error);
  });

{
  "totalNutrients": {
    "calories": {
      "value": 435,
      "unit": "kcal"
    },
    "carbs": {
      "value": 92,
      "unit": "g"
    },
    "protein": {
      "value": 8.5,
      "unit": "g"
    }
  },
  "detections": [
    {
      "food": {
        "name": "Banana",
        "id": 123456,
        "brandName": null,
        "nutrients": {
          "calories": {
            "value": 105,
            "unit": "kcal"
          }
        },
        "servings": [
          {
            "id": 78901,
            "quantity": 1,
            "unit": "medium banana"
          }
        ]
      }
    }
  ]
}

This endpoint allows you to search for food items using natural language processing via common English text.

HTTP Request

GET https://partners.january.ai/v1.1/search/foods/nlp

Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication

Query Parameters

Parameter	Required	Description
query	Yes	The search term for food items in natural language

Response Structure

The response includes:

totalNutrients: Summary of total nutritional content
detections: Array of detected food items with detailed information

Photo Scan

import requests
import json

url = 'https://partners.january.ai/v1.1/vision/foods'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'x-partner-user-id': 'your-user-id'
}
data = {
    "photoUrl": "https://i.imgur.com/bTQIGxf.png"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

curl --location 'https://partners.january.ai/v1.1/vision/foods' \
--header 'Content-Type: application/json' \
--header 'x-partner-user-id: your-user-id' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
  "photoUrl": "https://i.imgur.com/bTQIGxf.png"
}'

const axios = require('axios');

const config = {
  method: 'post',
  url: 'https://partners.january.ai/v1.1/vision/foods',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'x-partner-user-id': 'your-user-id'
  },
  data: {
    photoUrl: 'https://i.imgur.com/bTQIGxf.png'
  }
};

axios(config)
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.log(error);
  });

{
  "mealName": "Breakfast Bowl",
  "totalNutrients": {
    "calories": {
      "value": 520,
      "unit": "kcal"
    },
    "carbs": {
      "value": 68,
      "unit": "g"
    },
    "protein": {
      "value": 15,
      "unit": "g"
    }
  },
  "detections": [
    {
      "confidenceScore": "high",
      "food": {
        "name": "Oatmeal",
        "id": 789012,
        "brandName": null,
        "nutrients": {
          "calories": {
            "value": 300,
            "unit": "kcal"
          }
        },
        "servings": [
          {
            "id": 45678,
            "quantity": 1,
            "unit": "cup"
          }
        ]
      }
    }
  ]
}

This endpoint allows you to scan a photo of a food item and retrieve nutritional information of foods in the photo.

HTTP Request

POST https://partners.january.ai/v1.1/vision/foods

Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication
Content-Type	Yes	Must be `application/json`
x-partner-user-id	Yes	Unique user ID from your system

Request Body

Parameter	Required	Description
photoUrl	Yes	The URL of the image to be analyzed
photoBase64	Optional	Base64 encoded image data (if not using photoUrl)

Photo Requirements

Must be at least 512x512 pixels in JPG or JPEG format
Maximum resolution: 1024x1024 pixels
Maximum file size: 4 MB
Must not include location or personal metadata
Must not be blurry or dark

Response Structure

The response includes:

mealName: Name of the meal identified in the image
totalNutrients: Summary of total nutritional content
detections: Array of detected food items with confidence scores

Restaurant Search

import requests

url = 'https://partners.january.ai/v1.1/search/restaurants'
params = {
    'query': 'mcdonalds',
    'limit': 50,
    'lat': 37.549,
    'lon': -121.989,
    'distance': 16093
}
headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get(url, params=params, headers=headers)
print(response.json())

curl --location 'https://partners.january.ai/v1.1/search/restaurants?query=mcdonalds&limit=50&lat=37.549&lon=-121.989' \
--header 'Authorization: Bearer YOUR_API_KEY'

const axios = require('axios');

const config = {
  method: 'get',
  url: 'https://partners.january.ai/v1.1/search/restaurants',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  params: {
    query: 'mcdonalds',
    limit: 50,
    lat: 37.549,
    lon: -121.989,
    distance: 16093
  }
};

axios(config)
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.log(error);
  });

{
  "items": [
    {
      "id": "53fc3b8a-e6bf-404d-83c8-9f42124d1bee",
      "name": "McDonald's",
      "is_chain": false,
      "distance": 8,
      "city": "San Francisco",
      "address1": "123 Main Street",
      "address2": "Suite 100"
    }
  ]
}

This endpoint allows you to search for restaurants (local and/or chain) by name.

HTTP Request

GET https://partners.january.ai/v1.1/search/restaurants

Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication

Query Parameters

Parameter	Required	Description
query	Yes	The search term related to the restaurant. Leave empty to return all nearest restaurants.
lat	Optional	Latitude coordinate for proximity search
lon	Optional	Longitude coordinate for proximity search
distance	Optional	Distance in meters to search for restaurants
limit	Optional	Maximum number of results to return

Response Structure

The response includes:

items: Array of restaurant locations with id, name, chain status, distance, and address information

import requests

url = 'https://partners.january.ai/v1.1/search/restaurants/menu'
params = {
    'query': 'burger',
    'limit': 50,
    'lat': 37.549,
    'lon': -121.989,
    'distance': 16093
}
headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get(url, params=params, headers=headers)
print(response.json())

curl --location 'https://partners.january.ai/v1.1/search/restaurants/menu?query=burger&lat=37.549&lon=-121.989' \
--header 'Authorization: Bearer YOUR_API_KEY'

const axios = require('axios');

const config = {
  method: 'get',
  url: 'https://partners.january.ai/v1.1/search/restaurants/menu',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  params: {
    query: 'burger',
    limit: 50,
    lat: 37.549,
    lon: -121.989,
    distance: 16093
  }
};

axios(config)
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.log(error);
  });

{
  "items": [
    {
      "type": "menu_item",
      "id": "228990954",
      "name": "burger",
      "restaurant_name": "morning due cafe",
      "is_chain": false,
      "data_source_id": 12,
      "source_original_id": "ngxZD7tEA1cQGCuOYBF05Ckft2ZP3z3Ja88wVaXYqqr7P7F3QiGFN1BSCl6H0Bt_5iN7y",
      "protein": 48,
      "energy": 800,
      "carbs": 40,
      "net_carbs": 38,
      "sugars": 6,
      "added_sugars": null,
      "fat": 45,
      "gi": 48.507698,
      "gl": 36.67089,
      "fiber": 2,
      "photo_url": "https://cdn-img.ai/23361362e6a706567",
      "servings": [
        {
          "id": 189343592,
          "scaling_factor": 1,
          "quantity": 1,
          "unit": "serving",
          "weight_grams": null,
          "is_primary": true
        }
      ],
      "distance": 124
    }
  ]
}

This endpoint allows you to search for restaurants (local and/or chain) by name.

HTTP Request

GET https://partners.january.ai/v1.1/search/restaurants/menu

Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication

Query Parameters

Parameter	Required	Description
query	Yes	The search term related to the menu.
lat	Yes	Latitude coordinate for proximity search
lon	Yes	Longitude coordinate for proximity search
distance	Optional	Distance in meters to search for restaurant menus
limit	Optional	Maximum number of results to return

Response Structure

The response includes:

items: Array of menu items with id, name, restaurant name, photo URL, nutrients and primary serving information

Food Logs APIs

The Food Logs APIs allow you to create, retrieve, and manage food logs for users.

Create Food Logs

import requests
import json

url = 'https://partners.january.ai/v1.1/logs/foods'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'x-partner-user-id': 'your-user-id'
}
data = {
    "foods": [
        {
            "id": 101963552,
            "serving": {
                "id": 68051535,
                "quantity": 1.4
            }
        }
    ],
    "timestampUtc": "2024-09-13T11:34:56Z"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

curl --location 'https://partners.january.ai/v1.1/logs/foods' \
--header 'Content-Type: application/json' \
--header 'x-partner-user-id: your-user-id' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
  "foods": [
    {
      "id": 101963552,
      "serving": {
        "id": 68051535,
        "quantity": 1.4
      }
    }
  ],
  "timestampUtc": "2024-09-13T11:34:56Z"
}'

const axios = require('axios');

const config = {
  method: 'post',
  url: 'https://partners.january.ai/v1.1/logs/foods',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'x-partner-user-id': 'your-user-id'
  },
  data: {
    foods: [
      {
        id: 101963552,
        serving: {
          id: 68051535,
          quantity: 1.4
        }
      }
    ],
    timestampUtc: "2024-09-13T11:34:56Z"
  }
};

axios(config)
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.log(error);
  });

This endpoint allows partners to log food items associated with a specific user.

HTTP Request

POST https://partners.january.ai/v1.1/logs/foods

Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication
Content-Type	Yes	Must be `application/json`
x-partner-user-id	Yes	Unique user ID from your system

Request Body

Parameter	Required	Description
foods	Yes	Array of food items to be logged
foods[].id	Yes	Unique identifier of the food item
foods[].serving	Yes	Serving details of the food item
foods[].serving.id	Yes	Serving size identifier
foods[].serving.quantity	Yes	Amount of the serving consumed
timestampUtc	Yes	UTC timestamp when food was consumed (YYYY-MM-DDTHH:MM:SSZ)
name	Optional	Name of the meal

Retrieve Food Logs

import requests

url = 'https://partners.january.ai/v1.1/logs/foods'
params = {
    'start': '2023-09-12',
    'end': '2024-09-15'
}
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'x-partner-user-id': 'your-user-id'
}

response = requests.get(url, params=params, headers=headers)
print(response.json())

curl --location 'https://partners.january.ai/v1.1/logs/foods?start=2023-09-12&end=2024-09-15' \
--header 'x-partner-user-id: your-user-id' \
--header 'Authorization: Bearer YOUR_API_KEY'

const axios = require('axios');

const config = {
  method: 'get',
  url: 'https://partners.january.ai/v1.1/logs/foods',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'x-partner-user-id': 'your-user-id'
  },
  params: {
    start: '2023-09-12',
    end: '2024-09-15'
  }
};

axios(config)
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.log(error);
  });

This endpoint allows you to retrieve food logs for a specific user over a defined date range.

HTTP Request

GET https://partners.january.ai/v1.1/logs/foods

Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication
x-partner-user-id	Yes	Unique user ID from your system

Query Parameters

Parameter	Required	Description
start	Yes	Start date (YYYY-MM-DD format)
end	Yes	End date (YYYY-MM-DD format)

Delete Food Log

import requests

url = 'https://partners.january.ai/v1.1/logs/foods/78129823-8ba2-4183-b13b-71f0e963c606'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'x-partner-user-id': 'user123'
}

response = requests.delete(url, headers=headers)
print(response.status_code)

curl --location --request DELETE 'https://partners.january.ai/v1.1/logs/foods/78129823-8ba2-4183-b13b-71f0e963c606' \
--header 'x-partner-user-id: user123' \
--header 'Authorization: Bearer YOUR_API_KEY'

const axios = require('axios');

const config = {
  method: 'delete',
  url: 'https://partners.january.ai/v1.1/logs/foods/78129823-8ba2-4183-b13b-71f0e963c606',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'x-partner-user-id': 'user123'
  }
};

axios(config)
  .then(response => {
    console.log(response.status);
  })
  .catch(error => {
    console.log(error);
  });

This endpoint allows you to delete a specific food log associated with a user.

HTTP Request

DELETE https://partners.january.ai/v1.1/logs/foods/{logId}

URL Parameters

Parameter	Description
logId	The unique identifier of the food log to delete

Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication
x-partner-user-id	Yes	Unique user ID from your system

Glucose Insights APIs

The Glucose Insights APIs provide advanced glucose response predictions and meal analysis capabilities.

Glucose Prediction

import requests
import json

url = 'https://partners.january.ai/v1.1/cgm/glucose-predict'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'x-partner-timezone': 'America/Los_Angeles'
}
data = {
    "userProfile": {
        "age": 25,
        "gender": "male",
        "height": 65,
        "weight": 165,
        "activityLevel": "very_active",
        "healthConditions": ["Type 2 diabetes"]
    },
    "startTime": "2025-04-09T19:06:12Z",
    "foods": [
        {
            "id": 70380652,
            "serving": {
                "id": 34176931,
                "quantity": 1
            }
        }
    ],
    "cgmData": [
        # Optional CGM data array
        {
            "timestamp": "2025-04-03T14:56:03Z",
            "value": 92
        },
        {
            "timestamp": "2025-04-03T14:59:40Z",
            "value": 95
        }
    ],
    "consumedFoods": [
        # Optional historical user foods
        {
            "timestamp": "2025-04-03T14:56:03Z",
            "id": 70380652,
            "serving": {
                "id": 34176931,
                "quantity": 1
            }
        }
    ]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

curl --location 'https://partners.january.ai/v1.1/cgm/glucose-predict' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'x-partner-timezone: America/Los_Angeles' \
--data '{
  "userProfile": {
    "age": 25,
    "gender": "male",
    "height": 65,
    "weight": 165,
    "activityLevel": "very_active",
    "healthConditions": ["Type 2 diabetes"]
  },
  "startTime": "2025-04-09T19:06:12Z",
  "foods": [
    {
      "id": 70380652,
      "serving": {
        "id": 34176931,
        "quantity": 1
      }
    }
  ],
  "cgmData": [
    {
      "timestamp": "2025-04-03T14:56:03Z",
      "value": 92
    },
    {
      "timestamp": "2025-04-03T14:59:40Z",
      "value": 95
    }
  ],
  "consumedFoods": [
    {
      "timestamp": "2025-04-03T14:56:03Z",
      "id": 70380652,
      "serving": {
          "id": 34176931,
          "quantity": 1
      }
    }
  ]
}'

const axios = require('axios');

const config = {
  method: 'post',
  url: 'https://partners.january.ai/v1.1/cgm/glucose-predict',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'x-partner-timezone': 'America/Los_Angeles'
  },
  data: {
    userProfile: {
      age: 25,
      gender: "male",
      height: 65,
      weight: 165,
      activityLevel: "very_active",
      healthConditions: ["Type 2 diabetes"]
    },
    startTime: "2025-04-09T19:06:12Z",
    foods: [
      {
        id: 70380652,
        serving: {
          id: 34176931,
          quantity: 1
        }
      }
    ],
    cgmData: [
        // Optional CGM data array
        {
            "timestamp": "2025-04-03T14:56:03Z",
            "value": 92
        }
    ],
    consumedFoods: [
        // Optional historical user foods
        {
            timestamp: "2025-04-03T14:56:03Z",
            id: 70380652,
            serving: {
                id: 34176931,
                quantity: 1
            }
        }
    ]
  }
};

axios(config)
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.log(error);
  });

{
  "curve": [
    [0, 95],
    [15, 110],
    [30, 140],
    [45, 155],
    [60, 145],
    [75, 125],
    [90, 110],
    [105, 100],
    [120, 95]
  ],
  "scoring": "medium_impact"
}

This endpoint provides two-hour glucose predictions for a user based on individual food or meal lookups. It optionally accepts user CGM data and comsumed foods for personal CGP AI training. If cgmData and consumedFoods are provided, they must contain enough data to complete AI training. AI training is completed if there are 5 or more training good days. A training day is good if it has at least 12 hours of CGM data and at least 2 logged meals at different time during the day.

HTTP Request

POST https://partners.january.ai/v1.1/cgm/glucose-predict

Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication
Content-Type	Yes	Must be `application/json`
x-partner-timezone	Yes	User local timezone (e.g. `America/New_York` or `US/Pacific`)

Request Body

Parameter	Required	Description
userProfile	Yes	User's profile data
userProfile.age	Yes	User's age
userProfile.gender	Yes	User's gender ('male' or 'female')
userProfile.height	Yes	User's height in inches
userProfile.weight	Yes	User's weight in pounds
userProfile.activityLevel	Yes	Activity level ('sedentary', 'lightly_active', 'moderately_active', 'very_active')
userProfile.healthConditions	Yes	Array of health conditions
foods	Yes	Array of foods and servings for prediction
foods[].id	Yes	Unique identifier of the food item
foods[].serving	Yes	Serving details
foods[].serving.id	Yes	Serving size identifier
foods[].serving.quantity	Yes	Amount of serving consumed
startTime	Yes	ISO 8601 timestamp for when foods are consumed
cgmData	No	CGM data array for AI training. Please provide at least one data point per 15 minutes. If `cgmData` is provided, `consumedFoods` must be provided also.
cgmData[].timestamp	Yes	ISO 8601 timestamp for the CGM data point
cgmData[].value	Yes	Blood sugar level (in mg/dL)
consumedFoods	No	Array of historical user foods and servings for AI training.
consumedFoods[].timestamp	Yes	ISO 8601 timestamp for when the food is consumed
consumedFoods[].id	Yes	Unique identifier of the food item
consumedFoods[].serving	Yes	Serving details
consumedFoods[].serving.id	Yes	Serving size identifier
consumedFoods[].serving.quantity	Yes	Amount of serving consumed

Health Conditions

Valid health conditions include:

Type 1 diabetes
Type 2 diabetes
Prediabetes
Gestational diabetes (prior pregnancy)
Latent autoimmune diabetes in adults (LADA)
Cystic-fibrosis related diabetes
Diabetes, but not sure which type
None of the above
Other

Response Structure

The response includes:

curve: Array of data points representing glucose response curve [minute, glucose_value]
scoring: Qualitative impact scoring ('low_impact', 'medium_impact', 'high_impact')

Food Alternatives

import requests
import json

url = 'https://partners.january.ai/v1.1/cgm/food-alternatives/5467772'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}
data = {
    "dietaryRestrictions": ["Gluten"],
    "dietaryPreferences": ["Vegan"]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

curl --location 'https://partners.january.ai/v1.1/cgm/food-alternatives/5467772' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
  "dietaryRestrictions": ["Gluten"],
  "dietaryPreferences": ["Vegan"]
}'

const axios = require('axios');

const config = {
  method: 'post',
  url: 'https://partners.january.ai/v1.1/cgm/food-alternatives/5467772',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  data: {
    dietaryRestrictions: ["Gluten"],
    dietaryPreferences: ["Vegan"]
  }
};

axios(config)
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.log(error);
  });

{
  "alternatives": [
    {
      "food": {
        "name": "Gluten-Free Oat Bread",
        "id": 9876543,
        "brandName": "Nature's Path",
        "nutrients": {
          "calories": {
            "value": 80,
            "unit": "kcal"
          },
          "carbs": {
            "value": 15,
            "unit": "g"
          }
        },
        "servings": [
          {
            "id": 12345,
            "quantity": 1,
            "unit": "slice"
          }
        ]
      }
    }
  ]
}

This endpoint allows you to see semantically similar healthy alternatives to individual food items.

HTTP Request

POST https://partners.january.ai/v1.1/cgm/food-alternatives/{foodId}

Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication
Content-Type	Yes	Must be `application/json`

URL Parameters

Parameter	Description
foodId	The unique identifier of the food item to find alternatives for

Request Body

Parameter	Required	Description
dietaryRestrictions	Yes	Array of dietary restrictions/allergies
dietaryPreferences	Yes	Array of dietary preferences

Dietary Restrictions

Valid dietary restrictions include:

Gluten
Lactose
Yeast
Tree nuts
Peanuts
Dairy
Eggs
Sulfites
Soy
Wheat
Shellfish
Fish
Mushrooms
Sesame
MSG
Caffeine
FODMAPs

Dietary Preferences

Valid dietary preferences include:

Vegetarian
Vegan
Keto
Paleo
Pescatarian
Low carbohydrate
High protein
Kosher

Food Detect

import requests
import json

url = 'https://partners.january.ai/v1.1/cgm/food-detect'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}
data = {
    "cgmData": {
        # CGM data structure
    },
    "hrData": {
        # Heart rate data structure
    }
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

curl --location 'https://partners.january.ai/v1.1/cgm/food-detect' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
  "cgmData": {},
  "hrData": {}
}'

const axios = require('axios');

const config = {
  method: 'post',
  url: 'https://partners.january.ai/v1.1/cgm/food-detect',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  data: {
    cgmData: {
      // CGM data structure
    },
    hrData: {
      // Heart rate data structure
    }
  }
};

axios(config)
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.log(error);
  });

{
  "mealTime": "2025-04-09T20:43:00Z"
}

This endpoint allows you to detect times at which a user consumed food based on CGM and Heart Rate data.

HTTP Request

POST https://partners.january.ai/v1.1/cgm/food-detect

Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication
Content-Type	Yes	Must be `application/json`

Request Body

Parameter	Required	Description
cgmData	Yes	CGM data object/array
hrData	Yes	Heart rate data object/array

Response Structure

The response includes:

mealTime: ISO 8601 timestamp for detected meals

Last-Meal Sleep Gap

import requests
import json

url = 'https://partners.january.ai/v1.1/cgm/sleep-gap'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}
data = {
    "cgmData": {
        # CGM data structure
    },
    "bedtime": "2025-04-09T23:00:00Z"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

curl --location 'https://partners.january.ai/v1.1/cgm/sleep-gap' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
  "cgmData": {},
  "bedtime": "2025-04-09T23:00:00Z"
}'

const axios = require('axios');

const config = {
  method: 'post',
  url: 'https://partners.january.ai/v1.1/cgm/sleep-gap',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  data: {
    cgmData: {
      // CGM data structure
    },
    bedtime: "2025-04-09T23:00:00Z"
  }
};

axios(config)
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.log(error);
  });

{
  "hoursSinceLastMeal": 3.5
}

This endpoint allows you to detect the number of hours between the final food a user consumes in a day and their time of sleep.

HTTP Request

POST https://partners.january.ai/v1.1/cgm/sleep-gap

Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication
Content-Type	Yes	Must be `application/json`

Request Body

Parameter	Required	Description
cgmData	Yes	CGM data object/array
bedtime	Yes	ISO 8601 timestamp indicating user's bedtime

Response Structure

The response includes:

hoursSinceLastMeal: Number of hours since the user last consumed a meal

Errors

The January AI API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid or malformed.
401	Unauthorized -- Your API key is invalid or missing.
403	Forbidden -- You don't have permission to access this resource.
404	Not Found -- The specified resource could not be found.
405	Method Not Allowed -- You tried to access a resource with an invalid HTTP method.
406	Not Acceptable -- You requested a format that isn't supported.
422	Unprocessable Entity -- The request was well-formed but contains semantic errors.
429	Too Many Requests -- You're making too many requests! Please slow down.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Error Response Format

{
  "error": {
    "code": 400,
    "message": "Bad Request",
    "details": "The 'query' parameter is required for this endpoint."
  }
}

All error responses follow a consistent format with an error object containing:

code: HTTP status code
message: Human-readable error message
details: Additional information about the error (when available)

Common Error Scenarios

Authentication Errors

401 Unauthorized: Missing or invalid API key
403 Forbidden: Valid API key but insufficient permissions

Request Errors

400 Bad Request: Missing required parameters or invalid parameter values
422 Unprocessable Entity: Valid request format but business logic errors
429 Too Many Requests: Rate limiting exceeded

Server Errors

500 Internal Server Error: Unexpected server-side error
503 Service Unavailable: Temporary service outage

Introduction

Authentication

Nutritional Intelligence APIs

Food Search (By Name or Barcode)

HTTP Request

Headers

Query Parameters

Response Structure

NLP Food Search

HTTP Request

Headers

Query Parameters

Response Structure

Photo Scan

HTTP Request

Headers

Request Body

Photo Requirements

Response Structure

Restaurant Search

HTTP Request

Headers

Query Parameters

Response Structure

Menu within a Restaurant Search

HTTP Request

Headers

Query Parameters

Response Structure

Food Logs APIs

Create Food Logs

HTTP Request

Headers

Request Body

Retrieve Food Logs

HTTP Request

Headers

Query Parameters

Delete Food Log

HTTP Request

URL Parameters

Headers

Glucose Insights APIs

Glucose Prediction

HTTP Request

Headers

Request Body

Health Conditions

Response Structure

Food Alternatives

HTTP Request

Headers

URL Parameters

Request Body

Dietary Restrictions

Dietary Preferences

Food Detect

HTTP Request

Headers

Request Body

Response Structure

Last-Meal Sleep Gap

HTTP Request

Headers

Request Body

Response Structure

Errors

Error Response Format

Common Error Scenarios

Authentication Errors

Request Errors

Server Errors