Foods

Search the January food database, power type-ahead results, look up barcodes, fetch a food's full details and servings, and suggest healthier alternatives.

Each operation's description states what it costs — see Credits and pricing.

Search foods by name

get

API key or client token.

Costs 2 credits per successful call.

Full-text search over the January food database, returning up to 50 ranked matches per call. Generic foods, branded products and recipes are searched together unless type narrows it to one; page deeper with offset. To look up a scanned barcode, use GET /v1.2/foods/barcode/{barcode} instead.

Callable with a client token carrying the foods:read scope.

Authorizations

AuthorizationstringRequired

Your credential, sent as Authorization: Bearer <credential>. Two kinds reach this API, and the prefix tells them apart.

API key (sk-…) — created in the Developer Dashboard, it authenticates your whole account. Use it only where you control the machine — never inside a mobile app or a browser. Every endpoint accepts it.

Client token (ct-…) — a short-lived credential bound to one of your end users, minted from your API key by POST /v1.2/auth/client-tokens on your backend and relayed to the device. Safe to hold on a phone: it expires within 2 hours and acts only as the user it was minted for. Endpoints that open with API key or client token accept one and name the scope it must carry; endpoints that open with API key only refuse it.

Query parameters

querystring · max: 256Required

The food name to search for.

Example: greek yogurt

typestring · enumOptional

Narrows results to one kind of food. Omitted, all three are searched and returned as one ranked list, so a partner who does not care which kind a match is does not have to ask three times.

Possible values:

limitinteger · min: 1 · max: 50Optional

Maximum number of results to return in one call. Values above 50 are treated as 50, so page by 50 if you asked for more.

Default: 10

offsetintegerOptional

Number of results to skip, for paging: a page shorter than limit is the last one.

Default: 0

Responses

200

Foods matching the query, best match first; empty when nothing matches or offset is past the last result.

application/json

400

A parameter is missing or invalid; the message names the parameter and the accepted values.

application/json

401

The request carried no Authorization header, or the credential in it was rejected.

unauthorized — the header is missing or malformed, or the key is not one we recognise. A valid key belonging to the other API version is 403 forbidden instead.

A client token is rejected in one of three ways, and only the first should be handled automatically:

• token_expired — the token is past its TTL. Mint a fresh one from your backend and retry the request once. This is routine and expected once per TTL window.
• token_invalid — no such token: it was never issued, or it has been purged, which happens shortly after it expires. This code is not an automatic token-refresh signal.
• token_revoked — the token was revoked, by POST /v1.2/auth/client-token-revocations or from the dashboard. The end user signs in again in your app, and your backend decides whether to mint another; a device that just re-mints defeats the revocation.

application/json

403

The credential is valid but is not allowed to make this request. forbidden is the general case — a key issued for the other API version, for example. A client token adds client_token_not_allowed, meaning the endpoint takes only an sk- API key — its description opens with API key only. (in this API: POST /v1.2/auth/client-tokens, POST /v1.2/auth/client-token-revocations, POST /v1.2/chat/completions, POST /v1.2/literature/search, POST /v1.2/extractions, GET /v1.2/extractions/{job_id}, GET /v1.2/patients/{patient_id}/snapshot, and GET /v1.2/credits).

On an endpoint that opens with API key or client token., scope_insufficient means the token was minted without the scope named at the end of that endpoint’s description.

application/json

429

Two failures share this status; use code to choose the response.

• rate_limited — a rolling abuse window was reached: the partner-wide v1.2 minute cap, a configured short-window limit, or a client-token limit. Back off and retry; Retry-After carries the wait when Redis reports it.
• credit_limit_exceeded — this call costs more credits than you have left for the billing period, or they are spent. Never returned to an Enterprise account, whose usage past the allowance is billed as overage instead.

Credits reset at the end of your billing period; GET /v1.2/credits reports that instant as resets_at and remains available when either limit refuses other operations.

application/json

default

Any other error: the HTTP status plus { code, message }. Retry only rate_limited and the transient 5xx codes.

application/json

get/v1.2/foods

GET /v1.2/foods?query=greek+yogurt HTTP/1.1
Host: partners.january.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "101963552",
      "type": "branded",
      "name": "Dipped Banana Bites",
      "brand_name": "Banana",
      "nutrients": {
        "calories": {
          "value": 300,
          "unit": "g"
        },
        "protein": {
          "value": 300,
          "unit": "g"
        },
        "carbohydrates": {
          "value": 300,
          "unit": "g"
        },
        "net_carbohydrates": {
          "value": 300,
          "unit": "g"
        },
        "total_fat": {
          "value": 300,
          "unit": "g"
        },
        "trans_fat": {
          "value": 300,
          "unit": "g"
        },
        "saturated_fat": {
          "value": 300,
          "unit": "g"
        },
        "fiber": {
          "value": 300,
          "unit": "g"
        },
        "total_sugars": {
          "value": 300,
          "unit": "g"
        },
        "added_sugars": {
          "value": 300,
          "unit": "g"
        },
        "cholesterol": {
          "value": 300,
          "unit": "g"
        },
        "calcium": {
          "value": 300,
          "unit": "g"
        },
        "iron": {
          "value": 300,
          "unit": "g"
        },
        "potassium": {
          "value": 300,
          "unit": "g"
        },
        "sodium": {
          "value": 300,
          "unit": "g"
        },
        "vitamin_d": {
          "value": 300,
          "unit": "g"
        }
      },
      "glycemic_index": 1,
      "glycemic_load": 1,
      "image_url": "text",
      "barcode": "049000006346",
      "servings": [
        {
          "id": "68051535",
          "quantity": 1,
          "unit": "oz",
          "scaling_factor": 1,
          "weight_grams": 28,
          "is_primary": true
        }
      ]
    }
  ]
}

Autocomplete food names

get

API key or client token.

Free up to your plan's free-call limit, then 1 credit per 100 calls.

Lightweight food suggestions for a partial name, built for type-ahead ("ban" → banana, banana bread, …): generic foods first, then branded, each with its id, name, brand, a thumbnail and calories. Once the user picks one, fetch GET /v1.2/foods/{food_id} for servings and full nutrition. items is empty for fewer than 2 letters or digits, no match, or a search-index error (the suggestion service fails open so a typing user is not interrupted); an unreachable service still answers with the standard 502/504.

Callable with a client token carrying the foods:read scope.

Authorizations

AuthorizationstringRequired

Your credential, sent as Authorization: Bearer <credential>. Two kinds reach this API, and the prefix tells them apart.

API key (sk-…) — created in the Developer Dashboard, it authenticates your whole account. Use it only where you control the machine — never inside a mobile app or a browser. Every endpoint accepts it.

Client token (ct-…) — a short-lived credential bound to one of your end users, minted from your API key by POST /v1.2/auth/client-tokens on your backend and relayed to the device. Safe to hold on a phone: it expires within 2 hours and acts only as the user it was minted for. Endpoints that open with API key or client token accept one and name the scope it must carry; endpoints that open with API key only refuse it.

Query parameters

querystring · max: 64Required

The characters the user has typed so far. Fewer than 2 letters or digits yield no suggestions.

Example: ban

typestring · enumOptional

Narrows suggestions to one kind of food. Omitted, generic and branded foods are suggested together, generic first.

Possible values:

limitinteger · min: 1 · max: 20Optional

Maximum number of suggestions to return.

Default: 8

Responses

200

Type-ahead suggestions for the partial name, generic before branded; empty when fewer than 2 characters were given or nothing matches.

application/json

400

A parameter is missing or invalid; the message names the parameter and the accepted values.

application/json

401

The request carried no Authorization header, or the credential in it was rejected.

unauthorized — the header is missing or malformed, or the key is not one we recognise. A valid key belonging to the other API version is 403 forbidden instead.

A client token is rejected in one of three ways, and only the first should be handled automatically:

• token_expired — the token is past its TTL. Mint a fresh one from your backend and retry the request once. This is routine and expected once per TTL window.
• token_invalid — no such token: it was never issued, or it has been purged, which happens shortly after it expires. This code is not an automatic token-refresh signal.
• token_revoked — the token was revoked, by POST /v1.2/auth/client-token-revocations or from the dashboard. The end user signs in again in your app, and your backend decides whether to mint another; a device that just re-mints defeats the revocation.

application/json

403

The credential is valid but is not allowed to make this request. forbidden is the general case — a key issued for the other API version, for example. A client token adds client_token_not_allowed, meaning the endpoint takes only an sk- API key — its description opens with API key only. (in this API: POST /v1.2/auth/client-tokens, POST /v1.2/auth/client-token-revocations, POST /v1.2/chat/completions, POST /v1.2/literature/search, POST /v1.2/extractions, GET /v1.2/extractions/{job_id}, GET /v1.2/patients/{patient_id}/snapshot, and GET /v1.2/credits).

On an endpoint that opens with API key or client token., scope_insufficient means the token was minted without the scope named at the end of that endpoint’s description.

application/json

429

Two failures share this status; use code to choose the response.

• rate_limited — a rolling abuse window was reached: the partner-wide v1.2 minute cap, a configured short-window limit, or a client-token limit. Back off and retry; Retry-After carries the wait when Redis reports it.
• credit_limit_exceeded — this call costs more credits than you have left for the billing period, or they are spent. Never returned to an Enterprise account, whose usage past the allowance is billed as overage instead.

Credits reset at the end of your billing period; GET /v1.2/credits reports that instant as resets_at and remains available when either limit refuses other operations.

application/json

default

Any other error: the HTTP status plus { code, message }. Retry only rate_limited and the transient 5xx codes.

application/json

get/v1.2/foods/autocomplete

GET /v1.2/foods/autocomplete?query=ban HTTP/1.1
Host: partners.january.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "70376053",
      "type": "generic",
      "name": "greek yogurt",
      "brand_name": "Chobani",
      "image_url": "text",
      "nutrients": {
        "calories": {
          "value": 300,
          "unit": "g"
        },
        "protein": {
          "value": 300,
          "unit": "g"
        },
        "carbohydrates": {
          "value": 300,
          "unit": "g"
        },
        "net_carbohydrates": {
          "value": 300,
          "unit": "g"
        },
        "total_fat": {
          "value": 300,
          "unit": "g"
        },
        "trans_fat": {
          "value": 300,
          "unit": "g"
        },
        "saturated_fat": {
          "value": 300,
          "unit": "g"
        },
        "fiber": {
          "value": 300,
          "unit": "g"
        },
        "total_sugars": {
          "value": 300,
          "unit": "g"
        },
        "added_sugars": {
          "value": 300,
          "unit": "g"
        },
        "cholesterol": {
          "value": 300,
          "unit": "g"
        },
        "calcium": {
          "value": 300,
          "unit": "g"
        },
        "iron": {
          "value": 300,
          "unit": "g"
        },
        "potassium": {
          "value": 300,
          "unit": "g"
        },
        "sodium": {
          "value": 300,
          "unit": "g"
        },
        "vitamin_d": {
          "value": 300,
          "unit": "g"
        }
      }
    }
  ]
}

Barcode coverage is US-only. The database holds products sold in the United States, keyed by their UPC-A and EAN codes. Barcodes issued elsewhere — for example the GS1 prefixes 73 (Sweden), 64 (Finland), 54 (Belgium and Luxembourg), and 93 (Australia) — are not covered and return 404 not_found. Treat that 404 as "not covered" rather than retrying: fall back to text search (GET /v1.2/foods) or your own product data for those markets.

Look up a food by barcode

get

API key or client token.

Costs 2 credits per successful call.

Exact lookup of the food a barcode names — one food, not a list. The barcode on the returned food is the database's normalized form and may differ from the digits you scanned in leading zeros, so display it rather than comparing it. For free-text search, use GET /v1.2/foods instead.

Callable with a client token carrying the foods:read scope.

Authorizations

AuthorizationstringRequired

Your credential, sent as Authorization: Bearer <credential>. Two kinds reach this API, and the prefix tells them apart.

API key (sk-…) — created in the Developer Dashboard, it authenticates your whole account. Use it only where you control the machine — never inside a mobile app or a browser. Every endpoint accepts it.

Client token (ct-…) — a short-lived credential bound to one of your end users, minted from your API key by POST /v1.2/auth/client-tokens on your backend and relayed to the device. Safe to hold on a phone: it expires within 2 hours and acts only as the user it was minted for. Endpoints that open with API key or client token accept one and name the scope it must carry; endpoints that open with API key only refuse it.

Path parameters

barcodestringRequired

The numeric barcode: 6 to 14 digits (UPC-E, UPC-A, EAN-8, EAN-13 or GTIN-14). The example is a Coca-Cola can.

Example: 049000006346Pattern: ^[0-9]{6,14}$

Responses

200

The single food the barcode identifies.

application/json

idstringRequired

Opaque id — pass it back verbatim to log, predict, or fetch this food.

Example: 101963552Pattern: ^[1-9]\d{0,9}$

typestring · enumRequired

What kind of food this is: generic for a database staple ("banana"), branded for a packaged product, recipe for a multi-ingredient dish.

Example: brandedPossible values:

namestring · nullableRequired

Null only when the database has no name for the row.

Example: Dipped Banana Bites

brand_namestring · nullableRequired

null for generic foods and recipes, which have no brand.

Example: Banana

glycemic_indexnumber · nullableRequired

Glycemic index; null when the database has none for this food.

glycemic_loadnumber · nullableRequired

Glycemic load; null when the database has none for this food.

image_urlstring · nullableRequired

URL of a picture of the food; null when the database has none.

barcodestring · nullableRequired

The product's barcode; null for foods that have none. Named for the code rather than one of its encodings — the same field carries a UPC, an EAN or a GTIN. It is the database's normalized form, so it may differ from the digits you scanned in leading zeros: display it, do not string-compare it.

Example: 049000006346

400

The barcode is not a 6 to 14 digit number.

application/json

401

The request carried no Authorization header, or the credential in it was rejected.

unauthorized — the header is missing or malformed, or the key is not one we recognise. A valid key belonging to the other API version is 403 forbidden instead.

A client token is rejected in one of three ways, and only the first should be handled automatically:

• token_expired — the token is past its TTL. Mint a fresh one from your backend and retry the request once. This is routine and expected once per TTL window.
• token_invalid — no such token: it was never issued, or it has been purged, which happens shortly after it expires. This code is not an automatic token-refresh signal.
• token_revoked — the token was revoked, by POST /v1.2/auth/client-token-revocations or from the dashboard. The end user signs in again in your app, and your backend decides whether to mint another; a device that just re-mints defeats the revocation.

application/json

403

The credential is valid but is not allowed to make this request. forbidden is the general case — a key issued for the other API version, for example. A client token adds client_token_not_allowed, meaning the endpoint takes only an sk- API key — its description opens with API key only. (in this API: POST /v1.2/auth/client-tokens, POST /v1.2/auth/client-token-revocations, POST /v1.2/chat/completions, POST /v1.2/literature/search, POST /v1.2/extractions, GET /v1.2/extractions/{job_id}, GET /v1.2/patients/{patient_id}/snapshot, and GET /v1.2/credits).

On an endpoint that opens with API key or client token., scope_insufficient means the token was minted without the scope named at the end of that endpoint’s description.

application/json

404

No food matches this barcode.

application/json

429

Two failures share this status; use code to choose the response.

• rate_limited — a rolling abuse window was reached: the partner-wide v1.2 minute cap, a configured short-window limit, or a client-token limit. Back off and retry; Retry-After carries the wait when Redis reports it.
• credit_limit_exceeded — this call costs more credits than you have left for the billing period, or they are spent. Never returned to an Enterprise account, whose usage past the allowance is billed as overage instead.

Credits reset at the end of your billing period; GET /v1.2/credits reports that instant as resets_at and remains available when either limit refuses other operations.

application/json

default

Any other error: the HTTP status plus { code, message }. Retry only rate_limited and the transient 5xx codes.

application/json

get/v1.2/foods/barcode/{barcode}

GET /v1.2/foods/barcode/{barcode} HTTP/1.1
Host: partners.january.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "101963552",
  "type": "branded",
  "name": "Dipped Banana Bites",
  "brand_name": "Banana",
  "nutrients": {
    "calories": {
      "value": 300,
      "unit": "g"
    },
    "protein": {
      "value": 300,
      "unit": "g"
    },
    "carbohydrates": {
      "value": 300,
      "unit": "g"
    },
    "net_carbohydrates": {
      "value": 300,
      "unit": "g"
    },
    "total_fat": {
      "value": 300,
      "unit": "g"
    },
    "trans_fat": {
      "value": 300,
      "unit": "g"
    },
    "saturated_fat": {
      "value": 300,
      "unit": "g"
    },
    "fiber": {
      "value": 300,
      "unit": "g"
    },
    "total_sugars": {
      "value": 300,
      "unit": "g"
    },
    "added_sugars": {
      "value": 300,
      "unit": "g"
    },
    "cholesterol": {
      "value": 300,
      "unit": "g"
    },
    "calcium": {
      "value": 300,
      "unit": "g"
    },
    "iron": {
      "value": 300,
      "unit": "g"
    },
    "potassium": {
      "value": 300,
      "unit": "g"
    },
    "sodium": {
      "value": 300,
      "unit": "g"
    },
    "vitamin_d": {
      "value": 300,
      "unit": "g"
    }
  },
  "glycemic_index": 1,
  "glycemic_load": 1,
  "image_url": "text",
  "barcode": "049000006346",
  "servings": [
    {
      "id": "68051535",
      "quantity": 1,
      "unit": "oz",
      "scaling_factor": 1,
      "weight_grams": 28,
      "is_primary": true
    }
  ]
}

Get a food

get

API key or client token.

Costs 1 credit per successful call.

One food's full record — most importantly the complete list of serving sizes. Search, barcode, and food-analysis results carry a single default serving; fetch the food here to let an end user pick "1 cup" vs "100 g" vs "1 medium" when logging or predicting. Nutrition is per the default serving, in the shared nutrient vocabulary.

Callable with a client token carrying the foods:read scope.

Authorizations

AuthorizationstringRequired

Your credential, sent as Authorization: Bearer <credential>. Two kinds reach this API, and the prefix tells them apart.

API key (sk-…) — created in the Developer Dashboard, it authenticates your whole account. Use it only where you control the machine — never inside a mobile app or a browser. Every endpoint accepts it.

Client token (ct-…) — a short-lived credential bound to one of your end users, minted from your API key by POST /v1.2/auth/client-tokens on your backend and relayed to the device. Safe to hold on a phone: it expires within 2 hours and acts only as the user it was minted for. Endpoints that open with API key or client token accept one and name the scope it must carry; endpoints that open with API key only refuse it.

Path parameters

food_idstringRequired

Food id from a search or food-analysis result.

Example: 101963552Pattern: ^[1-9]\d{0,9}$

Responses

200

The food's full record, including the complete list of serving sizes.

application/json

idstringRequired

Opaque id — pass it back verbatim to log, predict, or fetch this food.

Example: 101963552Pattern: ^[1-9]\d{0,9}$

typestring · enumRequired

What kind of food this is: generic for a database staple ("banana"), branded for a packaged product, recipe for a multi-ingredient dish.

Example: brandedPossible values:

namestring · nullableRequired

Null only when the database has no name for the row.

Example: Dipped Banana Bites

brand_namestring · nullableRequired

null for generic foods and recipes, which have no brand.

Example: Banana

glycemic_indexnumber · nullableRequired

Glycemic index; null when the database has none for this food.

glycemic_loadnumber · nullableRequired

Glycemic load; null when the database has none for this food.

image_urlstring · nullableRequired

URL of a picture of the food; null when the database has none.

barcodestring · nullableRequired

The product's barcode; null for foods that have none. Named for the code rather than one of its encodings — the same field carries a UPC, an EAN or a GTIN. It is the database's normalized form, so it may differ from the digits you scanned in leading zeros: display it, do not string-compare it.

Example: 049000006346

400

food_id is not a numeric id; the message shows the expected form.

application/json

401

The request carried no Authorization header, or the credential in it was rejected.

unauthorized — the header is missing or malformed, or the key is not one we recognise. A valid key belonging to the other API version is 403 forbidden instead.

A client token is rejected in one of three ways, and only the first should be handled automatically:

• token_expired — the token is past its TTL. Mint a fresh one from your backend and retry the request once. This is routine and expected once per TTL window.
• token_invalid — no such token: it was never issued, or it has been purged, which happens shortly after it expires. This code is not an automatic token-refresh signal.
• token_revoked — the token was revoked, by POST /v1.2/auth/client-token-revocations or from the dashboard. The end user signs in again in your app, and your backend decides whether to mint another; a device that just re-mints defeats the revocation.

application/json

403

The credential is valid but is not allowed to make this request. forbidden is the general case — a key issued for the other API version, for example. A client token adds client_token_not_allowed, meaning the endpoint takes only an sk- API key — its description opens with API key only. (in this API: POST /v1.2/auth/client-tokens, POST /v1.2/auth/client-token-revocations, POST /v1.2/chat/completions, POST /v1.2/literature/search, POST /v1.2/extractions, GET /v1.2/extractions/{job_id}, GET /v1.2/patients/{patient_id}/snapshot, and GET /v1.2/credits).

On an endpoint that opens with API key or client token., scope_insufficient means the token was minted without the scope named at the end of that endpoint’s description.

application/json

404

No food with this id.

application/json

429

Two failures share this status; use code to choose the response.

• rate_limited — a rolling abuse window was reached: the partner-wide v1.2 minute cap, a configured short-window limit, or a client-token limit. Back off and retry; Retry-After carries the wait when Redis reports it.
• credit_limit_exceeded — this call costs more credits than you have left for the billing period, or they are spent. Never returned to an Enterprise account, whose usage past the allowance is billed as overage instead.

Credits reset at the end of your billing period; GET /v1.2/credits reports that instant as resets_at and remains available when either limit refuses other operations.

application/json

default

Any other error: the HTTP status plus { code, message }. Retry only rate_limited and the transient 5xx codes.

application/json

get/v1.2/foods/{food_id}

GET /v1.2/foods/{food_id} HTTP/1.1
Host: partners.january.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "101963552",
  "type": "branded",
  "name": "Dipped Banana Bites",
  "brand_name": "Banana",
  "nutrients": {
    "calories": {
      "value": 300,
      "unit": "g"
    },
    "protein": {
      "value": 300,
      "unit": "g"
    },
    "carbohydrates": {
      "value": 300,
      "unit": "g"
    },
    "net_carbohydrates": {
      "value": 300,
      "unit": "g"
    },
    "total_fat": {
      "value": 300,
      "unit": "g"
    },
    "trans_fat": {
      "value": 300,
      "unit": "g"
    },
    "saturated_fat": {
      "value": 300,
      "unit": "g"
    },
    "fiber": {
      "value": 300,
      "unit": "g"
    },
    "total_sugars": {
      "value": 300,
      "unit": "g"
    },
    "added_sugars": {
      "value": 300,
      "unit": "g"
    },
    "cholesterol": {
      "value": 300,
      "unit": "g"
    },
    "calcium": {
      "value": 300,
      "unit": "g"
    },
    "iron": {
      "value": 300,
      "unit": "g"
    },
    "potassium": {
      "value": 300,
      "unit": "g"
    },
    "sodium": {
      "value": 300,
      "unit": "g"
    },
    "vitamin_d": {
      "value": 300,
      "unit": "g"
    }
  },
  "glycemic_index": 1,
  "glycemic_load": 1,
  "image_url": "text",
  "barcode": "049000006346",
  "servings": [
    {
      "id": "68051535",
      "quantity": 1,
      "unit": "oz",
      "scaling_factor": 1,
      "weight_grams": 28,
      "is_primary": true
    }
  ]
}

Suggest healthier alternatives for a food

post

API key or client token.

Costs 4 credits per successful call.

Returns healthier alternatives for a food, honoring the given dietary restrictions and preferences. Omit either array (or send []) if it does not apply. An empty alternatives result is valid — no suitable alternatives were found.

Callable with a client token carrying the foods:read scope.

Authorizations

AuthorizationstringRequired

Your credential, sent as Authorization: Bearer <credential>. Two kinds reach this API, and the prefix tells them apart.

API key (sk-…) — created in the Developer Dashboard, it authenticates your whole account. Use it only where you control the machine — never inside a mobile app or a browser. Every endpoint accepts it.

Client token (ct-…) — a short-lived credential bound to one of your end users, minted from your API key by POST /v1.2/auth/client-tokens on your backend and relayed to the device. Safe to hold on a phone: it expires within 2 hours and acts only as the user it was minted for. Endpoints that open with API key or client token accept one and name the scope it must carry; endpoints that open with API key only refuse it.

Path parameters

food_idstringRequired

Food id from a search or food-analysis result. The example is brown rice.

Example: 70372230Pattern: ^[1-9]\d{0,9}$

Body

Responses

200

Healthier alternatives honoring the restrictions and preferences; may be empty.

application/json

400

A field is missing or a value is not in the allowed vocabulary; the message names it.

application/json

401

The request carried no Authorization header, or the credential in it was rejected.

unauthorized — the header is missing or malformed, or the key is not one we recognise. A valid key belonging to the other API version is 403 forbidden instead.

A client token is rejected in one of three ways, and only the first should be handled automatically:

• token_expired — the token is past its TTL. Mint a fresh one from your backend and retry the request once. This is routine and expected once per TTL window.
• token_invalid — no such token: it was never issued, or it has been purged, which happens shortly after it expires. This code is not an automatic token-refresh signal.
• token_revoked — the token was revoked, by POST /v1.2/auth/client-token-revocations or from the dashboard. The end user signs in again in your app, and your backend decides whether to mint another; a device that just re-mints defeats the revocation.

application/json

403

The credential is valid but is not allowed to make this request. forbidden is the general case — a key issued for the other API version, for example. A client token adds client_token_not_allowed, meaning the endpoint takes only an sk- API key — its description opens with API key only. (in this API: POST /v1.2/auth/client-tokens, POST /v1.2/auth/client-token-revocations, POST /v1.2/chat/completions, POST /v1.2/literature/search, POST /v1.2/extractions, GET /v1.2/extractions/{job_id}, GET /v1.2/patients/{patient_id}/snapshot, and GET /v1.2/credits).

On an endpoint that opens with API key or client token., scope_insufficient means the token was minted without the scope named at the end of that endpoint’s description.

application/json

404

No food with this id.

application/json

429

Two failures share this status; use code to choose the response.

• rate_limited — a rolling abuse window was reached: the partner-wide v1.2 minute cap, a configured short-window limit, or a client-token limit. Back off and retry; Retry-After carries the wait when Redis reports it.
• credit_limit_exceeded — this call costs more credits than you have left for the billing period, or they are spent. Never returned to an Enterprise account, whose usage past the allowance is billed as overage instead.

Credits reset at the end of your billing period; GET /v1.2/credits reports that instant as resets_at and remains available when either limit refuses other operations.

application/json

default

Any other error: the HTTP status plus { code, message }. Retry only rate_limited and the transient 5xx codes.

application/json

post/v1.2/foods/{food_id}/alternatives

POST /v1.2/foods/{food_id}/alternatives HTTP/1.1
Host: partners.january.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 76

{
  "diet_restrictions": [
    "gluten",
    "peanuts"
  ],
  "diet_preferences": [
    "vegetarian"
  ]
}

{
  "alternatives": [
    {
      "id": "70379835",
      "name": "Oatmeal",
      "brand_name": null,
      "nutrients": {
        "calories": {
          "value": 300,
          "unit": "g"
        },
        "protein": {
          "value": 300,
          "unit": "g"
        },
        "carbohydrates": {
          "value": 300,
          "unit": "g"
        },
        "net_carbohydrates": {
          "value": 300,
          "unit": "g"
        },
        "total_fat": {
          "value": 300,
          "unit": "g"
        },
        "trans_fat": {
          "value": 300,
          "unit": "g"
        },
        "saturated_fat": {
          "value": 300,
          "unit": "g"
        },
        "fiber": {
          "value": 300,
          "unit": "g"
        },
        "total_sugars": {
          "value": 300,
          "unit": "g"
        },
        "added_sugars": {
          "value": 300,
          "unit": "g"
        },
        "cholesterol": {
          "value": 300,
          "unit": "g"
        },
        "calcium": {
          "value": 300,
          "unit": "g"
        },
        "iron": {
          "value": 300,
          "unit": "g"
        },
        "potassium": {
          "value": 300,
          "unit": "g"
        },
        "sodium": {
          "value": 300,
          "unit": "g"
        },
        "vitamin_d": {
          "value": 300,
          "unit": "g"
        }
      },
      "servings": [
        {
          "id": "34237662",
          "quantity": 1,
          "unit": "cup",
          "weight_grams": 60
        }
      ]
    }
  ]
}