Glucose prediction

Predict the glucose response to a meal without requiring a sensor. Optional CGM history can personalize the same operation.

Predict the glucose response to a meal

post

API key or client token.

Predicts the glucose curve a meal will produce for the given profile and body.timezone (required — the IANA timezone the end user is in; the prediction depends on the meal's local time of day). Optionally personalize by sending cgm_data with the consumed_foods eaten during it (both together; the upstream needs at least five complete days of paired history). Nothing is stored, so there is no end-user identity to send: the request acts as the partner itself.

Callable with a client token carrying the glucose: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.

Body

timezonestringRequired

The IANA timezone the end user is in. The prediction depends on the meal's local time of day.

Example: America/New_York

start_timestring · date-timeRequired

When the meal is (or will be) eaten. Must carry a timezone designator.

Example: 2024-09-13T11:34:56Z

Responses

200

points, the predicted glucose curve at 15-minute intervals, plus the meal's overall impact score and suggested chart bounds for rendering it.

application/json

impact_scorestring · enum · nullableRequired

The meal's overall glucose impact. Null when the model returned no grade, or one outside this list.

Example: lowPossible values:

400

A field is missing or invalid; the message names it 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, 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

Either a rate limit was exceeded (code: rate_limited) or the monthly credit allowance is spent (code: credit_limit_exceeded). When Retry-After is present, wait that many seconds; a per-day allowance resets 24 hours after the first request in its window. Credit exhaustion carries no Retry-After and retrying does not help — the allowance returns at the start of the next calendar month. Call GET /v1.2/credits for the balance and reset date.

application/json

504

The prediction took too long; retry.

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/glucose/predictions

POST /v1.2/glucose/predictions HTTP/1.1
Host: partners.january.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 323

{
  "user_profile": {
    "age": 42,
    "sex": "female",
    "height": {
      "value": 66,
      "unit": "in"
    },
    "weight": {
      "value": 150,
      "unit": "lb"
    },
    "activity_level": "moderately_active",
    "health_conditions": [
      "prediabetes"
    ]
  },
  "foods": [
    {
      "food_id": "101963552",
      "serving_id": "68051535",
      "quantity": 1.4
    }
  ],
  "start_time": "2024-09-13T11:34:56Z",
  "timezone": "America/New_York"
}

{
  "points": [
    {
      "minutes": 30,
      "value": 140
    }
  ],
  "impact_score": "low",
  "chart": {
    "min": 70,
    "max": 140
  }
}