FORM · Developers

Connect an assistant to FORM

FORM tracks what a member eats and how they train. This connector lets an AI assistant read that member’s own data, and log meals and workouts for them, once they have signed in and agreed.

It speaks MCP over HTTP, and the same data is available as a plain REST API. Both sit behind OAuth 2.1 with PKCE.

What this is

One endpoint, serving a member’s own FORM data. Everything is scoped to the person who authorised it — there is no organisation-wide or cross-member access, and no way to ask for another member’s records.

MCP endpoint   https://api.getinform.co/mcp
REST base      https://api.getinform.co/v1
OpenAPI        https://api.getinform.co/openapi.json
Tool list      https://api.getinform.co/tools.json

Sleep, steps, heart rate and recovery are not available. FORM reads those from Apple Health and Health Connect on the member’s phone and never stores them on a server, so the connector genuinely cannot see them. Say so rather than estimating.

Connecting

OAuth 2.1, authorization code with PKCE. Public clients only — there is no client secret, which is the right shape for an assistant that runs in many places.S256 is the only challenge method accepted.

Discovery is where you should start; every URL below comes from it.

GET https://api.getinform.co/.well-known/oauth-authorization-server
GET https://api.getinform.co/.well-known/oauth-protected-resource

Clients may register themselves (RFC 7591) rather than waiting for us to issue credentials:

POST https://api.getinform.co/oauth/register
Content-Type: application/json

{
  "client_name": "Your assistant",
  "redirect_uris": ["https://your.app/callback"]
}

Redirect URIs must use https, or http on loopback for desktop clients, and must match the registration exactly. Access tokens last an hour; refresh tokens rotate on every use, and presenting a retired one ends the connection. A member can disconnect at any time, and access stops within a minute.

Scopes

Ask only for what you need. A tool whose scope was not granted is not offered to the assistant at all, so a read-only connection simply has no way to write.

profile:read
Read your FORM profile, targets and preferences
nutrition:read
Read the meals, water and drinks you have logged
nutrition:write
Log meals, water and drinks on your behalf
training:read
Read your workouts and training plan
training:write
Log workouts on your behalf
body:read
Read your weight history
body:write
Record a weigh-in on your behalf

MCP tools

13 tools, 4 of which write to the member's real diary. Writing tools are marked; confirm details with the member before calling one, and call it once.

Reading

  • get_todaynutrition:read

    How the member is doing today: calories and macros consumed against their targets, water, and the meals they have logged. Use this for any question about today, right now, or how much is left.

  • get_daynutrition:read

    The same picture as get_today, for a specific past date. Use for questions about yesterday or a named day.

  • get_trendsnutrition:read

    Averages and day-by-day figures over a recent window: calories, macros, water, workouts, weight change and how many days were actually logged. Use for questions about a week, a fortnight, a month, consistency, or whether something is improving.

  • get_profileprofile:read

    The member's goal, daily targets, body measurements, diet, allergens and training preferences. Read this before giving any advice about what they should eat or do, and always before suggesting food — it carries their allergens.

  • list_mealsnutrition:read

    The member's logged meals, most recent first, or all meals on one date. Returns names, calories and macros — use get_meal for a full ingredient breakdown.

  • get_mealnutrition:read

    Everything FORM knows about one logged meal: ingredients with amounts, full macros and micros, health score and allergens. Needs a meal id from list_meals or get_today.

  • get_weight_historybody:read

    Recent weigh-ins with the change across the window and the member's goal weight.

  • get_workoutstraining:read

    Workouts the member has logged, most recent first, or all workouts on one date. Includes sessions imported from Apple Health or Health Connect.

  • get_training_plantraining:read

    The member's current FORM training programme and this week's schedule, if they have generated one.

Writing

  • log_mealwritesnutrition:write

    Record something the member ate, from a plain description such as 'grilled chicken with rice and broccoli'. FORM estimates the ingredients, calories and macros. This writes to the member's real food diary and runs an analysis that takes a few seconds — confirm the description with them before calling it, and call it once per meal.

  • log_drinkwritesnutrition:write

    Record water in millilitres, caffeine in milligrams, or alcohol in standard units. Writes to the member's real diary.

  • log_weightwritesbody:write

    Record the member's weight. Give it as weight_kg or weight_lb — do not convert or guess which the member meant. Writes to their real history and updates their current weight.

  • log_workoutwritestraining:write

    Record a workout the member has done. Writes to their real training history.

REST API

The same data, for anything that does not speak MCP. Bearer token in theAuthorization header; the full contract is in openapi.json.

  • GET/v1/days/{date}

    The same daily picture for a specific date.

  • GET/v1/meals

    Logged meals, most recent first, or every meal on one date.

  • GET/v1/meals/{id}

    One meal in full: ingredients, macros, micros, health score and allergens.

  • GET/v1/profile

    The member's goal, daily targets, body measurements, diet, allergens and training preferences.

  • GET/v1/today

    Today's calories and macros against target, water, and the meals logged so far, in the member's own timezone.

  • GET/v1/training-plan

    The member's current FORM training programme and weekly schedule.

  • GET/v1/trends

    Averages and day-by-day figures over a recent window, with adherence and weight change.

  • GET/v1/weights

    Recent weigh-ins with the change across the window.

  • GET/v1/workouts

    Logged workouts, including sessions imported from Apple Health or Health Connect.

  • POST/v1/drinks

    Log water (ml), caffeine (mg) or alcohol (standard units).

  • POST/v1/meals

    Log a meal from a plain description. FORM estimates ingredients, calories and macros.

  • POST/v1/weights

    Record a weigh-in. Supply weight_kg or weight_lb explicitly.

  • POST/v1/workouts

    Record a completed workout.

Limits and errors

Per member, so one assistant cannot spend another member’s allowance:

  • 600 requests an hour
  • 120 writes an hour
  • 40 meal analyses a day — this one runs a language model

Errors carry a stable code and a sentence written to be read aloud to the member, so you rarely need to rewrite them.

{
  "error": "rate_limited",
  "message": "FORM's meal analysis has hit today's limit for this account. Try again tomorrow.",
  "retryable": true
}

A member who has not finished setting up FORM has no targets yet. Reads succeed and report setup_incomplete rather than returning zeroes — tell them to finish setup in the app instead of reporting a target of nothing.

Support

Questions, or a connector you would like listed: support@getinform.co.

Privacy · Terms · getinform.co