{"openapi":"3.1.0","info":{"title":"FORM Connector API","version":"1.0.0","description":"Read and write one FORM member's own nutrition and training data, with their consent.\n\nSleep, steps, heart rate and recovery are not available: FORM reads those from Apple Health or Health Connect on the member's device and never stores them server-side.","contact":{"name":"FORM support","email":"support@getinform.co","url":"https://www.getinform.co/support"},"termsOfService":"https://www.getinform.co/terms"},"servers":[{"url":"https://api.getinform.co"}],"security":[{"formOAuth":[]}],"paths":{"/v1/profile":{"get":{"operationId":"getProfile","summary":"The member's goal, daily targets, body measurements, diet, allergens and training preferences.","security":[{"formOAuth":["profile:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid FORM connection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope not granted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/today":{"get":{"operationId":"getToday","summary":"Today's calories and macros against target, water, and the meals logged so far, in the member's own timezone.","security":[{"formOAuth":["nutrition:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid FORM connection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope not granted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/days/{date}":{"get":{"operationId":"getDay","summary":"The same daily picture for a specific date.","security":[{"formOAuth":["nutrition:read"]}],"parameters":[{"name":"date","in":"path","required":true,"schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid FORM connection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope not granted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/trends":{"get":{"operationId":"getTrends","summary":"Averages and day-by-day figures over a recent window, with adherence and weight change.","security":[{"formOAuth":["nutrition:read"]}],"parameters":[{"name":"days","schema":{"type":"integer","minimum":2,"maximum":90,"default":14},"in":"query","required":false},{"name":"end","schema":{"type":"string","format":"date"},"in":"query","required":false}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid FORM connection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope not granted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/meals":{"get":{"operationId":"listMeals","summary":"Logged meals, most recent first, or every meal on one date.","security":[{"formOAuth":["nutrition:read"]}],"parameters":[{"name":"date","schema":{"type":"string","format":"date"},"in":"query","required":false},{"name":"limit","schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"in":"query","required":false}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid FORM connection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope not granted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"logMeal","summary":"Log a meal from a plain description. FORM estimates ingredients, calories and macros.","security":[{"formOAuth":["nutrition:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogMealRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid FORM connection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope not granted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/meals/{id}":{"get":{"operationId":"getMeal","summary":"One meal in full: ingredients, macros, micros, health score and allergens.","security":[{"formOAuth":["nutrition:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid FORM connection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope not granted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/drinks":{"post":{"operationId":"logDrink","summary":"Log water (ml), caffeine (mg) or alcohol (standard units).","security":[{"formOAuth":["nutrition:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogDrinkRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid FORM connection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope not granted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/weights":{"get":{"operationId":"listWeights","summary":"Recent weigh-ins with the change across the window.","security":[{"formOAuth":["body:read"]}],"parameters":[{"name":"limit","schema":{"type":"integer","minimum":1,"maximum":90,"default":30},"in":"query","required":false}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid FORM connection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope not granted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"logWeight","summary":"Record a weigh-in. Supply weight_kg or weight_lb explicitly.","security":[{"formOAuth":["body:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogWeightRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid FORM connection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope not granted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/workouts":{"get":{"operationId":"listWorkouts","summary":"Logged workouts, including sessions imported from Apple Health or Health Connect.","security":[{"formOAuth":["training:read"]}],"parameters":[{"name":"date","schema":{"type":"string","format":"date"},"in":"query","required":false},{"name":"limit","schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"in":"query","required":false}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid FORM connection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope not granted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"logWorkout","summary":"Record a completed workout.","security":[{"formOAuth":["training:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogWorkoutRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid FORM connection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope not granted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/training-plan":{"get":{"operationId":"getTrainingPlan","summary":"The member's current FORM training programme and weekly schedule.","security":[{"formOAuth":["training:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid FORM connection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope not granted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"formOAuth":{"type":"oauth2","description":"OAuth 2.1 authorization code with PKCE (S256). Public clients only; dynamic registration is supported.","flows":{"authorizationCode":{"authorizationUrl":"https://api.getinform.co/oauth/authorize","tokenUrl":"https://api.getinform.co/oauth/token","refreshUrl":"https://api.getinform.co/oauth/token","scopes":{"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"}}}}},"schemas":{"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Stable machine-readable code."},"message":{"type":"string","description":"A sentence suitable for showing a member."},"retryable":{"type":"boolean"}}},"LogMealRequest":{"type":"object","required":["description"],"properties":{"description":{"type":"string","minLength":2,"maxLength":600,"description":"What they ate, in plain words."},"servings":{"type":"number","minimum":0.1,"maximum":20,"default":1},"at":{"type":"string","format":"date-time","description":"When it was eaten. Defaults to now."}}},"LogDrinkRequest":{"type":"object","required":["kind","amount"],"properties":{"kind":{"type":"string","enum":["water","caffeine","alcohol"]},"amount":{"type":"number","exclusiveMinimum":0,"description":"ml, mg or standard units by kind."}}},"LogWeightRequest":{"type":"object","description":"Supply exactly one of weight_kg or weight_lb. The unit is never inferred.","properties":{"weight_kg":{"type":"number","minimum":20,"maximum":400},"weight_lb":{"type":"number","minimum":44,"maximum":880},"waist_cm":{"type":"number","minimum":30,"maximum":250},"note":{"type":"string","maxLength":200}},"anyOf":[{"required":["weight_kg"]},{"required":["weight_lb"]}]},"LogWorkoutRequest":{"type":"object","required":["name","duration_minutes"],"properties":{"name":{"type":"string","minLength":2,"maxLength":80},"duration_minutes":{"type":"number","minimum":1,"maximum":1440},"calories_burned":{"type":"number","minimum":0,"maximum":5000},"intensity":{"type":"string","enum":["low","moderate","high"]},"at":{"type":"string","format":"date-time"}}}}}}