{ "openapi": "3.1.0", "info": { "title": "FoodABCs API", "version": "1.0.0" }, "servers": [ { "url": "https://www.foodabcs.com/api" } ], "components": { "securitySchemes": { "oauth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://www.foodabcs.com/oauth/authorize", "tokenUrl": "https://www.foodabcs.com/api/oauth/token", "scopes": { "profile.read": "View your FoodABCs profile summary", "demographics.read": "View your demographics", "demographics.write": "Update your demographics", "meals.read": "View your meal history, grades, and favorite meals from all your apps", "meals.write": "Log, analyze, update, and favorite meals from this app", "workouts.read": "View your workout history and grades from all your apps", "workouts.write": "Log and update workouts from this app", "moods.read": "View your mood check-ins from all your apps", "moods.write": "Log mood check-ins and prompt responses from this app", "wellness.read": "View your wellness metrics", "goals.read": "View your FoodABCs goals", "goals.write": "Update your FoodABCs goals", "restrictions.read": "View your dietary restrictions", "restrictions.write": "Update your dietary restrictions", "conditions.read": "View your health conditions", "conditions.write": "Update your health conditions", "exams.read": "View your physical exam metrics", "exams.write": "Log physical exam metrics from this app", "medications.read": "View your medication list", "medications.write": "Update your medication list", "behaviors.read": "View FoodABCs eating behavior insights", "foods.search": "Search foods, barcodes, farmers markets, and medications", "offline_access": "Keep you connected after the current session" } } } }, "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "FoodABCs partner API key" } }, "schemas": { "MealIngredient": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "amount": { "type": [ "number", "null" ] }, "unit": { "type": [ "string", "null" ] }, "logged_nutrients": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true }, "MealDraftResponse": { "type": "object", "required": [ "name", "ingredients", "total_calories", "projected_grade" ], "properties": { "name": { "type": "string" }, "ingredients": { "type": "array", "items": { "$ref": "#/components/schemas/MealIngredient" } }, "total_calories": { "type": [ "number", "null" ] }, "projected_grade": { "type": [ "string", "null" ] }, "grade_pending_reason": { "type": "string" } }, "additionalProperties": true }, "MealSavedResponse": { "type": "object", "required": [ "id", "source_app_id", "classification_status" ], "properties": { "id": { "type": "integer" }, "source_app_id": { "type": "string", "format": "uuid" }, "meal_score": { "type": [ "string", "null" ] }, "classification_status": { "type": "string", "enum": [ "queued" ] } }, "additionalProperties": true }, "AnalyzeImageJsonRequest": { "type": "object", "required": [ "image" ], "properties": { "image": { "type": "string", "contentEncoding": "base64", "description": "Base64 encoded JPEG, PNG, WebP, HEIC, or HEIF image. Data URLs are accepted." }, "save": { "type": "boolean", "default": false, "description": "When true, FoodABCs creates the meal immediately; otherwise a draft is returned." } }, "additionalProperties": false }, "AnalyzeImageMultipartRequest": { "type": "object", "required": [ "image" ], "properties": { "image": { "type": "string", "format": "binary", "description": "JPEG, PNG, WebP, HEIC, or HEIF image up to 3 MB." }, "save": { "type": "boolean", "default": false } }, "additionalProperties": false }, "AnalyzeTextRequest": { "type": "object", "required": [ "description" ], "properties": { "description": { "type": "string", "maxLength": 1000, "description": "Plain-language meal description, such as grilled chicken sandwich with avocado." }, "save": { "type": "boolean", "default": false, "description": "When true, FoodABCs creates the meal immediately; otherwise a draft is returned." } }, "additionalProperties": false }, "MealGradedWebhookPayload": { "type": "object", "required": [ "meal_id", "user_id", "grade", "classified_at" ], "properties": { "meal_id": { "type": "integer" }, "user_id": { "type": "string", "format": "uuid" }, "grade": { "type": [ "string", "null" ] }, "classified_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } }, "x-foodabcs-webhook-events": [ { "type": "data.deleted", "description": "A granted user account was deleted and partner-linked retained data was anonymized.", "payload": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "additionalProperties": true }, "example": { "id": "evt_01JZ9MBSDJ5HF3Q5T6ZVY51D2Q", "type": "data.deleted", "created_at": "2026-06-29T18:30:00.000Z", "data": { "user_ref": "usr_7ca9704d", "reason": "account_deletion" } } }, { "type": "grant.revoked", "description": "A user revoked an active partner grant.", "payload": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "additionalProperties": true }, "example": { "id": "evt_01JZ9MC3EPPWAJR80GX1VP9GMX", "type": "grant.revoked", "created_at": "2026-06-29T18:30:00.000Z", "data": { "user_id": "6bc72c8d-6d8a-4e85-9cbb-c02d19dca12f", "partner_id": "7d3fb86b-470d-4855-8daf-c574a81bf2dc", "revoked_at": "2026-06-29T18:29:58.000Z" } } }, { "type": "meal.graded", "description": "An API-created meal finished asynchronous classification.", "payload": { "type": "object", "required": [ "meal_id", "user_id", "grade", "classified_at" ], "properties": { "meal_id": { "type": "integer" }, "user_id": { "type": "string", "format": "uuid" }, "grade": { "type": [ "string", "null" ] }, "classified_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "example": { "meal_id": 1042, "user_id": "6bc72c8d-6d8a-4e85-9cbb-c02d19dca12f", "grade": "A", "classified_at": "2026-06-29T18:30:08.000Z" } } ], "paths": { "/v1/me": { "get": { "operationId": "get_me_read", "summary": "Get profile summary", "description": "Returns the current user’s profile identity and lifetime activity counts.", "tags": [ "Profile" ], "security": [ { "oauth2": [ "profile.read" ] } ], "parameters": [], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "first_name", "last_name", "created_at", "meal_count", "workout_count", "mood_count", "physical_exam_count" ], "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "meal_count": { "type": "integer" }, "workout_count": { "type": "integer" }, "mood_count": { "type": "integer" }, "physical_exam_count": { "type": "integer" } }, "additionalProperties": false }, "example": { "first_name": "Alex", "last_name": "Rivera", "created_at": "2025-11-04T19:22:10.000Z", "meal_count": 184, "workout_count": 67, "mood_count": 93, "physical_exam_count": 4 } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "404": { "description": "The requested resource does not exist or is not visible to this credential.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "not_found", "message": "Resource not found.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "me.read", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "me.read", "x-foodabcs-price-cents": 0.5, "x-foodabcs-tier2-price-cents": 1, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/demographics": { "get": { "operationId": "get_demographics_read", "summary": "Get demographics", "description": "Returns the current user’s self-reported demographic profile. Fields may be null when the user has not answered them.", "tags": [ "Profile" ], "security": [ { "oauth2": [ "demographics.read" ] } ], "parameters": [], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "birthdate", "sex", "state", "zip_code", "race_ethnicity", "snap_wic_status", "household_income" ], "properties": { "birthdate": { "type": "string", "format": "date" }, "sex": { "type": "string" }, "state": { "type": "string" }, "zip_code": { "type": "string" }, "race_ethnicity": { "type": "string" }, "snap_wic_status": { "type": "string" }, "household_income": { "type": "string" } }, "additionalProperties": false }, "example": { "birthdate": "1992-04-18", "sex": "female", "state": "CO", "zip_code": "80205", "race_ethnicity": "Hispanic or Latino", "snap_wic_status": "Not receiving", "household_income": "$75,000 – $99,999" } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "404": { "description": "The requested resource does not exist or is not visible to this credential.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "not_found", "message": "Resource not found.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "demographics.read", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "demographics.read", "x-foodabcs-price-cents": 0.5, "x-foodabcs-tier2-price-cents": 1, "x-foodabcs-infra-cost-cents": 0.02 }, "patch": { "operationId": "patch_demographics_write", "summary": "Update demographics", "description": "Updates only the supplied self-reported fields and returns the complete demographic profile.", "tags": [ "Profile" ], "security": [ { "oauth2": [ "demographics.write" ] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "state": { "type": "string" }, "zip_code": { "type": "string" }, "household_income": { "type": "string" } }, "additionalProperties": false, "minProperties": 1 }, "example": { "state": "CO", "zip_code": "80205", "household_income": "$75,000 – $99,999" } } } }, "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "birthdate", "sex", "state", "zip_code", "race_ethnicity", "snap_wic_status", "household_income" ], "properties": { "birthdate": { "type": "string", "format": "date" }, "sex": { "type": "string" }, "state": { "type": "string" }, "zip_code": { "type": "string" }, "race_ethnicity": { "type": "string" }, "snap_wic_status": { "type": "string" }, "household_income": { "type": "string" } }, "additionalProperties": false }, "example": { "birthdate": "1992-04-18", "sex": "female", "state": "CO", "zip_code": "80205", "race_ethnicity": "Hispanic or Latino", "snap_wic_status": "Not receiving", "household_income": "$75,000 – $99,999" } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "404": { "description": "The requested resource does not exist or is not visible to this credential.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "not_found", "message": "Resource not found.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "demographics.write", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "demographics.write", "x-foodabcs-price-cents": 1, "x-foodabcs-tier2-price-cents": 2, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/meals": { "post": { "operationId": "post_meals_write", "summary": "Create a meal", "description": "Creates an API-owned meal, calculates its immediate grade, and queues asynchronous classification.", "tags": [ "Meals" ], "security": [ { "oauth2": [ "meals.write" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key that safely replays the first response when the same request body is retried.", "schema": { "type": "string" }, "example": "61d6c26b-4f60-4a03-a8df-c65bf86a6b64" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ingredients" ], "properties": { "timestamp": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "ingredients": { "type": "array", "items": { "type": "object", "required": [ "name", "amount", "unit", "nutrition" ], "properties": { "name": { "type": "string" }, "amount": { "type": "integer" }, "unit": { "type": "string" }, "nutrition": { "type": "object", "required": [ "nutrients" ], "properties": { "nutrients": { "type": "array", "items": { "type": "object", "required": [ "name", "amount", "unit" ], "properties": { "name": { "type": "string" }, "amount": { "type": "integer" }, "unit": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } }, "additionalProperties": false } }, "total_calories": { "type": "integer" } }, "additionalProperties": false }, "example": { "timestamp": "2026-06-29T18:30:00Z", "name": "Chicken quinoa bowl", "ingredients": [ { "name": "Grilled chicken breast", "amount": 5, "unit": "oz", "nutrition": { "nutrients": [ { "name": "Calories", "amount": 234, "unit": "kcal" }, { "name": "Protein", "amount": 44, "unit": "g" }, { "name": "Carbohydrates", "amount": 0, "unit": "g" }, { "name": "Fat", "amount": 5, "unit": "g" } ] } }, { "name": "Cooked quinoa", "amount": 1, "unit": "cup", "nutrition": { "nutrients": [ { "name": "Calories", "amount": 222, "unit": "kcal" }, { "name": "Protein", "amount": 8, "unit": "g" }, { "name": "Carbohydrates", "amount": 39, "unit": "g" }, { "name": "Fat", "amount": 4, "unit": "g" } ] } } ], "total_calories": 612 } } } }, "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "user_id", "timestamp", "name", "ingredients", "total_calories", "meal_score", "is_favorite", "meal_classifications", "meal_classification_version", "meal_classified_at", "meal_behavior_events", "meal_behavior_version", "meal_behavior_detected_at", "source_app_id", "classification_status" ], "properties": { "id": { "type": "string" }, "user_id": { "type": "string", "format": "uuid" }, "timestamp": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "ingredients": { "type": "array", "items": { "type": "object", "required": [ "name", "amount", "unit", "nutrition" ], "properties": { "name": { "type": "string" }, "amount": { "type": "integer" }, "unit": { "type": "string" }, "nutrition": { "type": "object", "required": [ "nutrients" ], "properties": { "nutrients": { "type": "array", "items": { "type": "object", "required": [ "name", "amount", "unit" ], "properties": { "name": { "type": "string" }, "amount": { "type": "integer" }, "unit": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } }, "additionalProperties": false } }, "total_calories": { "type": "string" }, "meal_score": { "type": "string" }, "is_favorite": { "type": "boolean" }, "meal_classifications": { "type": "array", "items": { "type": "object", "required": [ "key", "label" ], "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "additionalProperties": false } }, "meal_classification_version": { "type": "string" }, "meal_classified_at": { "type": "string", "format": "date-time" }, "meal_behavior_events": { "type": "array", "items": {} }, "meal_behavior_version": { "type": "string" }, "meal_behavior_detected_at": { "type": "string", "format": "date-time" }, "source_app_id": { "type": "string", "format": "uuid" }, "classification_status": { "type": "string" } }, "additionalProperties": false }, "example": { "id": "1042", "user_id": "6bc72c8d-6d8a-4e85-9cbb-c02d19dca12f", "timestamp": "2026-06-29T18:30:00.000Z", "name": "Chicken quinoa bowl", "ingredients": [ { "name": "Grilled chicken breast", "amount": 5, "unit": "oz", "nutrition": { "nutrients": [ { "name": "Calories", "amount": 234, "unit": "kcal" }, { "name": "Protein", "amount": 44, "unit": "g" }, { "name": "Carbohydrates", "amount": 0, "unit": "g" }, { "name": "Fat", "amount": 5, "unit": "g" } ] } }, { "name": "Cooked quinoa", "amount": 1, "unit": "cup", "nutrition": { "nutrients": [ { "name": "Calories", "amount": 222, "unit": "kcal" }, { "name": "Protein", "amount": 8, "unit": "g" }, { "name": "Carbohydrates", "amount": 39, "unit": "g" }, { "name": "Fat", "amount": 4, "unit": "g" } ] } } ], "total_calories": "612", "meal_score": "A", "is_favorite": false, "meal_classifications": [ { "key": "high_protein", "label": "High protein" } ], "meal_classification_version": "v1", "meal_classified_at": "2026-06-29T18:30:08.000Z", "meal_behavior_events": [], "meal_behavior_version": "v1", "meal_behavior_detected_at": "2026-06-29T18:30:08.000Z", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7", "classification_status": "queued" } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "409": { "description": "The Idempotency-Key was already used with a different request body.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "idempotency_conflict", "message": "Idempotency-Key was already used with a different request.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "meals.write", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "meals.write", "x-foodabcs-price-cents": 1, "x-foodabcs-tier2-price-cents": 2, "x-foodabcs-infra-cost-cents": 0.02 }, "get": { "operationId": "get_meals_read", "summary": "List meals", "description": "Lists meals visible to the user across all sources in reverse chronological order.", "tags": [ "Meals" ], "security": [ { "oauth2": [ "meals.read" ] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Inclusive ISO 8601 range start.", "schema": { "type": "string" }, "example": "2026-06-01T00:00:00Z" }, { "name": "to", "in": "query", "required": false, "description": "Inclusive ISO 8601 range end.", "schema": { "type": "string" }, "example": "2026-06-30T23:59:59Z" }, { "name": "limit", "in": "query", "required": false, "description": "Number of records to return (1–100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "example": 25 }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque next_cursor from the previous response.", "schema": { "type": "string" }, "example": "MjAyNi0wNi0yOVQxODozMDowMC4wMDBafDEwNDI" } ], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "user_id", "timestamp", "name", "ingredients", "total_calories", "meal_score", "is_favorite", "meal_classifications", "meal_classification_version", "meal_classified_at", "meal_behavior_events", "meal_behavior_version", "meal_behavior_detected_at", "source_app_id" ], "properties": { "id": { "type": "string" }, "user_id": { "type": "string", "format": "uuid" }, "timestamp": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "ingredients": { "type": "array", "items": { "type": "object", "required": [ "name", "amount", "unit", "nutrition" ], "properties": { "name": { "type": "string" }, "amount": { "type": "integer" }, "unit": { "type": "string" }, "nutrition": { "type": "object", "required": [ "nutrients" ], "properties": { "nutrients": { "type": "array", "items": { "type": "object", "required": [ "name", "amount", "unit" ], "properties": { "name": { "type": "string" }, "amount": { "type": "integer" }, "unit": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } }, "additionalProperties": false } }, "total_calories": { "type": "string" }, "meal_score": { "type": "string" }, "is_favorite": { "type": "boolean" }, "meal_classifications": { "type": "array", "items": { "type": "object", "required": [ "key", "label" ], "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "additionalProperties": false } }, "meal_classification_version": { "type": "string" }, "meal_classified_at": { "type": "string", "format": "date-time" }, "meal_behavior_events": { "type": "array", "items": {} }, "meal_behavior_version": { "type": "string" }, "meal_behavior_detected_at": { "type": "string", "format": "date-time" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "next_cursor": { "type": "string" } }, "additionalProperties": false }, "example": { "data": [ { "id": "1042", "user_id": "6bc72c8d-6d8a-4e85-9cbb-c02d19dca12f", "timestamp": "2026-06-29T18:30:00.000Z", "name": "Chicken quinoa bowl", "ingredients": [ { "name": "Grilled chicken breast", "amount": 5, "unit": "oz", "nutrition": { "nutrients": [ { "name": "Calories", "amount": 234, "unit": "kcal" }, { "name": "Protein", "amount": 44, "unit": "g" }, { "name": "Carbohydrates", "amount": 0, "unit": "g" }, { "name": "Fat", "amount": 5, "unit": "g" } ] } }, { "name": "Cooked quinoa", "amount": 1, "unit": "cup", "nutrition": { "nutrients": [ { "name": "Calories", "amount": 222, "unit": "kcal" }, { "name": "Protein", "amount": 8, "unit": "g" }, { "name": "Carbohydrates", "amount": 39, "unit": "g" }, { "name": "Fat", "amount": 4, "unit": "g" } ] } } ], "total_calories": "612", "meal_score": "A", "is_favorite": false, "meal_classifications": [ { "key": "high_protein", "label": "High protein" } ], "meal_classification_version": "v1", "meal_classified_at": "2026-06-29T18:30:08.000Z", "meal_behavior_events": [], "meal_behavior_version": "v1", "meal_behavior_detected_at": "2026-06-29T18:30:08.000Z", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } ], "next_cursor": "MjAyNi0wNi0yOFQxMzowMDowMC4wMDBafDEwNDI" } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "meals.read", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "meals.read", "x-foodabcs-price-cents": 0.5, "x-foodabcs-tier2-price-cents": 1, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/meals/analyze-image": { "post": { "operationId": "post_meals_analyze_image", "summary": "Analyze a meal image", "description": "Extracts ingredients and nutrition from a supported image. Set save to true to create the meal; otherwise the response is a draft.", "tags": [ "Meals" ], "security": [ { "oauth2": [ "meals.write" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key that safely replays the first response when the same request body is retried.", "schema": { "type": "string" }, "example": "61d6c26b-4f60-4a03-a8df-c65bf86a6b64" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "image" ], "properties": { "image": { "type": "string", "contentEncoding": "base64", "description": "Base64 encoded JPEG, PNG, WebP, HEIC, or HEIF image. Data URLs are accepted." }, "save": { "type": "boolean", "default": false, "description": "When true, FoodABCs creates the meal immediately; otherwise a draft is returned." } }, "additionalProperties": false }, "example": { "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...", "save": false } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "image" ], "properties": { "image": { "type": "string", "format": "binary", "description": "JPEG, PNG, WebP, HEIC, or HEIF image up to 3 MB." }, "save": { "type": "boolean", "default": false } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/MealDraftResponse" }, { "$ref": "#/components/schemas/MealSavedResponse" } ] }, "example": { "name": "Chicken quinoa bowl", "ingredients": [ { "name": "Grilled chicken breast", "amount": 5, "unit": "oz", "nutrition": { "nutrients": [ { "name": "Calories", "amount": 234, "unit": "kcal" }, { "name": "Protein", "amount": 44, "unit": "g" }, { "name": "Carbohydrates", "amount": 0, "unit": "g" }, { "name": "Fat", "amount": 5, "unit": "g" } ] } }, { "name": "Cooked quinoa", "amount": 1, "unit": "cup", "nutrition": { "nutrients": [ { "name": "Calories", "amount": 222, "unit": "kcal" }, { "name": "Protein", "amount": 8, "unit": "g" }, { "name": "Carbohydrates", "amount": 39, "unit": "g" }, { "name": "Fat", "amount": 4, "unit": "g" } ] } } ], "total_calories": 612, "projected_grade": "A", "grade_pending_reason": "Ingredient details are sufficient for an initial grade." } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "409": { "description": "The Idempotency-Key was already used with a different request body.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "idempotency_conflict", "message": "Idempotency-Key was already used with a different request.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "meals.analyze_image", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "meals.analyze_image", "x-foodabcs-price-cents": 7, "x-foodabcs-tier2-price-cents": 14, "x-foodabcs-infra-cost-cents": 0.1 } }, "/v1/meals/analyze-text": { "post": { "operationId": "post_meals_analyze_text", "summary": "Analyze a meal description", "description": "Turns a plain-language meal description into a scored draft or, when save is true, an API-owned meal.", "tags": [ "Meals" ], "security": [ { "oauth2": [ "meals.write" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key that safely replays the first response when the same request body is retried.", "schema": { "type": "string" }, "example": "61d6c26b-4f60-4a03-a8df-c65bf86a6b64" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "description" ], "properties": { "description": { "type": "string", "maxLength": 1000, "description": "Plain-language meal description, such as grilled chicken sandwich with avocado." }, "save": { "type": "boolean", "default": false, "description": "When true, FoodABCs creates the meal immediately; otherwise a draft is returned." } }, "additionalProperties": false }, "example": { "description": "Turkey and avocado sandwich on whole wheat bread", "save": false } } } }, "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/MealDraftResponse" }, { "$ref": "#/components/schemas/MealSavedResponse" } ] }, "example": { "name": "Turkey avocado sandwich", "ingredients": [ { "name": "Whole wheat bread", "amount": 2, "unit": "slices", "calories": 160 }, { "name": "Sliced turkey", "amount": 4, "unit": "oz", "calories": 120 }, { "name": "Avocado", "amount": 0.5, "unit": "each", "calories": 120 } ], "total_calories": 400, "projected_grade": "B", "grade_pending_reason": "Some ingredient nutrition values were estimated." } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "409": { "description": "The Idempotency-Key was already used with a different request body.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "idempotency_conflict", "message": "Idempotency-Key was already used with a different request.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "meals.analyze_text", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "meals.analyze_text", "x-foodabcs-price-cents": 5.5, "x-foodabcs-tier2-price-cents": 11, "x-foodabcs-infra-cost-cents": 0.05 } }, "/v1/meals/{mealId}": { "get": { "operationId": "get_meals_read_one", "summary": "Get a meal", "description": "Returns one meal visible to the current user.", "tags": [ "Meals" ], "security": [ { "oauth2": [ "meals.read" ] } ], "parameters": [ { "name": "mealId", "in": "path", "required": true, "description": "Meal identifier.", "schema": { "type": "string" }, "example": "1042" } ], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "user_id", "timestamp", "name", "ingredients", "total_calories", "meal_score", "is_favorite", "meal_classifications", "meal_classification_version", "meal_classified_at", "meal_behavior_events", "meal_behavior_version", "meal_behavior_detected_at", "source_app_id" ], "properties": { "id": { "type": "string" }, "user_id": { "type": "string", "format": "uuid" }, "timestamp": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "ingredients": { "type": "array", "items": { "type": "object", "required": [ "name", "amount", "unit", "nutrition" ], "properties": { "name": { "type": "string" }, "amount": { "type": "integer" }, "unit": { "type": "string" }, "nutrition": { "type": "object", "required": [ "nutrients" ], "properties": { "nutrients": { "type": "array", "items": { "type": "object", "required": [ "name", "amount", "unit" ], "properties": { "name": { "type": "string" }, "amount": { "type": "integer" }, "unit": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } }, "additionalProperties": false } }, "total_calories": { "type": "string" }, "meal_score": { "type": "string" }, "is_favorite": { "type": "boolean" }, "meal_classifications": { "type": "array", "items": { "type": "object", "required": [ "key", "label" ], "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "additionalProperties": false } }, "meal_classification_version": { "type": "string" }, "meal_classified_at": { "type": "string", "format": "date-time" }, "meal_behavior_events": { "type": "array", "items": {} }, "meal_behavior_version": { "type": "string" }, "meal_behavior_detected_at": { "type": "string", "format": "date-time" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, "example": { "id": "1042", "user_id": "6bc72c8d-6d8a-4e85-9cbb-c02d19dca12f", "timestamp": "2026-06-29T18:30:00.000Z", "name": "Chicken quinoa bowl", "ingredients": [ { "name": "Grilled chicken breast", "amount": 5, "unit": "oz", "nutrition": { "nutrients": [ { "name": "Calories", "amount": 234, "unit": "kcal" }, { "name": "Protein", "amount": 44, "unit": "g" }, { "name": "Carbohydrates", "amount": 0, "unit": "g" }, { "name": "Fat", "amount": 5, "unit": "g" } ] } }, { "name": "Cooked quinoa", "amount": 1, "unit": "cup", "nutrition": { "nutrients": [ { "name": "Calories", "amount": 222, "unit": "kcal" }, { "name": "Protein", "amount": 8, "unit": "g" }, { "name": "Carbohydrates", "amount": 39, "unit": "g" }, { "name": "Fat", "amount": 4, "unit": "g" } ] } } ], "total_calories": "612", "meal_score": "A", "is_favorite": false, "meal_classifications": [ { "key": "high_protein", "label": "High protein" } ], "meal_classification_version": "v1", "meal_classified_at": "2026-06-29T18:30:08.000Z", "meal_behavior_events": [], "meal_behavior_version": "v1", "meal_behavior_detected_at": "2026-06-29T18:30:08.000Z", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "404": { "description": "The requested resource does not exist or is not visible to this credential.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "not_found", "message": "Resource not found.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "meals.read.one", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "meals.read.one", "x-foodabcs-price-cents": 0.5, "x-foodabcs-tier2-price-cents": 1, "x-foodabcs-infra-cost-cents": 0.02 }, "patch": { "operationId": "patch_meals_update", "summary": "Update a meal", "description": "Updates an API-owned meal. Records created by another source cannot be modified by this app.", "tags": [ "Meals" ], "security": [ { "oauth2": [ "meals.write" ] } ], "parameters": [ { "name": "mealId", "in": "path", "required": true, "description": "Meal identifier.", "schema": { "type": "string" }, "example": "1042" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "name": { "type": "string" }, "total_calories": { "type": "integer" } }, "additionalProperties": false, "minProperties": 1 }, "example": { "name": "Chicken, quinoa, and kale bowl", "total_calories": 638 } } } }, "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "user_id", "timestamp", "name", "ingredients", "total_calories", "meal_score", "is_favorite", "meal_classifications", "meal_classification_version", "meal_classified_at", "meal_behavior_events", "meal_behavior_version", "meal_behavior_detected_at", "source_app_id" ], "properties": { "id": { "type": "string" }, "user_id": { "type": "string", "format": "uuid" }, "timestamp": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "ingredients": { "type": "array", "items": { "type": "object", "required": [ "name", "amount", "unit", "nutrition" ], "properties": { "name": { "type": "string" }, "amount": { "type": "integer" }, "unit": { "type": "string" }, "nutrition": { "type": "object", "required": [ "nutrients" ], "properties": { "nutrients": { "type": "array", "items": { "type": "object", "required": [ "name", "amount", "unit" ], "properties": { "name": { "type": "string" }, "amount": { "type": "integer" }, "unit": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } }, "additionalProperties": false } }, "total_calories": { "type": "string" }, "meal_score": { "type": "string" }, "is_favorite": { "type": "boolean" }, "meal_classifications": { "type": "array", "items": { "type": "object", "required": [ "key", "label" ], "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "additionalProperties": false } }, "meal_classification_version": { "type": "string" }, "meal_classified_at": { "type": "string", "format": "date-time" }, "meal_behavior_events": { "type": "array", "items": {} }, "meal_behavior_version": { "type": "string" }, "meal_behavior_detected_at": { "type": "string", "format": "date-time" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, "example": { "id": "1042", "user_id": "6bc72c8d-6d8a-4e85-9cbb-c02d19dca12f", "timestamp": "2026-06-29T18:30:00.000Z", "name": "Chicken, quinoa, and kale bowl", "ingredients": [ { "name": "Grilled chicken breast", "amount": 5, "unit": "oz", "nutrition": { "nutrients": [ { "name": "Calories", "amount": 234, "unit": "kcal" }, { "name": "Protein", "amount": 44, "unit": "g" }, { "name": "Carbohydrates", "amount": 0, "unit": "g" }, { "name": "Fat", "amount": 5, "unit": "g" } ] } }, { "name": "Cooked quinoa", "amount": 1, "unit": "cup", "nutrition": { "nutrients": [ { "name": "Calories", "amount": 222, "unit": "kcal" }, { "name": "Protein", "amount": 8, "unit": "g" }, { "name": "Carbohydrates", "amount": 39, "unit": "g" }, { "name": "Fat", "amount": 4, "unit": "g" } ] } } ], "total_calories": "638", "meal_score": "A", "is_favorite": false, "meal_classifications": [ { "key": "high_protein", "label": "High protein" } ], "meal_classification_version": "v1", "meal_classified_at": "2026-06-29T18:30:08.000Z", "meal_behavior_events": [], "meal_behavior_version": "v1", "meal_behavior_detected_at": "2026-06-29T18:30:08.000Z", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "404": { "description": "The requested resource does not exist or is not visible to this credential.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "not_found", "message": "Resource not found.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "meals.update", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "meals.update", "x-foodabcs-price-cents": 1, "x-foodabcs-tier2-price-cents": 2, "x-foodabcs-infra-cost-cents": 0.02 }, "delete": { "operationId": "delete_meals_delete", "summary": "Delete a meal", "description": "Deletes an API-owned meal and returns the deleted identifier.", "tags": [ "Meals" ], "security": [ { "oauth2": [ "meals.write" ] } ], "parameters": [ { "name": "mealId", "in": "path", "required": true, "description": "Meal identifier.", "schema": { "type": "string" }, "example": "1042" } ], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted", "id" ], "properties": { "deleted": { "type": "boolean" }, "id": { "type": "string" } }, "additionalProperties": false }, "example": { "deleted": true, "id": "1042" } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "404": { "description": "The requested resource does not exist or is not visible to this credential.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "not_found", "message": "Resource not found.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "meals.delete", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "meals.delete", "x-foodabcs-price-cents": 1, "x-foodabcs-tier2-price-cents": 2, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/meals/{mealId}/grade": { "get": { "operationId": "get_meals_grade_read", "summary": "Get a meal grade", "description": "Returns the current grade and asynchronous classifications for one meal.", "tags": [ "Meals" ], "security": [ { "oauth2": [ "meals.read" ] } ], "parameters": [ { "name": "mealId", "in": "path", "required": true, "description": "Meal identifier.", "schema": { "type": "string" }, "example": "1042" } ], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "meal_id", "grade", "classifications", "classified_at" ], "properties": { "meal_id": { "type": "string" }, "grade": { "type": "string" }, "classifications": { "type": "array", "items": { "type": "object", "required": [ "key", "label" ], "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "additionalProperties": false } }, "classified_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "example": { "meal_id": "1042", "grade": "A", "classifications": [ { "key": "high_protein", "label": "High protein" } ], "classified_at": "2026-06-29T18:30:08.000Z" } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "404": { "description": "The requested resource does not exist or is not visible to this credential.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "not_found", "message": "Resource not found.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "meals.grade.read", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "meals.grade.read", "x-foodabcs-price-cents": 0.5, "x-foodabcs-tier2-price-cents": 1, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/meals/grades": { "get": { "operationId": "get_meals_grades_read", "summary": "List meal grades", "description": "Lists meal identifiers, timestamps, and grades for a date range.", "tags": [ "Meals" ], "security": [ { "oauth2": [ "meals.read" ] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Inclusive ISO 8601 range start.", "schema": { "type": "string" }, "example": "2026-06-01T00:00:00Z" }, { "name": "to", "in": "query", "required": false, "description": "Inclusive ISO 8601 range end.", "schema": { "type": "string" }, "example": "2026-06-30T23:59:59Z" }, { "name": "limit", "in": "query", "required": false, "description": "Number of records to return (1–100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "example": 25 }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque next_cursor from the previous response.", "schema": { "type": "string" }, "example": "MjAyNi0wNi0yOVQxODozMDowMC4wMDBafDEwNDI" } ], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "timestamp", "meal_score" ], "properties": { "id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "meal_score": { "type": "string" } }, "additionalProperties": false } }, "next_cursor": { "type": "string" } }, "additionalProperties": false }, "example": { "data": [ { "id": "1042", "timestamp": "2026-06-29T18:30:00.000Z", "meal_score": "A" } ], "next_cursor": "MjAyNi0wNi0yOFQxMzowMDowMC4wMDBafDEwNDI" } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "meals.grades.read", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "meals.grades.read", "x-foodabcs-price-cents": 0.5, "x-foodabcs-tier2-price-cents": 1, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/meals/{mealId}/expanded": { "get": { "operationId": "get_meals_expanded_read", "summary": "Get expanded meal data", "description": "Returns a meal with nutrient warehouse rows and normalized ingredient-history records.", "tags": [ "Meals" ], "security": [ { "oauth2": [ "meals.read" ] } ], "parameters": [ { "name": "mealId", "in": "path", "required": true, "description": "Meal identifier.", "schema": { "type": "string" }, "example": "1042" } ], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "user_id", "timestamp", "name", "ingredients", "total_calories", "meal_score", "is_favorite", "meal_classifications", "meal_classification_version", "meal_classified_at", "meal_behavior_events", "meal_behavior_version", "meal_behavior_detected_at", "source_app_id", "nutrients" ], "properties": { "id": { "type": "string" }, "user_id": { "type": "string", "format": "uuid" }, "timestamp": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "ingredients": { "type": "array", "items": { "type": "object", "required": [ "id", "meal_id", "meal_timestamp", "meal_slot", "ingredient_position", "source_food_id", "display_name", "brand_name", "barcode", "selected_amount", "selected_unit", "entry_source", "nutrition_snapshot", "search_keywords", "created_at", "source_app_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "meal_id": { "type": "string" }, "meal_timestamp": { "type": "string", "format": "date-time" }, "meal_slot": { "type": "string" }, "ingredient_position": { "type": "integer" }, "source_food_id": { "type": "string" }, "display_name": { "type": "string" }, "brand_name": { "type": "string" }, "barcode": { "type": "string" }, "selected_amount": { "type": "string" }, "selected_unit": { "type": "string" }, "entry_source": { "type": "string" }, "nutrition_snapshot": { "type": "object", "required": [ "calories", "protein" ], "properties": { "calories": { "type": "integer" }, "protein": { "type": "integer" } }, "additionalProperties": false }, "search_keywords": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "total_calories": { "type": "string" }, "meal_score": { "type": "string" }, "is_favorite": { "type": "boolean" }, "meal_classifications": { "type": "array", "items": { "type": "object", "required": [ "key", "label" ], "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "additionalProperties": false } }, "meal_classification_version": { "type": "string" }, "meal_classified_at": { "type": "string", "format": "date-time" }, "meal_behavior_events": { "type": "array", "items": {} }, "meal_behavior_version": { "type": "string" }, "meal_behavior_detected_at": { "type": "string", "format": "date-time" }, "source_app_id": { "type": "string", "format": "uuid" }, "nutrients": { "type": "array", "items": { "type": "object", "required": [ "meal_id", "nutrient_key", "nutrient_name", "nutrient_unit", "nutrient_amount", "created_at" ], "properties": { "meal_id": { "type": "string" }, "nutrient_key": { "type": "string" }, "nutrient_name": { "type": "string" }, "nutrient_unit": { "type": "string" }, "nutrient_amount": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } }, "additionalProperties": false }, "example": { "id": "1042", "user_id": "6bc72c8d-6d8a-4e85-9cbb-c02d19dca12f", "timestamp": "2026-06-29T18:30:00.000Z", "name": "Chicken quinoa bowl", "ingredients": [ { "id": "b035d85f-86a3-4f2f-b231-a4b1a2488f73", "meal_id": "1042", "meal_timestamp": "2026-06-29T18:30:00.000Z", "meal_slot": "dinner", "ingredient_position": 0, "source_food_id": "food_123", "display_name": "Grilled chicken breast", "brand_name": "FoodABCs", "barcode": "012345678905", "selected_amount": "5", "selected_unit": "oz", "entry_source": "api", "nutrition_snapshot": { "calories": 234, "protein": 44 }, "search_keywords": [ "chicken", "grilled" ], "created_at": "2026-06-29T18:30:08.000Z", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } ], "total_calories": "612", "meal_score": "A", "is_favorite": false, "meal_classifications": [ { "key": "high_protein", "label": "High protein" } ], "meal_classification_version": "v1", "meal_classified_at": "2026-06-29T18:30:08.000Z", "meal_behavior_events": [], "meal_behavior_version": "v1", "meal_behavior_detected_at": "2026-06-29T18:30:08.000Z", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7", "nutrients": [ { "meal_id": "1042", "nutrient_key": "protein", "nutrient_name": "Protein", "nutrient_unit": "g", "nutrient_amount": "48", "created_at": "2026-06-29T18:30:08.000Z" } ] } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "404": { "description": "The requested resource does not exist or is not visible to this credential.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "not_found", "message": "Resource not found.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "meals.expanded.read", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "meals.expanded.read", "x-foodabcs-price-cents": 0.5, "x-foodabcs-tier2-price-cents": 1, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/meals/insights": { "get": { "operationId": "get_meals_insights", "summary": "Get meal insights", "description": "Aggregates meal grades, classifications, nutrients, and food-behavior signals over a date range.", "tags": [ "Meals" ], "security": [ { "oauth2": [ "meals.read" ] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Inclusive ISO 8601 range start.", "schema": { "type": "string" }, "example": "2026-06-01T00:00:00Z" }, { "name": "to", "in": "query", "required": false, "description": "Inclusive ISO 8601 range end.", "schema": { "type": "string" }, "example": "2026-06-30T23:59:59Z" } ], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "period", "meal_count", "average_calories", "grade_distribution", "top_classifications", "nutrient_daily_averages", "behavior_summary" ], "properties": { "period": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "meal_count": { "type": "integer" }, "average_calories": { "type": "string" }, "grade_distribution": { "type": "array", "items": { "type": "object", "required": [ "grade", "count" ], "properties": { "grade": { "type": "string" }, "count": { "type": "integer" } }, "additionalProperties": false } }, "top_classifications": { "type": "array", "items": { "type": "object", "required": [ "classification", "count" ], "properties": { "classification": { "type": "string" }, "count": { "type": "integer" } }, "additionalProperties": false } }, "nutrient_daily_averages": { "type": "object", "required": [ "protein", "fiber", "sodium" ], "properties": { "protein": { "type": "string" }, "fiber": { "type": "string" }, "sodium": { "type": "string" } }, "additionalProperties": false }, "behavior_summary": { "type": "array", "items": { "type": "object", "required": [ "event_type", "count" ], "properties": { "event_type": { "type": "string" }, "count": { "type": "integer" } }, "additionalProperties": false } } }, "additionalProperties": false }, "example": { "period": { "from": "2026-06-01T00:00:00.000Z", "to": "2026-06-30T23:59:59.000Z" }, "meal_count": 62, "average_calories": "548.7", "grade_distribution": [ { "grade": "A", "count": 29 }, { "grade": "B", "count": 21 } ], "top_classifications": [ { "classification": "high_protein", "count": 18 } ], "nutrient_daily_averages": { "protein": "94.2", "fiber": "24.6", "sodium": "1880" }, "behavior_summary": [ { "event_type": "late_night_eating", "count": 3 } ] } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "meals.insights", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "meals.insights", "x-foodabcs-price-cents": 2, "x-foodabcs-tier2-price-cents": 4, "x-foodabcs-infra-cost-cents": 0.1 } }, "/v1/favorite-meals": { "get": { "operationId": "get_favorites_read", "summary": "List favorite meals", "description": "Lists favorite meal templates visible to the user.", "tags": [ "Meals" ], "security": [ { "oauth2": [ "meals.read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Number of records to return (1–100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "example": 25 } ], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "user_id", "created_at", "name", "ingredients", "total_calories", "meal_score", "meal_classifications", "meal_classification_version", "meal_classified_at", "meal_behavior_events", "meal_behavior_version", "meal_behavior_detected_at", "source_app_id" ], "properties": { "id": { "type": "string" }, "user_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "ingredients": { "type": "array", "items": { "type": "object", "required": [ "name", "amount", "unit", "nutrition" ], "properties": { "name": { "type": "string" }, "amount": { "type": "integer" }, "unit": { "type": "string" }, "nutrition": { "type": "object", "required": [ "nutrients" ], "properties": { "nutrients": { "type": "array", "items": { "type": "object", "required": [ "name", "amount", "unit" ], "properties": { "name": { "type": "string" }, "amount": { "type": "integer" }, "unit": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } }, "additionalProperties": false } }, "total_calories": { "type": "string" }, "meal_score": { "type": "string" }, "meal_classifications": { "type": "array", "items": { "type": "object", "required": [ "key", "label" ], "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "additionalProperties": false } }, "meal_classification_version": { "type": "string" }, "meal_classified_at": { "type": "string", "format": "date-time" }, "meal_behavior_events": { "type": "array", "items": {} }, "meal_behavior_version": { "type": "string" }, "meal_behavior_detected_at": { "type": "string", "format": "date-time" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } } }, "additionalProperties": false }, "example": { "data": [ { "id": "1042", "user_id": "6bc72c8d-6d8a-4e85-9cbb-c02d19dca12f", "created_at": "2026-06-20T12:00:00.000Z", "name": "Chicken quinoa bowl", "ingredients": [ { "name": "Grilled chicken breast", "amount": 5, "unit": "oz", "nutrition": { "nutrients": [ { "name": "Calories", "amount": 234, "unit": "kcal" }, { "name": "Protein", "amount": 44, "unit": "g" }, { "name": "Carbohydrates", "amount": 0, "unit": "g" }, { "name": "Fat", "amount": 5, "unit": "g" } ] } }, { "name": "Cooked quinoa", "amount": 1, "unit": "cup", "nutrition": { "nutrients": [ { "name": "Calories", "amount": 222, "unit": "kcal" }, { "name": "Protein", "amount": 8, "unit": "g" }, { "name": "Carbohydrates", "amount": 39, "unit": "g" }, { "name": "Fat", "amount": 4, "unit": "g" } ] } } ], "total_calories": "612", "meal_score": "A", "meal_classifications": [ { "key": "high_protein", "label": "High protein" } ], "meal_classification_version": "v1", "meal_classified_at": "2026-06-20T12:00:08.000Z", "meal_behavior_events": [], "meal_behavior_version": "v1", "meal_behavior_detected_at": "2026-06-20T12:00:08.000Z", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } ] } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "favorites.read", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "favorites.read", "x-foodabcs-price-cents": 0.5, "x-foodabcs-tier2-price-cents": 1, "x-foodabcs-infra-cost-cents": 0.02 }, "post": { "operationId": "post_favorites_write", "summary": "Create a favorite meal", "description": "Creates an API-owned favorite template and returns its calculated meal grade.", "tags": [ "Meals" ], "security": [ { "oauth2": [ "meals.write" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key that safely replays the first response when the same request body is retried.", "schema": { "type": "string" }, "example": "61d6c26b-4f60-4a03-a8df-c65bf86a6b64" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ingredients" ], "properties": { "name": { "type": "string" }, "ingredients": { "type": "array", "items": { "type": "object", "required": [ "name", "amount", "unit", "nutrition" ], "properties": { "name": { "type": "string" }, "amount": { "type": "integer" }, "unit": { "type": "string" }, "nutrition": { "type": "object", "required": [ "nutrients" ], "properties": { "nutrients": { "type": "array", "items": { "type": "object", "required": [ "name", "amount", "unit" ], "properties": { "name": { "type": "string" }, "amount": { "type": "integer" }, "unit": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } }, "additionalProperties": false } }, "total_calories": { "type": "integer" } }, "additionalProperties": false }, "example": { "name": "Chicken quinoa bowl", "ingredients": [ { "name": "Grilled chicken breast", "amount": 5, "unit": "oz", "nutrition": { "nutrients": [ { "name": "Calories", "amount": 234, "unit": "kcal" }, { "name": "Protein", "amount": 44, "unit": "g" }, { "name": "Carbohydrates", "amount": 0, "unit": "g" }, { "name": "Fat", "amount": 5, "unit": "g" } ] } }, { "name": "Cooked quinoa", "amount": 1, "unit": "cup", "nutrition": { "nutrients": [ { "name": "Calories", "amount": 222, "unit": "kcal" }, { "name": "Protein", "amount": 8, "unit": "g" }, { "name": "Carbohydrates", "amount": 39, "unit": "g" }, { "name": "Fat", "amount": 4, "unit": "g" } ] } } ], "total_calories": 612 } } } }, "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "user_id", "created_at", "name", "ingredients", "total_calories", "meal_score", "meal_classifications", "meal_classification_version", "meal_classified_at", "meal_behavior_events", "meal_behavior_version", "meal_behavior_detected_at", "source_app_id" ], "properties": { "id": { "type": "string" }, "user_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "ingredients": { "type": "array", "items": { "type": "object", "required": [ "name", "amount", "unit", "nutrition" ], "properties": { "name": { "type": "string" }, "amount": { "type": "integer" }, "unit": { "type": "string" }, "nutrition": { "type": "object", "required": [ "nutrients" ], "properties": { "nutrients": { "type": "array", "items": { "type": "object", "required": [ "name", "amount", "unit" ], "properties": { "name": { "type": "string" }, "amount": { "type": "integer" }, "unit": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } }, "additionalProperties": false } }, "total_calories": { "type": "string" }, "meal_score": { "type": "string" }, "meal_classifications": { "type": "array", "items": { "type": "object", "required": [ "key", "label" ], "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "additionalProperties": false } }, "meal_classification_version": { "type": "string" }, "meal_classified_at": { "type": "string", "format": "date-time" }, "meal_behavior_events": { "type": "array", "items": {} }, "meal_behavior_version": { "type": "string" }, "meal_behavior_detected_at": { "type": "string", "format": "date-time" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, "example": { "id": "1042", "user_id": "6bc72c8d-6d8a-4e85-9cbb-c02d19dca12f", "created_at": "2026-06-20T12:00:00.000Z", "name": "Chicken quinoa bowl", "ingredients": [ { "name": "Grilled chicken breast", "amount": 5, "unit": "oz", "nutrition": { "nutrients": [ { "name": "Calories", "amount": 234, "unit": "kcal" }, { "name": "Protein", "amount": 44, "unit": "g" }, { "name": "Carbohydrates", "amount": 0, "unit": "g" }, { "name": "Fat", "amount": 5, "unit": "g" } ] } }, { "name": "Cooked quinoa", "amount": 1, "unit": "cup", "nutrition": { "nutrients": [ { "name": "Calories", "amount": 222, "unit": "kcal" }, { "name": "Protein", "amount": 8, "unit": "g" }, { "name": "Carbohydrates", "amount": 39, "unit": "g" }, { "name": "Fat", "amount": 4, "unit": "g" } ] } } ], "total_calories": "612", "meal_score": "A", "meal_classifications": [ { "key": "high_protein", "label": "High protein" } ], "meal_classification_version": "v1", "meal_classified_at": "2026-06-20T12:00:08.000Z", "meal_behavior_events": [], "meal_behavior_version": "v1", "meal_behavior_detected_at": "2026-06-20T12:00:08.000Z", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "409": { "description": "The Idempotency-Key was already used with a different request body.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "idempotency_conflict", "message": "Idempotency-Key was already used with a different request.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "favorites.write", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "favorites.write", "x-foodabcs-price-cents": 1, "x-foodabcs-tier2-price-cents": 2, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/favorite-meals/{favoriteId}": { "delete": { "operationId": "delete_favorites_delete", "summary": "Delete a favorite meal", "description": "Deletes an API-owned favorite template.", "tags": [ "Meals" ], "security": [ { "oauth2": [ "meals.write" ] } ], "parameters": [ { "name": "favoriteId", "in": "path", "required": true, "description": "Favorite meal identifier.", "schema": { "type": "string" }, "example": "1042" } ], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted", "id" ], "properties": { "deleted": { "type": "boolean" }, "id": { "type": "string" } }, "additionalProperties": false }, "example": { "deleted": true, "id": "1042" } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "404": { "description": "The requested resource does not exist or is not visible to this credential.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "not_found", "message": "Resource not found.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "favorites.delete", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "favorites.delete", "x-foodabcs-price-cents": 1, "x-foodabcs-tier2-price-cents": 2, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/workouts": { "post": { "operationId": "post_workouts_write", "summary": "Create a workout", "description": "Creates an API workout. Supplying the same original_id again returns the existing workout with deduplicated true.", "tags": [ "Workouts" ], "security": [ { "oauth2": [ "workouts.write" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key that safely replays the first response when the same request body is retried.", "schema": { "type": "string" }, "example": "61d6c26b-4f60-4a03-a8df-c65bf86a6b64" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "start_time", "end_time", "duration_minutes", "calories_burned" ], "properties": { "type": { "type": "string" }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "duration_minutes": { "type": "integer" }, "calories_burned": { "type": "integer" }, "average_heart_rate": { "type": "integer" }, "distance_meters": { "type": "integer" }, "steps": { "type": "integer" }, "original_id": { "type": "string" }, "raw_type": { "type": "string" } }, "additionalProperties": false }, "example": { "type": "Outdoor Run", "start_time": "2026-06-28T13:00:00.000Z", "end_time": "2026-06-28T13:32:00.000Z", "duration_minutes": 32, "calories_burned": 348, "average_heart_rate": 151, "distance_meters": 5020, "steps": 6234, "original_id": "run-2026-06-28", "raw_type": "running" } } } }, "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "user_id", "type", "start_time", "end_time", "duration_minutes", "calories_burned", "average_heart_rate", "min_heart_rate", "max_heart_rate", "heart_rate_samples", "distance_meters", "steps", "elevation_gain_meters", "average_speed_mps", "max_speed_mps", "average_power_watts", "average_cadence", "calorie_samples", "provider", "original_id", "grade", "synced_at", "created_at", "updated_at", "raw_type", "source_app_id" ], "properties": { "id": { "type": "string" }, "user_id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "duration_minutes": { "type": "integer" }, "calories_burned": { "type": "integer" }, "average_heart_rate": { "type": "integer" }, "min_heart_rate": { "type": "integer" }, "max_heart_rate": { "type": "integer" }, "heart_rate_samples": { "type": "array", "items": { "type": "object", "required": [ "offset_seconds", "bpm" ], "properties": { "offset_seconds": { "type": "integer" }, "bpm": { "type": "integer" } }, "additionalProperties": false } }, "distance_meters": { "type": "integer" }, "steps": { "type": "integer" }, "elevation_gain_meters": { "type": "integer" }, "average_speed_mps": { "type": "number" }, "max_speed_mps": { "type": "number" }, "average_power_watts": { "type": "integer" }, "average_cadence": { "type": "integer" }, "calorie_samples": { "type": "array", "items": { "type": "object", "required": [ "offset_seconds", "calories" ], "properties": { "offset_seconds": { "type": "integer" }, "calories": { "type": "integer" } }, "additionalProperties": false } }, "provider": { "type": "string" }, "original_id": { "type": "string" }, "grade": { "type": "string" }, "synced_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "raw_type": { "type": "string" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, "example": { "id": "api_3a99efb4-6ac9-44f7-8a0c-663a8ee6464f", "user_id": "6bc72c8d-6d8a-4e85-9cbb-c02d19dca12f", "type": "Outdoor Run", "start_time": "2026-06-28T13:00:00.000Z", "end_time": "2026-06-28T13:32:00.000Z", "duration_minutes": 32, "calories_burned": 348, "average_heart_rate": 151, "min_heart_rate": 104, "max_heart_rate": 174, "heart_rate_samples": [ { "offset_seconds": 60, "bpm": 132 } ], "distance_meters": 5020, "steps": 6234, "elevation_gain_meters": 41, "average_speed_mps": 2.61, "max_speed_mps": 3.9, "average_power_watts": 248, "average_cadence": 168, "calorie_samples": [ { "offset_seconds": 300, "calories": 54 } ], "provider": "api", "original_id": "run-2026-06-28", "grade": "A", "synced_at": "2026-06-28T13:33:00.000Z", "created_at": "2026-06-28T13:33:00.000Z", "updated_at": "2026-06-28T13:33:00.000Z", "raw_type": "running", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "409": { "description": "The Idempotency-Key was already used with a different request body.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "idempotency_conflict", "message": "Idempotency-Key was already used with a different request.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "workouts.write", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "workouts.write", "x-foodabcs-price-cents": 1, "x-foodabcs-tier2-price-cents": 2, "x-foodabcs-infra-cost-cents": 0.02 }, "get": { "operationId": "get_workouts_read", "summary": "List workouts", "description": "Lists workouts across all sources in reverse chronological order.", "tags": [ "Workouts" ], "security": [ { "oauth2": [ "workouts.read" ] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Inclusive ISO 8601 range start.", "schema": { "type": "string" }, "example": "2026-06-01T00:00:00Z" }, { "name": "to", "in": "query", "required": false, "description": "Inclusive ISO 8601 range end.", "schema": { "type": "string" }, "example": "2026-06-30T23:59:59Z" }, { "name": "limit", "in": "query", "required": false, "description": "Number of records to return (1–100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "example": 25 }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque next_cursor from the previous response.", "schema": { "type": "string" }, "example": "MjAyNi0wNi0yOVQxODozMDowMC4wMDBafDEwNDI" } ], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "user_id", "type", "start_time", "end_time", "duration_minutes", "calories_burned", "average_heart_rate", "min_heart_rate", "max_heart_rate", "heart_rate_samples", "distance_meters", "steps", "elevation_gain_meters", "average_speed_mps", "max_speed_mps", "average_power_watts", "average_cadence", "calorie_samples", "provider", "original_id", "grade", "synced_at", "created_at", "updated_at", "raw_type", "source_app_id" ], "properties": { "id": { "type": "string" }, "user_id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "duration_minutes": { "type": "integer" }, "calories_burned": { "type": "integer" }, "average_heart_rate": { "type": "integer" }, "min_heart_rate": { "type": "integer" }, "max_heart_rate": { "type": "integer" }, "heart_rate_samples": { "type": "array", "items": { "type": "object", "required": [ "offset_seconds", "bpm" ], "properties": { "offset_seconds": { "type": "integer" }, "bpm": { "type": "integer" } }, "additionalProperties": false } }, "distance_meters": { "type": "integer" }, "steps": { "type": "integer" }, "elevation_gain_meters": { "type": "integer" }, "average_speed_mps": { "type": "number" }, "max_speed_mps": { "type": "number" }, "average_power_watts": { "type": "integer" }, "average_cadence": { "type": "integer" }, "calorie_samples": { "type": "array", "items": { "type": "object", "required": [ "offset_seconds", "calories" ], "properties": { "offset_seconds": { "type": "integer" }, "calories": { "type": "integer" } }, "additionalProperties": false } }, "provider": { "type": "string" }, "original_id": { "type": "string" }, "grade": { "type": "string" }, "synced_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "raw_type": { "type": "string" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "next_cursor": { "type": "string" } }, "additionalProperties": false }, "example": { "data": [ { "id": "api_3a99efb4-6ac9-44f7-8a0c-663a8ee6464f", "user_id": "6bc72c8d-6d8a-4e85-9cbb-c02d19dca12f", "type": "Outdoor Run", "start_time": "2026-06-28T13:00:00.000Z", "end_time": "2026-06-28T13:32:00.000Z", "duration_minutes": 32, "calories_burned": 348, "average_heart_rate": 151, "min_heart_rate": 104, "max_heart_rate": 174, "heart_rate_samples": [ { "offset_seconds": 60, "bpm": 132 } ], "distance_meters": 5020, "steps": 6234, "elevation_gain_meters": 41, "average_speed_mps": 2.61, "max_speed_mps": 3.9, "average_power_watts": 248, "average_cadence": 168, "calorie_samples": [ { "offset_seconds": 300, "calories": 54 } ], "provider": "api", "original_id": "run-2026-06-28", "grade": "A", "synced_at": "2026-06-28T13:33:00.000Z", "created_at": "2026-06-28T13:33:00.000Z", "updated_at": "2026-06-28T13:33:00.000Z", "raw_type": "running", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } ], "next_cursor": "MjAyNi0wNi0yOFQxMzowMDowMC4wMDBafDEwNDI" } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "workouts.read", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "workouts.read", "x-foodabcs-price-cents": 0.5, "x-foodabcs-tier2-price-cents": 1, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/workouts/{workoutId}": { "get": { "operationId": "get_workouts_read_one", "summary": "Get a workout", "description": "Returns one workout visible to the current user.", "tags": [ "Workouts" ], "security": [ { "oauth2": [ "workouts.read" ] } ], "parameters": [ { "name": "workoutId", "in": "path", "required": true, "description": "Workout identifier.", "schema": { "type": "string" }, "example": "api_3a99efb4-6ac9-44f7-8a0c-663a8ee6464f" } ], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "user_id", "type", "start_time", "end_time", "duration_minutes", "calories_burned", "average_heart_rate", "min_heart_rate", "max_heart_rate", "heart_rate_samples", "distance_meters", "steps", "elevation_gain_meters", "average_speed_mps", "max_speed_mps", "average_power_watts", "average_cadence", "calorie_samples", "provider", "original_id", "grade", "synced_at", "created_at", "updated_at", "raw_type", "source_app_id" ], "properties": { "id": { "type": "string" }, "user_id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "duration_minutes": { "type": "integer" }, "calories_burned": { "type": "integer" }, "average_heart_rate": { "type": "integer" }, "min_heart_rate": { "type": "integer" }, "max_heart_rate": { "type": "integer" }, "heart_rate_samples": { "type": "array", "items": { "type": "object", "required": [ "offset_seconds", "bpm" ], "properties": { "offset_seconds": { "type": "integer" }, "bpm": { "type": "integer" } }, "additionalProperties": false } }, "distance_meters": { "type": "integer" }, "steps": { "type": "integer" }, "elevation_gain_meters": { "type": "integer" }, "average_speed_mps": { "type": "number" }, "max_speed_mps": { "type": "number" }, "average_power_watts": { "type": "integer" }, "average_cadence": { "type": "integer" }, "calorie_samples": { "type": "array", "items": { "type": "object", "required": [ "offset_seconds", "calories" ], "properties": { "offset_seconds": { "type": "integer" }, "calories": { "type": "integer" } }, "additionalProperties": false } }, "provider": { "type": "string" }, "original_id": { "type": "string" }, "grade": { "type": "string" }, "synced_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "raw_type": { "type": "string" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, "example": { "id": "api_3a99efb4-6ac9-44f7-8a0c-663a8ee6464f", "user_id": "6bc72c8d-6d8a-4e85-9cbb-c02d19dca12f", "type": "Outdoor Run", "start_time": "2026-06-28T13:00:00.000Z", "end_time": "2026-06-28T13:32:00.000Z", "duration_minutes": 32, "calories_burned": 348, "average_heart_rate": 151, "min_heart_rate": 104, "max_heart_rate": 174, "heart_rate_samples": [ { "offset_seconds": 60, "bpm": 132 } ], "distance_meters": 5020, "steps": 6234, "elevation_gain_meters": 41, "average_speed_mps": 2.61, "max_speed_mps": 3.9, "average_power_watts": 248, "average_cadence": 168, "calorie_samples": [ { "offset_seconds": 300, "calories": 54 } ], "provider": "api", "original_id": "run-2026-06-28", "grade": "A", "synced_at": "2026-06-28T13:33:00.000Z", "created_at": "2026-06-28T13:33:00.000Z", "updated_at": "2026-06-28T13:33:00.000Z", "raw_type": "running", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "404": { "description": "The requested resource does not exist or is not visible to this credential.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "not_found", "message": "Resource not found.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "workouts.read.one", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "workouts.read.one", "x-foodabcs-price-cents": 0.5, "x-foodabcs-tier2-price-cents": 1, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/workouts/{workoutId}/grade": { "get": { "operationId": "get_workouts_grade_read", "summary": "Get a workout grade", "description": "Returns the calculated grade for one workout.", "tags": [ "Workouts" ], "security": [ { "oauth2": [ "workouts.read" ] } ], "parameters": [ { "name": "workoutId", "in": "path", "required": true, "description": "Workout identifier.", "schema": { "type": "string" }, "example": "api_3a99efb4-6ac9-44f7-8a0c-663a8ee6464f" } ], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "workout_id", "grade" ], "properties": { "workout_id": { "type": "string" }, "grade": { "type": "string" } }, "additionalProperties": false }, "example": { "workout_id": "api_3a99efb4-6ac9-44f7-8a0c-663a8ee6464f", "grade": "A" } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "404": { "description": "The requested resource does not exist or is not visible to this credential.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "not_found", "message": "Resource not found.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "workouts.grade.read", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "workouts.grade.read", "x-foodabcs-price-cents": 0.5, "x-foodabcs-tier2-price-cents": 1, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/workouts/grades": { "get": { "operationId": "get_workouts_grades_read", "summary": "List workout grades", "description": "Lists workout identifiers, start times, and grades for a date range.", "tags": [ "Workouts" ], "security": [ { "oauth2": [ "workouts.read" ] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Inclusive ISO 8601 range start.", "schema": { "type": "string" }, "example": "2026-06-01T00:00:00Z" }, { "name": "to", "in": "query", "required": false, "description": "Inclusive ISO 8601 range end.", "schema": { "type": "string" }, "example": "2026-06-30T23:59:59Z" }, { "name": "limit", "in": "query", "required": false, "description": "Number of records to return (1–100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "example": 25 }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque next_cursor from the previous response.", "schema": { "type": "string" }, "example": "MjAyNi0wNi0yOVQxODozMDowMC4wMDBafDEwNDI" } ], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "start_time", "grade" ], "properties": { "id": { "type": "string" }, "start_time": { "type": "string", "format": "date-time" }, "grade": { "type": "string" } }, "additionalProperties": false } }, "next_cursor": { "type": "string" } }, "additionalProperties": false }, "example": { "data": [ { "id": "api_3a99efb4-6ac9-44f7-8a0c-663a8ee6464f", "start_time": "2026-06-28T13:00:00.000Z", "grade": "A" } ], "next_cursor": "MjAyNi0wNi0yOFQxMzowMDowMC4wMDBafDEwNDI" } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "workouts.grades.read", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "workouts.grades.read", "x-foodabcs-price-cents": 0.5, "x-foodabcs-tier2-price-cents": 1, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/workouts/{workoutId}/expanded": { "get": { "operationId": "get_workouts_expanded_read", "summary": "Get expanded workout data", "description": "Returns the complete workout, including heart-rate and calorie sample arrays when recorded.", "tags": [ "Workouts" ], "security": [ { "oauth2": [ "workouts.read" ] } ], "parameters": [ { "name": "workoutId", "in": "path", "required": true, "description": "Workout identifier.", "schema": { "type": "string" }, "example": "api_3a99efb4-6ac9-44f7-8a0c-663a8ee6464f" } ], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "user_id", "type", "start_time", "end_time", "duration_minutes", "calories_burned", "average_heart_rate", "min_heart_rate", "max_heart_rate", "heart_rate_samples", "distance_meters", "steps", "elevation_gain_meters", "average_speed_mps", "max_speed_mps", "average_power_watts", "average_cadence", "calorie_samples", "provider", "original_id", "grade", "synced_at", "created_at", "updated_at", "raw_type", "source_app_id" ], "properties": { "id": { "type": "string" }, "user_id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "duration_minutes": { "type": "integer" }, "calories_burned": { "type": "integer" }, "average_heart_rate": { "type": "integer" }, "min_heart_rate": { "type": "integer" }, "max_heart_rate": { "type": "integer" }, "heart_rate_samples": { "type": "array", "items": { "type": "object", "required": [ "offset_seconds", "bpm" ], "properties": { "offset_seconds": { "type": "integer" }, "bpm": { "type": "integer" } }, "additionalProperties": false } }, "distance_meters": { "type": "integer" }, "steps": { "type": "integer" }, "elevation_gain_meters": { "type": "integer" }, "average_speed_mps": { "type": "number" }, "max_speed_mps": { "type": "number" }, "average_power_watts": { "type": "integer" }, "average_cadence": { "type": "integer" }, "calorie_samples": { "type": "array", "items": { "type": "object", "required": [ "offset_seconds", "calories" ], "properties": { "offset_seconds": { "type": "integer" }, "calories": { "type": "integer" } }, "additionalProperties": false } }, "provider": { "type": "string" }, "original_id": { "type": "string" }, "grade": { "type": "string" }, "synced_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "raw_type": { "type": "string" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, "example": { "id": "api_3a99efb4-6ac9-44f7-8a0c-663a8ee6464f", "user_id": "6bc72c8d-6d8a-4e85-9cbb-c02d19dca12f", "type": "Outdoor Run", "start_time": "2026-06-28T13:00:00.000Z", "end_time": "2026-06-28T13:32:00.000Z", "duration_minutes": 32, "calories_burned": 348, "average_heart_rate": 151, "min_heart_rate": 104, "max_heart_rate": 174, "heart_rate_samples": [ { "offset_seconds": 60, "bpm": 132 } ], "distance_meters": 5020, "steps": 6234, "elevation_gain_meters": 41, "average_speed_mps": 2.61, "max_speed_mps": 3.9, "average_power_watts": 248, "average_cadence": 168, "calorie_samples": [ { "offset_seconds": 300, "calories": 54 } ], "provider": "api", "original_id": "run-2026-06-28", "grade": "A", "synced_at": "2026-06-28T13:33:00.000Z", "created_at": "2026-06-28T13:33:00.000Z", "updated_at": "2026-06-28T13:33:00.000Z", "raw_type": "running", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "404": { "description": "The requested resource does not exist or is not visible to this credential.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "not_found", "message": "Resource not found.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "workouts.expanded.read", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "workouts.expanded.read", "x-foodabcs-price-cents": 0.5, "x-foodabcs-tier2-price-cents": 1, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/workouts/insights": { "get": { "operationId": "get_workouts_insights", "summary": "Get workout insights", "description": "Aggregates volume, calories, heart rate, grades, and workout types over a date range.", "tags": [ "Workouts" ], "security": [ { "oauth2": [ "workouts.read" ] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Inclusive ISO 8601 range start.", "schema": { "type": "string" }, "example": "2026-06-01T00:00:00Z" }, { "name": "to", "in": "query", "required": false, "description": "Inclusive ISO 8601 range end.", "schema": { "type": "string" }, "example": "2026-06-30T23:59:59Z" } ], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "period", "workout_count", "total_minutes", "total_calories", "grade_distribution", "by_type", "avg_heart_rate" ], "properties": { "period": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "workout_count": { "type": "integer" }, "total_minutes": { "type": "integer" }, "total_calories": { "type": "string" }, "grade_distribution": { "type": "array", "items": { "type": "object", "required": [ "grade", "count" ], "properties": { "grade": { "type": "string" }, "count": { "type": "integer" } }, "additionalProperties": false } }, "by_type": { "type": "array", "items": { "type": "object", "required": [ "type", "count" ], "properties": { "type": { "type": "string" }, "count": { "type": "integer" } }, "additionalProperties": false } }, "avg_heart_rate": { "type": "string" } }, "additionalProperties": false }, "example": { "period": { "from": "2026-06-01T00:00:00.000Z", "to": "2026-06-30T23:59:59.000Z" }, "workout_count": 18, "total_minutes": 624, "total_calories": "6410", "grade_distribution": [ { "grade": "A", "count": 10 }, { "grade": "B", "count": 6 } ], "by_type": [ { "type": "Outdoor Run", "count": 7 } ], "avg_heart_rate": "143.2" } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "workouts.insights", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "workouts.insights", "x-foodabcs-price-cents": 2, "x-foodabcs-tier2-price-cents": 4, "x-foodabcs-infra-cost-cents": 0.1 } }, "/v1/moods": { "post": { "operationId": "post_moods_write", "summary": "Create a mood entry", "description": "Creates an API-owned mood entry. mood_value must be an integer from 1 (Very Low) through 5 (Great).", "tags": [ "Mood" ], "security": [ { "oauth2": [ "moods.write" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key that safely replays the first response when the same request body is retried.", "schema": { "type": "string" }, "example": "61d6c26b-4f60-4a03-a8df-c65bf86a6b64" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mood_value", "local_entry_date", "timezone" ], "properties": { "mood_value": { "type": "integer" }, "note": { "type": "string" }, "local_entry_date": { "type": "string", "format": "date" }, "timezone": { "type": "string" }, "recorded_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "example": { "mood_value": 4, "note": "Good energy after lunch.", "local_entry_date": "2026-06-29", "timezone": "America/Denver", "recorded_at": "2026-06-29T20:15:00Z" } } } }, "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "user_id", "mood_value", "mood_key", "mood_label", "mood_emoji", "note", "source", "meal_log_id", "recorded_at", "local_entry_date", "timezone", "created_at", "source_app_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "mood_value": { "type": "integer" }, "mood_key": { "type": "string" }, "mood_label": { "type": "string" }, "mood_emoji": { "type": "string" }, "note": { "type": "string" }, "source": { "type": "string" }, "meal_log_id": { "type": "string" }, "recorded_at": { "type": "string", "format": "date-time" }, "local_entry_date": { "type": "string", "format": "date" }, "timezone": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, "example": { "id": "7fd304e1-7823-4352-a855-33d0da83bf28", "user_id": "6bc72c8d-6d8a-4e85-9cbb-c02d19dca12f", "mood_value": 4, "mood_key": "good", "mood_label": "Good", "mood_emoji": "🙂", "note": "Good energy after lunch.", "source": "api", "meal_log_id": "1042", "recorded_at": "2026-06-29T20:15:00.000Z", "local_entry_date": "2026-06-29", "timezone": "America/Denver", "created_at": "2026-06-29T20:15:01.000Z", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "409": { "description": "The Idempotency-Key was already used with a different request body.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "idempotency_conflict", "message": "Idempotency-Key was already used with a different request.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "moods.write", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "moods.write", "x-foodabcs-price-cents": 1, "x-foodabcs-tier2-price-cents": 2, "x-foodabcs-infra-cost-cents": 0.02 }, "get": { "operationId": "get_moods_read", "summary": "List mood entries", "description": "Lists mood entries in reverse chronological order. Notes are omitted unless include_notes=true.", "tags": [ "Mood" ], "security": [ { "oauth2": [ "moods.read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Number of records to return (1–100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "example": 25 }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque next_cursor from the previous response.", "schema": { "type": "string" }, "example": "MjAyNi0wNi0yOVQxODozMDowMC4wMDBafDEwNDI" }, { "name": "include_notes", "in": "query", "required": false, "description": "Include the private note field in each mood entry.", "schema": { "type": "boolean", "default": false }, "example": true } ], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "user_id", "mood_value", "mood_key", "mood_label", "mood_emoji", "note", "source", "meal_log_id", "recorded_at", "local_entry_date", "timezone", "created_at", "source_app_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "mood_value": { "type": "integer" }, "mood_key": { "type": "string" }, "mood_label": { "type": "string" }, "mood_emoji": { "type": "string" }, "note": { "type": "string" }, "source": { "type": "string" }, "meal_log_id": { "type": "string" }, "recorded_at": { "type": "string", "format": "date-time" }, "local_entry_date": { "type": "string", "format": "date" }, "timezone": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "next_cursor": { "type": "string" } }, "additionalProperties": false }, "example": { "data": [ { "id": "7fd304e1-7823-4352-a855-33d0da83bf28", "user_id": "6bc72c8d-6d8a-4e85-9cbb-c02d19dca12f", "mood_value": 4, "mood_key": "good", "mood_label": "Good", "mood_emoji": "🙂", "note": "Good energy after lunch.", "source": "api", "meal_log_id": "1042", "recorded_at": "2026-06-29T20:15:00.000Z", "local_entry_date": "2026-06-29", "timezone": "America/Denver", "created_at": "2026-06-29T20:15:01.000Z", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } ], "next_cursor": "MjAyNi0wNi0yOFQxMzowMDowMC4wMDBafDEwNDI" } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "moods.read", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "moods.read", "x-foodabcs-price-cents": 0.5, "x-foodabcs-tier2-price-cents": 1, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/moods/{moodId}/responses": { "post": { "operationId": "post_moods_responses_write", "summary": "Record a mood response", "description": "Records the submitted prompt action for an API-owned mood entry. Repeated submissions for the same local date are deduplicated.", "tags": [ "Mood" ], "security": [ { "oauth2": [ "moods.write" ] } ], "parameters": [ { "name": "moodId", "in": "path", "required": true, "description": "Mood entry identifier.", "schema": { "type": "string" }, "example": "7fd304e1-7823-4352-a855-33d0da83bf28" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key that safely replays the first response when the same request body is retried.", "schema": { "type": "string" }, "example": "61d6c26b-4f60-4a03-a8df-c65bf86a6b64" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "action": { "type": "string" }, "local_entry_date": { "type": "string", "format": "date" }, "timezone": { "type": "string" } }, "additionalProperties": false }, "example": { "action": "submitted", "local_entry_date": "2026-06-29", "timezone": "America/Denver" } } } }, "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "user_id", "local_entry_date", "timezone", "action", "mood_entry_id", "recorded_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "local_entry_date": { "type": "string", "format": "date" }, "timezone": { "type": "string" }, "action": { "type": "string" }, "mood_entry_id": { "type": "string", "format": "uuid" }, "recorded_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "example": { "id": "b035d85f-86a3-4f2f-b231-a4b1a2488f73", "user_id": "6bc72c8d-6d8a-4e85-9cbb-c02d19dca12f", "local_entry_date": "2026-06-29", "timezone": "America/Denver", "action": "submitted", "mood_entry_id": "7fd304e1-7823-4352-a855-33d0da83bf28", "recorded_at": "2026-06-29T20:15:00.000Z" } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "404": { "description": "The requested resource does not exist or is not visible to this credential.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "not_found", "message": "Resource not found.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "409": { "description": "The Idempotency-Key was already used with a different request body.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "idempotency_conflict", "message": "Idempotency-Key was already used with a different request.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "moods.responses.write", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "moods.responses.write", "x-foodabcs-price-cents": 1, "x-foodabcs-tier2-price-cents": 2, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/wellness/metrics": { "get": { "operationId": "get_wellness_read", "summary": "Get latest wellness metrics", "description": "Returns the latest value for each supported wellness metric. An account with no exam snapshots returns a null snapshot_at and an empty metrics object.", "tags": [ "Wellness" ], "security": [ { "oauth2": [ "wellness.read" ] } ], "parameters": [], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "snapshot_at", "metrics" ], "properties": { "snapshot_at": { "type": "string", "format": "date-time" }, "metrics": { "type": "object", "required": [ "height", "weight", "bmi", "systolic_bp", "diastolic_bp", "body_temp_f", "resting_hr", "respiratory_rate" ], "properties": { "height": { "type": "string" }, "weight": { "type": "string" }, "bmi": { "type": "string" }, "systolic_bp": { "type": "integer" }, "diastolic_bp": { "type": "integer" }, "body_temp_f": { "type": "string" }, "resting_hr": { "type": "integer" }, "respiratory_rate": { "type": "integer" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "snapshot_at": "2026-06-15T16:00:00.000Z", "metrics": { "height": "70", "weight": "176.4", "bmi": "25.3", "systolic_bp": 118, "diastolic_bp": 76, "body_temp_f": "98.4", "resting_hr": 62, "respiratory_rate": 14 } } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "wellness.read", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "wellness.read", "x-foodabcs-price-cents": 0.5, "x-foodabcs-tier2-price-cents": 1, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/wellness/metrics/{metricKey}": { "get": { "operationId": "get_wellness_read_one", "summary": "Get metric history", "description": "Lists the history for one supported metric: height, weight, bmi, systolic_bp, diastolic_bp, body_temp_f, resting_hr, or respiratory_rate.", "tags": [ "Wellness" ], "security": [ { "oauth2": [ "wellness.read" ] } ], "parameters": [ { "name": "metricKey", "in": "path", "required": true, "description": "Supported wellness metric key.", "schema": { "type": "string" }, "example": "weight" }, { "name": "limit", "in": "query", "required": false, "description": "Number of records to return (1–100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "example": 25 }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque next_cursor from the previous response.", "schema": { "type": "string" }, "example": "MjAyNi0wNi0yOVQxODozMDowMC4wMDBafDEwNDI" } ], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "snapshot_at", "value", "source", "source_app_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "snapshot_at": { "type": "string", "format": "date-time" }, "value": { "type": "string" }, "source": { "type": "string" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "next_cursor": { "type": "string" } }, "additionalProperties": false }, "example": { "data": [ { "id": "296d2c48-e9ab-44b8-a988-7b7332640af4", "snapshot_at": "2026-06-15T16:00:00.000Z", "value": "176.4", "source": "api", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } ], "next_cursor": "MjAyNi0wNi0yOFQxMzowMDowMC4wMDBafDEwNDI" } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "404": { "description": "The requested resource does not exist or is not visible to this credential.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "not_found", "message": "Resource not found.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "wellness.read.one", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "wellness.read.one", "x-foodabcs-price-cents": 0.5, "x-foodabcs-tier2-price-cents": 1, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/physical-exams/latest": { "get": { "operationId": "get_exams_read_latest", "summary": "Get latest physical exam", "description": "Returns the latest physical-exam snapshot, or an empty JSON object when no snapshot exists.", "tags": [ "Health records" ], "security": [ { "oauth2": [ "exams.read" ] } ], "parameters": [], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "id", "user_id", "snapshot_at", "source", "height", "weight", "bmi", "systolic_bp", "diastolic_bp", "body_temp_f", "resting_hr", "respiratory_rate", "created_at", "source_app_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "snapshot_at": { "type": "string", "format": "date-time" }, "source": { "type": "string" }, "height": { "type": "string" }, "weight": { "type": "string" }, "bmi": { "type": "string" }, "systolic_bp": { "type": "integer" }, "diastolic_bp": { "type": "integer" }, "body_temp_f": { "type": "string" }, "resting_hr": { "type": "integer" }, "respiratory_rate": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, { "type": "object", "maxProperties": 0 } ] }, "example": { "id": "296d2c48-e9ab-44b8-a988-7b7332640af4", "user_id": "6bc72c8d-6d8a-4e85-9cbb-c02d19dca12f", "snapshot_at": "2026-06-15T16:00:00.000Z", "source": "api", "height": "70", "weight": "176.4", "bmi": "25.3", "systolic_bp": 118, "diastolic_bp": 76, "body_temp_f": "98.4", "resting_hr": 62, "respiratory_rate": 14, "created_at": "2026-06-15T16:00:01.000Z", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "exams.read.latest", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "exams.read.latest", "x-foodabcs-price-cents": 0.5, "x-foodabcs-tier2-price-cents": 1, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/physical-exams": { "get": { "operationId": "get_exams_read", "summary": "List physical exams", "description": "Lists physical-exam snapshots in reverse chronological order.", "tags": [ "Health records" ], "security": [ { "oauth2": [ "exams.read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Number of records to return (1–100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "example": 25 }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque next_cursor from the previous response.", "schema": { "type": "string" }, "example": "MjAyNi0wNi0yOVQxODozMDowMC4wMDBafDEwNDI" } ], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "user_id", "snapshot_at", "source", "height", "weight", "bmi", "systolic_bp", "diastolic_bp", "body_temp_f", "resting_hr", "respiratory_rate", "created_at", "source_app_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "snapshot_at": { "type": "string", "format": "date-time" }, "source": { "type": "string" }, "height": { "type": "string" }, "weight": { "type": "string" }, "bmi": { "type": "string" }, "systolic_bp": { "type": "integer" }, "diastolic_bp": { "type": "integer" }, "body_temp_f": { "type": "string" }, "resting_hr": { "type": "integer" }, "respiratory_rate": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "next_cursor": { "type": "string" } }, "additionalProperties": false }, "example": { "data": [ { "id": "296d2c48-e9ab-44b8-a988-7b7332640af4", "user_id": "6bc72c8d-6d8a-4e85-9cbb-c02d19dca12f", "snapshot_at": "2026-06-15T16:00:00.000Z", "source": "api", "height": "70", "weight": "176.4", "bmi": "25.3", "systolic_bp": 118, "diastolic_bp": 76, "body_temp_f": "98.4", "resting_hr": 62, "respiratory_rate": 14, "created_at": "2026-06-15T16:00:01.000Z", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } ], "next_cursor": "MjAyNi0wNi0yOFQxMzowMDowMC4wMDBafDEwNDI" } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "exams.read", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "exams.read", "x-foodabcs-price-cents": 0.5, "x-foodabcs-tier2-price-cents": 1, "x-foodabcs-infra-cost-cents": 0.02 }, "post": { "operationId": "post_exams_write", "summary": "Create a physical exam", "description": "Creates an API-owned physical-exam snapshot. Omitted measurements are stored as null.", "tags": [ "Health records" ], "security": [ { "oauth2": [ "exams.write" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key that safely replays the first response when the same request body is retried.", "schema": { "type": "string" }, "example": "61d6c26b-4f60-4a03-a8df-c65bf86a6b64" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "snapshot_at": { "type": "string", "format": "date-time" }, "height": { "type": "integer" }, "weight": { "type": "number" }, "bmi": { "type": "number" }, "systolic_bp": { "type": "integer" }, "diastolic_bp": { "type": "integer" }, "body_temp_f": { "type": "number" }, "resting_hr": { "type": "integer" }, "respiratory_rate": { "type": "integer" } }, "additionalProperties": false }, "example": { "snapshot_at": "2026-06-15T16:00:00.000Z", "height": 70, "weight": 176.4, "bmi": 25.3, "systolic_bp": 118, "diastolic_bp": 76, "body_temp_f": 98.4, "resting_hr": 62, "respiratory_rate": 14 } } } }, "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "user_id", "snapshot_at", "source", "height", "weight", "bmi", "systolic_bp", "diastolic_bp", "body_temp_f", "resting_hr", "respiratory_rate", "created_at", "source_app_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "snapshot_at": { "type": "string", "format": "date-time" }, "source": { "type": "string" }, "height": { "type": "string" }, "weight": { "type": "string" }, "bmi": { "type": "string" }, "systolic_bp": { "type": "integer" }, "diastolic_bp": { "type": "integer" }, "body_temp_f": { "type": "string" }, "resting_hr": { "type": "integer" }, "respiratory_rate": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, "example": { "id": "296d2c48-e9ab-44b8-a988-7b7332640af4", "user_id": "6bc72c8d-6d8a-4e85-9cbb-c02d19dca12f", "snapshot_at": "2026-06-15T16:00:00.000Z", "source": "api", "height": "70", "weight": "176.4", "bmi": "25.3", "systolic_bp": 118, "diastolic_bp": 76, "body_temp_f": "98.4", "resting_hr": 62, "respiratory_rate": 14, "created_at": "2026-06-15T16:00:01.000Z", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "409": { "description": "The Idempotency-Key was already used with a different request body.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "idempotency_conflict", "message": "Idempotency-Key was already used with a different request.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "exams.write", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "exams.write", "x-foodabcs-price-cents": 1, "x-foodabcs-tier2-price-cents": 2, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/goals/wellness": { "get": { "operationId": "get_goals_wellness_read", "summary": "Get wellness goals", "description": "Returns active wellness goals across visible sources.", "tags": [ "Goals" ], "security": [ { "oauth2": [ "goals.read" ] } ], "parameters": [], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "goal", "created_at", "source_app_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "goal": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } } }, "additionalProperties": false }, "example": { "data": [ { "id": "b035d85f-86a3-4f2f-b231-a4b1a2488f73", "goal": "Improve Cardiovascular Health", "created_at": "2026-05-03T15:00:00.000Z", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } ] } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "goals.wellness.read", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "goals.wellness.read", "x-foodabcs-price-cents": 0.5, "x-foodabcs-tier2-price-cents": 1, "x-foodabcs-infra-cost-cents": 0.02 }, "put": { "operationId": "put_goals_wellness_write", "summary": "Replace wellness goals", "description": "Replaces this app’s active wellness goals with one to three supported goal names and returns all active goals.", "tags": [ "Goals" ], "security": [ { "oauth2": [ "goals.write" ] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "goals" ], "properties": { "goals": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "example": { "goals": [ "Improve Cardiovascular Health", "Better Sleep Quality" ] } } } }, "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "goal", "created_at", "source_app_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "goal": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } } }, "additionalProperties": false }, "example": { "data": [ { "id": "b035d85f-86a3-4f2f-b231-a4b1a2488f73", "goal": "Improve Cardiovascular Health", "created_at": "2026-06-29T15:00:00.000Z", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" }, { "id": "7d3fb86b-470d-4855-8daf-c574a81bf2dc", "goal": "Better Sleep Quality", "created_at": "2026-06-29T15:00:00.000Z", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } ] } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "goals.wellness.write", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "goals.wellness.write", "x-foodabcs-price-cents": 1, "x-foodabcs-tier2-price-cents": 2, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/goals/nutrition": { "get": { "operationId": "get_goals_nutrition_read", "summary": "Get nutrition goals", "description": "Returns current nutrition goals and records whether each value came from the user or another source.", "tags": [ "Goals" ], "security": [ { "oauth2": [ "goals.read" ] } ], "parameters": [], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "metric_id", "target_value", "target_unit", "goal_kind", "source", "created_at", "updated_at", "source_app_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "metric_id": { "type": "string" }, "target_value": { "type": "string" }, "target_unit": { "type": "string" }, "goal_kind": { "type": "string" }, "source": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } } }, "additionalProperties": false }, "example": { "data": [ { "id": "b035d85f-86a3-4f2f-b231-a4b1a2488f73", "metric_id": "protein", "target_value": "120", "target_unit": "g", "goal_kind": "daily_target", "source": "user_override", "created_at": "2026-05-03T15:00:00.000Z", "updated_at": "2026-06-29T15:00:00.000Z", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } ] } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "goals.nutrition.read", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "goals.nutrition.read", "x-foodabcs-price-cents": 0.5, "x-foodabcs-tier2-price-cents": 1, "x-foodabcs-infra-cost-cents": 0.02 }, "put": { "operationId": "put_goals_nutrition_write", "summary": "Upsert nutrition goals", "description": "Upserts this app’s nutrition targets by metric_id and goal_kind, then returns all current nutrition goals; omitted goals are not deleted.", "tags": [ "Goals" ], "security": [ { "oauth2": [ "goals.write" ] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "goals" ], "properties": { "goals": { "type": "array", "items": { "type": "object", "required": [ "metric_id", "target_value", "target_unit", "goal_kind" ], "properties": { "metric_id": { "type": "string" }, "target_value": { "type": "integer" }, "target_unit": { "type": "string" }, "goal_kind": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false }, "example": { "goals": [ { "metric_id": "protein", "target_value": 120, "target_unit": "g", "goal_kind": "daily_target" } ] } } } }, "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "metric_id", "target_value", "target_unit", "goal_kind", "source", "created_at", "updated_at", "source_app_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "metric_id": { "type": "string" }, "target_value": { "type": "string" }, "target_unit": { "type": "string" }, "goal_kind": { "type": "string" }, "source": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } } }, "additionalProperties": false }, "example": { "data": [ { "id": "b035d85f-86a3-4f2f-b231-a4b1a2488f73", "metric_id": "protein", "target_value": "120", "target_unit": "g", "goal_kind": "daily_target", "source": "user_override", "created_at": "2026-05-03T15:00:00.000Z", "updated_at": "2026-06-29T15:00:00.000Z", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } ] } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "goals.nutrition.write", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "goals.nutrition.write", "x-foodabcs-price-cents": 1, "x-foodabcs-tier2-price-cents": 2, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/dietary-restrictions": { "get": { "operationId": "get_restrictions_read", "summary": "Get dietary restrictions", "description": "Returns active dietary restrictions across visible sources.", "tags": [ "Health records" ], "security": [ { "oauth2": [ "restrictions.read" ] } ], "parameters": [], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "restriction", "created_at", "source_app_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "restriction": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } } }, "additionalProperties": false }, "example": { "data": [ { "id": "b035d85f-86a3-4f2f-b231-a4b1a2488f73", "restriction": "Tree nuts", "created_at": "2026-04-12T18:00:00.000Z", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } ] } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "restrictions.read", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "restrictions.read", "x-foodabcs-price-cents": 0.5, "x-foodabcs-tier2-price-cents": 1, "x-foodabcs-infra-cost-cents": 0.02 }, "put": { "operationId": "put_restrictions_write", "summary": "Replace dietary restrictions", "description": "Replaces this app’s active dietary restrictions and returns all active restrictions.", "tags": [ "Health records" ], "security": [ { "oauth2": [ "restrictions.write" ] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "restrictions" ], "properties": { "restrictions": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "example": { "restrictions": [ "Tree nuts", "Shellfish" ] } } } }, "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "user_id", "restriction", "removed_at", "created_at", "source_app_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "restriction": { "type": "string" }, "removed_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": true } } }, "additionalProperties": true }, "example": { "data": [ { "id": "b035d85f-86a3-4f2f-b231-a4b1a2488f73", "user_id": "6bc72c8d-6d8a-4e85-9cbb-c02d19dca12f", "restriction": "Tree nuts", "removed_at": null, "created_at": "2026-06-29T18:00:00.000Z", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" }, { "id": "7d3fb86b-470d-4855-8daf-c574a81bf2dc", "user_id": "6bc72c8d-6d8a-4e85-9cbb-c02d19dca12f", "restriction": "Shellfish", "removed_at": null, "created_at": "2026-06-29T18:00:00.000Z", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } ] } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "restrictions.write", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "restrictions.write", "x-foodabcs-price-cents": 1, "x-foodabcs-tier2-price-cents": 2, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/conditions": { "get": { "operationId": "get_conditions_read", "summary": "Get health conditions", "description": "Returns active conditions and optional diagnosed months.", "tags": [ "Health records" ], "security": [ { "oauth2": [ "conditions.read" ] } ], "parameters": [], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "condition_key", "diagnosed_month", "created_at", "source_app_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "condition_key": { "type": "string" }, "diagnosed_month": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } } }, "additionalProperties": false }, "example": { "data": [ { "id": "b035d85f-86a3-4f2f-b231-a4b1a2488f73", "condition_key": "hypertension", "diagnosed_month": "2024-11", "created_at": "2026-04-12T18:00:00.000Z", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } ] } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "conditions.read", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "conditions.read", "x-foodabcs-price-cents": 0.5, "x-foodabcs-tier2-price-cents": 1, "x-foodabcs-infra-cost-cents": 0.02 }, "put": { "operationId": "put_conditions_write", "summary": "Replace health conditions", "description": "Replaces this app’s active conditions. diagnosed_month uses YYYY-MM when known.", "tags": [ "Health records" ], "security": [ { "oauth2": [ "conditions.write" ] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "conditions" ], "properties": { "conditions": { "type": "array", "items": { "type": "object", "required": [ "condition_key", "diagnosed_month" ], "properties": { "condition_key": { "type": "string" }, "diagnosed_month": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false }, "example": { "conditions": [ { "condition_key": "hypertension", "diagnosed_month": "2024-11" } ] } } } }, "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "condition_key", "diagnosed_month", "created_at", "source_app_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "condition_key": { "type": "string" }, "diagnosed_month": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } } }, "additionalProperties": false }, "example": { "data": [ { "id": "b035d85f-86a3-4f2f-b231-a4b1a2488f73", "condition_key": "hypertension", "diagnosed_month": "2024-11", "created_at": "2026-06-29T18:00:00.000Z", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } ] } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "conditions.write", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "conditions.write", "x-foodabcs-price-cents": 1, "x-foodabcs-tier2-price-cents": 2, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/medications": { "get": { "operationId": "get_medications_read", "summary": "Get active medications", "description": "Returns medications without an ended_month.", "tags": [ "Health records" ], "security": [ { "oauth2": [ "medications.read" ] } ], "parameters": [], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "rxcui", "ingredient", "ingredient_rxcui", "started_month", "ended_month", "created_at", "updated_at", "source_app_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "rxcui": { "type": "string" }, "ingredient": { "type": "string" }, "ingredient_rxcui": { "type": "string" }, "started_month": { "type": "string" }, "ended_month": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } } }, "additionalProperties": false }, "example": { "data": [ { "id": "b035d85f-86a3-4f2f-b231-a4b1a2488f73", "name": "Lisinopril 10 MG Oral Tablet", "rxcui": "314076", "ingredient": "lisinopril", "ingredient_rxcui": "29046", "started_month": "2025-01", "ended_month": null, "created_at": "2025-01-10T17:00:00.000Z", "updated_at": "2025-01-10T17:00:00.000Z", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } ] } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "medications.read", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "medications.read", "x-foodabcs-price-cents": 0.5, "x-foodabcs-tier2-price-cents": 1, "x-foodabcs-infra-cost-cents": 0.02 }, "post": { "operationId": "post_medications_write", "summary": "Add a medication", "description": "Creates one API-owned medication row. Month fields use YYYY-MM.", "tags": [ "Health records" ], "security": [ { "oauth2": [ "medications.write" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key that safely replays the first response when the same request body is retried.", "schema": { "type": "string" }, "example": "61d6c26b-4f60-4a03-a8df-c65bf86a6b64" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "rxcui": { "type": "string" }, "ingredient": { "type": "string" }, "ingredient_rxcui": { "type": "string" }, "started_month": { "type": "string" } }, "additionalProperties": false }, "example": { "name": "Lisinopril 10 MG Oral Tablet", "rxcui": "314076", "ingredient": "lisinopril", "ingredient_rxcui": "29046", "started_month": "2025-01" } } } }, "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "rxcui", "ingredient", "ingredient_rxcui", "started_month", "ended_month", "created_at", "updated_at", "source_app_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "rxcui": { "type": "string" }, "ingredient": { "type": "string" }, "ingredient_rxcui": { "type": "string" }, "started_month": { "type": "string" }, "ended_month": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, "example": { "id": "b035d85f-86a3-4f2f-b231-a4b1a2488f73", "name": "Lisinopril 10 MG Oral Tablet", "rxcui": "314076", "ingredient": "lisinopril", "ingredient_rxcui": "29046", "started_month": "2025-01", "ended_month": null, "created_at": "2026-06-29T18:00:00.000Z", "updated_at": "2026-06-29T18:00:00.000Z", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "409": { "description": "The Idempotency-Key was already used with a different request body.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "idempotency_conflict", "message": "Idempotency-Key was already used with a different request.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "medications.write", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "medications.write", "x-foodabcs-price-cents": 1, "x-foodabcs-tier2-price-cents": 2, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/medications/history": { "get": { "operationId": "get_medications_history_read", "summary": "Get medication history", "description": "Returns active and ended medications in reverse chronological order.", "tags": [ "Health records" ], "security": [ { "oauth2": [ "medications.read" ] } ], "parameters": [], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "rxcui", "ingredient", "ingredient_rxcui", "started_month", "ended_month", "created_at", "updated_at", "source_app_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "rxcui": { "type": "string" }, "ingredient": { "type": "string" }, "ingredient_rxcui": { "type": "string" }, "started_month": { "type": "string" }, "ended_month": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } } }, "additionalProperties": false }, "example": { "data": [ { "id": "b035d85f-86a3-4f2f-b231-a4b1a2488f73", "name": "Lisinopril 10 MG Oral Tablet", "rxcui": "314076", "ingredient": "lisinopril", "ingredient_rxcui": "29046", "started_month": "2025-01", "ended_month": "2026-01", "created_at": "2025-01-10T17:00:00.000Z", "updated_at": "2026-01-09T17:00:00.000Z", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } ] } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "medications.history.read", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "medications.history.read", "x-foodabcs-price-cents": 0.5, "x-foodabcs-tier2-price-cents": 1, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/medications/{medicationId}": { "delete": { "operationId": "delete_medications_end", "summary": "End a medication", "description": "Sets ended_month on an API-owned medication. If omitted, ended_month defaults to the current UTC month.", "tags": [ "Health records" ], "security": [ { "oauth2": [ "medications.write" ] } ], "parameters": [ { "name": "medicationId", "in": "path", "required": true, "description": "Medication identifier.", "schema": { "type": "string" }, "example": "b035d85f-86a3-4f2f-b231-a4b1a2488f73" }, { "name": "ended_month", "in": "query", "required": false, "description": "End month in YYYY-MM format; defaults to the current UTC month.", "schema": { "type": "string" }, "example": "2026-06" } ], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "rxcui", "ingredient", "ingredient_rxcui", "started_month", "ended_month", "created_at", "updated_at", "source_app_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "rxcui": { "type": "string" }, "ingredient": { "type": "string" }, "ingredient_rxcui": { "type": "string" }, "started_month": { "type": "string" }, "ended_month": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, "example": { "id": "b035d85f-86a3-4f2f-b231-a4b1a2488f73", "name": "Lisinopril 10 MG Oral Tablet", "rxcui": "314076", "ingredient": "lisinopril", "ingredient_rxcui": "29046", "started_month": "2025-01", "ended_month": "2026-06", "created_at": "2025-01-10T17:00:00.000Z", "updated_at": "2026-06-29T18:00:00.000Z", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "404": { "description": "The requested resource does not exist or is not visible to this credential.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "not_found", "message": "Resource not found.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "medications.end", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "medications.end", "x-foodabcs-price-cents": 1, "x-foodabcs-tier2-price-cents": 2, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/food-behavior-events": { "get": { "operationId": "get_behaviors_read", "summary": "List food behavior events", "description": "Lists detected food-behavior events in reverse chronological order.", "tags": [ "Meals" ], "security": [ { "oauth2": [ "behaviors.read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Number of records to return (1–100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "example": 25 }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque next_cursor from the previous response.", "schema": { "type": "string" }, "example": "MjAyNi0wNi0yOVQxODozMDowMC4wMDBafDEwNDI" }, { "name": "event_type", "in": "query", "required": false, "description": "Filter to one behavior event type.", "schema": { "type": "string" }, "example": "late_night_eating" } ], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "user_id", "meal_id", "event_type", "event_value", "heat_score", "confidence", "recorded_at", "source", "behavior_version", "notes", "metadata", "created_at", "source_app_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "meal_id": { "type": "string" }, "event_type": { "type": "string" }, "event_value": { "type": "string" }, "heat_score": { "type": "integer" }, "confidence": { "type": "string" }, "recorded_at": { "type": "string", "format": "date-time" }, "source": { "type": "string" }, "behavior_version": { "type": "string" }, "notes": { "type": "string" }, "metadata": { "type": "object", "required": [ "local_hour" ], "properties": { "local_hour": { "type": "integer" } }, "additionalProperties": false }, "created_at": { "type": "string", "format": "date-time" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "next_cursor": { "type": "string" } }, "additionalProperties": false }, "example": { "data": [ { "id": "b035d85f-86a3-4f2f-b231-a4b1a2488f73", "user_id": "6bc72c8d-6d8a-4e85-9cbb-c02d19dca12f", "meal_id": "1042", "event_type": "late_night_eating", "event_value": "0.82", "heat_score": 72, "confidence": "0.91", "recorded_at": "2026-06-29T22:35:00.000Z", "source": "meal_ai", "behavior_version": "v1", "notes": "Meal recorded after the local late-night threshold.", "metadata": { "local_hour": 22 }, "created_at": "2026-06-29T22:35:05.000Z", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } ], "next_cursor": "MjAyNi0wNi0yOFQxMzowMDowMC4wMDBafDEwNDI" } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "behaviors.read", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "behaviors.read", "x-foodabcs-price-cents": 0.5, "x-foodabcs-tier2-price-cents": 1, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/foods/search": { "get": { "operationId": "get_foods_search", "summary": "Search foods", "description": "Returns matching foods and pagination metadata. Result counts and identifiers are strings.", "tags": [ "Discovery" ], "security": [ { "oauth2": [ "foods.search" ] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Food search phrase.", "schema": { "type": "string", "minLength": 1 }, "example": "plain greek yogurt" } ], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "foods", "page_number", "max_results", "total_results" ], "properties": { "foods": { "type": "object", "required": [ "food" ], "properties": { "food": { "type": "array", "items": { "type": "object", "required": [ "food_id", "food_name", "food_type", "food_description", "brand_name" ], "properties": { "food_id": { "type": "string" }, "food_name": { "type": "string" }, "food_type": { "type": "string" }, "food_description": { "type": "string" }, "brand_name": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true }, "page_number": { "type": "string" }, "max_results": { "type": "string" }, "total_results": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "example": { "data": { "foods": { "food": [ { "food_id": "4384", "food_name": "Greek yogurt, plain", "food_type": "Generic", "food_description": "1 cup - 149 calories", "brand_name": "FoodABCs" } ] }, "page_number": "0", "max_results": "25", "total_results": "84" } } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "foods.search", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "foods.search", "x-foodabcs-price-cents": 1.5, "x-foodabcs-tier2-price-cents": 3, "x-foodabcs-infra-cost-cents": 0.05 } }, "/v1/foods/barcode/{upc}": { "get": { "operationId": "get_foods_barcode", "summary": "Look up a food by barcode", "description": "Looks up packaged-food nutrition by an 8–14 digit UPC or EAN barcode.", "tags": [ "Discovery" ], "security": [ { "oauth2": [ "foods.search" ] } ], "parameters": [ { "name": "upc", "in": "path", "required": true, "description": "UPC or EAN barcode containing 8–14 digits.", "schema": { "type": "string" }, "example": "012345678905" } ], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "food" ], "properties": { "food": { "type": "object", "required": [ "id", "name", "amount", "unit", "type", "brand", "brand_name", "barcode", "upc", "nutrition", "logged_nutrients", "stored_calories" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "amount": { "type": "number" }, "unit": { "type": "string" }, "type": { "type": "string" }, "brand": { "type": "string" }, "brand_name": { "type": "string" }, "barcode": { "type": "string" }, "upc": { "type": "string" }, "nutrition": { "type": "object", "required": [ "nutrients", "weight_per_serving" ], "properties": { "nutrients": { "type": "array", "items": { "type": "object", "required": [ "name", "amount", "unit" ], "properties": { "name": { "type": "string" }, "amount": { "type": "integer" }, "unit": { "type": "string" } }, "additionalProperties": false } }, "weight_per_serving": { "type": "object", "required": [ "amount", "unit" ], "properties": { "amount": { "type": "integer" }, "unit": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false }, "logged_nutrients": { "type": "array", "items": { "type": "object", "required": [ "key", "name", "amount", "unit" ], "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "amount": { "type": "integer" }, "unit": { "type": "string" } }, "additionalProperties": false } }, "stored_calories": { "type": "integer" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "food": { "id": 12345, "name": "Old Fashioned Oats", "amount": 0.5, "unit": "cup", "type": "grocery_product", "brand": "Example Foods", "brand_name": "Example Foods", "barcode": "012345678905", "upc": "012345678905", "nutrition": { "nutrients": [ { "name": "Calories", "amount": 150, "unit": "kcal" }, { "name": "Protein", "amount": 5, "unit": "g" } ], "weight_per_serving": { "amount": 40, "unit": "g" } }, "logged_nutrients": [ { "key": "calories", "name": "Calories", "amount": 150, "unit": "kcal" }, { "key": "protein", "name": "Protein", "amount": 5, "unit": "g" } ], "stored_calories": 150 } } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "404": { "description": "The requested resource does not exist or is not visible to this credential.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "not_found", "message": "Resource not found.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "foods.barcode", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "foods.barcode", "x-foodabcs-price-cents": 3.5, "x-foodabcs-tier2-price-cents": 7, "x-foodabcs-infra-cost-cents": 0.05 } }, "/v1/farmers-markets": { "get": { "operationId": "get_places_farmers_markets", "summary": "Find farmers markets", "description": "Returns nearby market listings for a latitude and longitude.", "tags": [ "Discovery" ], "security": [ { "oauth2": [ "foods.search" ] } ], "parameters": [ { "name": "lat", "in": "query", "required": true, "description": "Latitude between -90 and 90.", "schema": { "type": "number", "minimum": -90, "maximum": 90 }, "example": 39.7392 }, { "name": "lng", "in": "query", "required": true, "description": "Longitude between -180 and 180.", "schema": { "type": "number", "minimum": -180, "maximum": 180 }, "example": -104.9903 }, { "name": "radius_miles", "in": "query", "required": false, "description": "Search radius from 1 through 100 miles.", "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 30 }, "example": 30 } ], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "data" ], "properties": { "error": { "type": "integer" }, "data": { "type": "array", "items": { "type": "object", "required": [ "listing_id", "listing_name", "location_y", "location_x" ], "properties": { "listing_id": { "type": "string" }, "listing_name": { "type": "string" }, "location_y": { "type": "string" }, "location_x": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true }, "example": { "error": 0, "data": [ { "listing_id": "1001234", "listing_name": "Union Station Farmers Market", "location_y": "39.752", "location_x": "-104.999" } ] } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "places.farmers_markets", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "places.farmers_markets", "x-foodabcs-price-cents": 0.5, "x-foodabcs-tier2-price-cents": 1, "x-foodabcs-infra-cost-cents": 0.05 } }, "/v1/medications/search": { "get": { "operationId": "get_medications_search", "summary": "Search medications", "description": "Returns normalized medication matches for a name search.", "tags": [ "Discovery" ], "security": [ { "oauth2": [ "foods.search" ] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Medication search phrase of at least two characters.", "schema": { "type": "string", "minLength": 2 }, "example": "lisinopril" } ], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "type": "object", "required": [ "rxcui", "name", "tty" ], "properties": { "rxcui": { "type": "string" }, "name": { "type": "string" }, "tty": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true }, "example": { "results": [ { "rxcui": "314076", "name": "Lisinopril 10 MG Oral Tablet", "tty": "SCD" } ] } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "medications.search", "x-foodabcs-token-classes": [ "user" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "medications.search", "x-foodabcs-price-cents": 0.3, "x-foodabcs-tier2-price-cents": 0.6, "x-foodabcs-infra-cost-cents": 0.05 } }, "/v1/partner/usage": { "get": { "operationId": "get_partner_usage_read", "summary": "Get usage summary", "description": "Returns aggregate calls, errors, cost, active users, and an endpoint breakdown across the partner’s apps.", "tags": [ "Usage and billing" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Inclusive ISO 8601 range start.", "schema": { "type": "string" }, "example": "2026-06-01T00:00:00Z" }, { "name": "to", "in": "query", "required": false, "description": "Inclusive ISO 8601 range end.", "schema": { "type": "string" }, "example": "2026-06-30T23:59:59Z" } ], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "period", "totals", "endpoints" ], "properties": { "period": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } }, "additionalProperties": false }, "totals": { "type": "object", "required": [ "call_count", "error_count", "cost_cents", "active_user_count" ], "properties": { "call_count": { "type": "integer" }, "error_count": { "type": "integer" }, "cost_cents": { "type": "integer" }, "active_user_count": { "type": "integer" } }, "additionalProperties": false }, "endpoints": { "type": "array", "items": { "type": "object", "required": [ "endpoint_key", "call_count", "error_count", "cost_cents" ], "properties": { "endpoint_key": { "type": "string" }, "call_count": { "type": "integer" }, "error_count": { "type": "integer" }, "cost_cents": { "type": "integer" } }, "additionalProperties": false } } }, "additionalProperties": false }, "example": { "period": { "from": "2026-06-01", "to": "2026-06-30" }, "totals": { "call_count": 12580, "error_count": 217, "cost_cents": 9435, "active_user_count": 384 }, "endpoints": [ { "endpoint_key": "meals.read", "call_count": 3820, "error_count": 41, "cost_cents": 764 } ] } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "partner.usage.read", "x-foodabcs-token-classes": [ "partner" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "partner.usage.read", "x-foodabcs-price-cents": 0.5, "x-foodabcs-tier2-price-cents": 1, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/partner/usage/daily": { "get": { "operationId": "get_partner_usage_daily_read", "summary": "Get daily usage", "description": "Returns daily usage rows by endpoint across the partner’s apps.", "tags": [ "Usage and billing" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Inclusive ISO 8601 range start.", "schema": { "type": "string" }, "example": "2026-06-01T00:00:00Z" }, { "name": "to", "in": "query", "required": false, "description": "Inclusive ISO 8601 range end.", "schema": { "type": "string" }, "example": "2026-06-30T23:59:59Z" } ], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "usage_date", "partner_id", "endpoint_key", "call_count", "error_count", "cost_cents", "expense_cents", "is_sandbox" ], "properties": { "usage_date": { "type": "string", "format": "date" }, "partner_id": { "type": "string", "format": "uuid" }, "endpoint_key": { "type": "string" }, "call_count": { "type": "integer" }, "error_count": { "type": "integer" }, "cost_cents": { "type": "string" }, "expense_cents": { "type": "string" }, "is_sandbox": { "type": "boolean" } }, "additionalProperties": false } } }, "additionalProperties": false }, "example": { "data": [ { "usage_date": "2026-06-29", "partner_id": "7d3fb86b-470d-4855-8daf-c574a81bf2dc", "endpoint_key": "meals.read", "call_count": 148, "error_count": 2, "cost_cents": "30.0000", "expense_cents": "1.4800", "is_sandbox": false } ] } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "partner.usage.daily.read", "x-foodabcs-token-classes": [ "partner" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "partner.usage.daily.read", "x-foodabcs-price-cents": 0.5, "x-foodabcs-tier2-price-cents": 1, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/partner/costs": { "get": { "operationId": "get_partner_costs_read", "summary": "Get costs and prices", "description": "Returns month-to-date spend, the configured spend cap, and every active endpoint price.", "tags": [ "Usage and billing" ], "security": [ { "apiKey": [] } ], "parameters": [], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "month_to_date_spend_cents", "monthly_spend_cap_cents", "endpoint_prices" ], "properties": { "month_to_date_spend_cents": { "type": "integer" }, "monthly_spend_cap_cents": { "type": "integer" }, "endpoint_prices": { "type": "array", "items": { "type": "object", "required": [ "endpoint_key", "price_cents", "tier2_price_cents", "infra_cost_cents", "active" ], "properties": { "endpoint_key": { "type": "string" }, "price_cents": { "type": "number" }, "tier2_price_cents": { "type": "number" }, "infra_cost_cents": { "type": "number" }, "active": { "type": "boolean" } }, "additionalProperties": false } } }, "additionalProperties": false }, "example": { "month_to_date_spend_cents": 9435, "monthly_spend_cap_cents": 25000, "endpoint_prices": [ { "endpoint_key": "meals.read", "price_cents": 0.2, "tier2_price_cents": 0.15, "infra_cost_cents": 0.01, "active": true } ] } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "partner.costs.read", "x-foodabcs-token-classes": [ "partner" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "partner.costs.read", "x-foodabcs-price-cents": 0.5, "x-foodabcs-tier2-price-cents": 1, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/partner/analytics/overview": { "get": { "operationId": "get_partner_analytics_overview", "summary": "Get analytics overview", "description": "Returns own-source engagement aggregates. Buckets below the privacy threshold are returned as suppressed rather than exposing small cohorts.", "tags": [ "Partner analytics" ], "security": [ { "apiKey": [] } ], "parameters": [], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "overview", "engagement_by_week" ], "properties": { "overview": { "oneOf": [ { "type": "object", "required": [ "subject_count", "meals_logged", "workouts_logged", "moods_logged", "average_meal_grade_score" ], "properties": { "subject_count": { "type": "integer" }, "meals_logged": { "type": "integer" }, "workouts_logged": { "type": "integer" }, "moods_logged": { "type": "integer" }, "average_meal_grade_score": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "suppressed", "minimum_cohort" ], "properties": { "suppressed": { "type": "boolean" }, "minimum_cohort": { "type": "integer" } }, "additionalProperties": false } ] }, "engagement_by_week": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": [ "week", "distinct_user_count", "event_count" ], "properties": { "week": { "type": "string", "format": "date" }, "distinct_user_count": { "type": "integer" }, "event_count": { "type": "integer" } }, "additionalProperties": false }, { "type": "object", "required": [ "suppressed", "minimum_cohort" ], "properties": { "suppressed": { "type": "boolean" }, "minimum_cohort": { "type": "integer" } }, "additionalProperties": false } ] } } }, "additionalProperties": false }, "example": { "overview": { "subject_count": 384, "meals_logged": 4210, "workouts_logged": 1402, "moods_logged": 2198, "average_meal_grade_score": "82.4" }, "engagement_by_week": [ { "week": "2026-06-22", "distinct_user_count": 247, "event_count": 1984 } ] } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "tier_required", "message": "Tier 2 is required.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "partner.analytics.overview", "x-foodabcs-token-classes": [ "partner" ], "x-foodabcs-tier": "tier2", "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "partner.analytics.overview", "x-foodabcs-price-cents": 2, "x-foodabcs-tier2-price-cents": 4, "x-foodabcs-infra-cost-cents": 0.1 } }, "/v1/partner/analytics/meals": { "get": { "operationId": "get_partner_analytics_meals", "summary": "Get meal analytics", "description": "Returns privacy-suppressed grade, nutrient, and weekly meal aggregates for records created by this partner app.", "tags": [ "Partner analytics" ], "security": [ { "apiKey": [] } ], "parameters": [], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "grade_distribution", "nutrient_averages", "trends" ], "properties": { "grade_distribution": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": [ "grade", "distinct_user_count", "meal_count" ], "properties": { "grade": { "type": "string" }, "distinct_user_count": { "type": "integer" }, "meal_count": { "type": "integer" } }, "additionalProperties": false }, { "type": "object", "required": [ "suppressed", "minimum_cohort" ], "properties": { "suppressed": { "type": "boolean" }, "minimum_cohort": { "type": "integer" } }, "additionalProperties": false } ] } }, "nutrient_averages": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": [ "nutrient_key", "distinct_user_count", "average_amount" ], "properties": { "nutrient_key": { "type": "string" }, "distinct_user_count": { "type": "integer" }, "average_amount": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "suppressed", "minimum_cohort" ], "properties": { "suppressed": { "type": "boolean" }, "minimum_cohort": { "type": "integer" } }, "additionalProperties": false } ] } }, "trends": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": [ "week", "distinct_user_count", "meal_count" ], "properties": { "week": { "type": "string", "format": "date" }, "distinct_user_count": { "type": "integer" }, "meal_count": { "type": "integer" } }, "additionalProperties": false }, { "type": "object", "required": [ "suppressed", "minimum_cohort" ], "properties": { "suppressed": { "type": "boolean" }, "minimum_cohort": { "type": "integer" } }, "additionalProperties": false } ] } } }, "additionalProperties": false }, "example": { "grade_distribution": [ { "grade": "A", "distinct_user_count": 142, "meal_count": 1240 } ], "nutrient_averages": [ { "nutrient_key": "protein", "distinct_user_count": 205, "average_amount": "31.7" } ], "trends": [ { "week": "2026-06-22", "distinct_user_count": 247, "meal_count": 1065 } ] } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "tier_required", "message": "Tier 2 is required.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "partner.analytics.meals", "x-foodabcs-token-classes": [ "partner" ], "x-foodabcs-tier": "tier2", "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "partner.analytics.meals", "x-foodabcs-price-cents": 2, "x-foodabcs-tier2-price-cents": 4, "x-foodabcs-infra-cost-cents": 0.1 } }, "/v1/partner/analytics/workouts": { "get": { "operationId": "get_partner_analytics_workouts", "summary": "Get workout analytics", "description": "Returns privacy-suppressed type, grade, and weekly workout aggregates for records created by this partner app.", "tags": [ "Partner analytics" ], "security": [ { "apiKey": [] } ], "parameters": [], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "by_type", "grade_distribution", "trends" ], "properties": { "by_type": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": [ "type", "distinct_user_count", "workout_count", "average_duration_minutes", "average_calories" ], "properties": { "type": { "type": "string" }, "distinct_user_count": { "type": "integer" }, "workout_count": { "type": "integer" }, "average_duration_minutes": { "type": "string" }, "average_calories": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "suppressed", "minimum_cohort" ], "properties": { "suppressed": { "type": "boolean" }, "minimum_cohort": { "type": "integer" } }, "additionalProperties": false } ] } }, "grade_distribution": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": [ "grade", "distinct_user_count", "workout_count" ], "properties": { "grade": { "type": "string" }, "distinct_user_count": { "type": "integer" }, "workout_count": { "type": "integer" } }, "additionalProperties": false }, { "type": "object", "required": [ "suppressed", "minimum_cohort" ], "properties": { "suppressed": { "type": "boolean" }, "minimum_cohort": { "type": "integer" } }, "additionalProperties": false } ] } }, "trends": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": [ "week", "distinct_user_count", "workout_count", "total_minutes", "total_calories" ], "properties": { "week": { "type": "string", "format": "date" }, "distinct_user_count": { "type": "integer" }, "workout_count": { "type": "integer" }, "total_minutes": { "type": "integer" }, "total_calories": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "suppressed", "minimum_cohort" ], "properties": { "suppressed": { "type": "boolean" }, "minimum_cohort": { "type": "integer" } }, "additionalProperties": false } ] } } }, "additionalProperties": false }, "example": { "by_type": [ { "type": "Outdoor Run", "distinct_user_count": 88, "workout_count": 312, "average_duration_minutes": "34.8", "average_calories": "362.1" } ], "grade_distribution": [ { "grade": "A", "distinct_user_count": 112, "workout_count": 498 } ], "trends": [ { "week": "2026-06-22", "distinct_user_count": 146, "workout_count": 382, "total_minutes": 14210, "total_calories": "125420" } ] } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "tier_required", "message": "Tier 2 is required.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "partner.analytics.workouts", "x-foodabcs-token-classes": [ "partner" ], "x-foodabcs-tier": "tier2", "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "partner.analytics.workouts", "x-foodabcs-price-cents": 2, "x-foodabcs-tier2-price-cents": 4, "x-foodabcs-infra-cost-cents": 0.1 } }, "/v1/partner/analytics/cohorts": { "get": { "operationId": "get_partner_analytics_cohorts", "summary": "Get cohort analytics", "description": "Returns privacy-suppressed weekly engagement cohorts for own-source activity.", "tags": [ "Partner analytics" ], "security": [ { "apiKey": [] } ], "parameters": [], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "cohorts" ], "properties": { "cohorts": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": [ "week", "distinct_user_count", "average_events_per_user" ], "properties": { "week": { "type": "string", "format": "date" }, "distinct_user_count": { "type": "integer" }, "average_events_per_user": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "suppressed", "minimum_cohort" ], "properties": { "suppressed": { "type": "boolean" }, "minimum_cohort": { "type": "integer" } }, "additionalProperties": false } ] } } }, "additionalProperties": false }, "example": { "cohorts": [ { "week": "2026-06-22", "distinct_user_count": 247, "average_events_per_user": "8.03" } ] } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "tier_required", "message": "Tier 2 is required.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "partner.analytics.cohorts", "x-foodabcs-token-classes": [ "partner" ], "x-foodabcs-tier": "tier2", "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "partner.analytics.cohorts", "x-foodabcs-price-cents": 2, "x-foodabcs-tier2-price-cents": 4, "x-foodabcs-infra-cost-cents": 0.1 } }, "/v1/partner/users": { "get": { "operationId": "get_partner_users_list", "summary": "List authorized users", "description": "Lists users with a current individual-access grant. Requires Tier 2 and verified compliance; every row is PHI-audited.", "tags": [ "Partner users" ], "security": [ { "apiKey": [] } ], "parameters": [], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "user_id", "scope", "granted_at" ], "properties": { "user_id": { "type": "string", "format": "uuid" }, "scope": { "type": "string" }, "granted_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } }, "additionalProperties": false }, "example": { "data": [ { "user_id": "6bc72c8d-6d8a-4e85-9cbb-c02d19dca12f", "scope": "meals.read workouts.read moods.read exams.read", "granted_at": "2026-05-14T20:00:00.000Z" } ] } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "compliance_required", "message": "Compliance verification is required.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "partner.users.list", "x-foodabcs-token-classes": [ "partner" ], "x-foodabcs-tier": "tier2", "x-foodabcs-requires-compliance": true, "x-foodabcs-price-key": "partner.users.list", "x-foodabcs-price-cents": 0.5, "x-foodabcs-tier2-price-cents": 1, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/partner/users/{userId}/records": { "get": { "operationId": "get_partner_users_records", "summary": "Get authorized user records", "description": "Returns this app’s meal, workout, mood, and physical-exam records for one user with an active individual-access grant. Requires Tier 2 and verified compliance; access is PHI-audited.", "tags": [ "Partner users" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "User UUID with an active individual-access grant.", "schema": { "type": "string" }, "example": "6bc72c8d-6d8a-4e85-9cbb-c02d19dca12f" } ], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "user_id", "meals", "workouts", "moods", "physical_exams" ], "properties": { "user_id": { "type": "string", "format": "uuid" }, "meals": { "type": "array", "items": { "type": "object", "required": [ "id", "user_id", "timestamp", "name", "ingredients", "total_calories", "meal_score", "is_favorite", "meal_classifications", "meal_classification_version", "meal_classified_at", "meal_behavior_events", "meal_behavior_version", "meal_behavior_detected_at", "source_app_id" ], "properties": { "id": { "type": "string" }, "user_id": { "type": "string", "format": "uuid" }, "timestamp": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "ingredients": { "type": "array", "items": { "type": "object", "required": [ "name", "amount", "unit", "nutrition" ], "properties": { "name": { "type": "string" }, "amount": { "type": "integer" }, "unit": { "type": "string" }, "nutrition": { "type": "object", "required": [ "nutrients" ], "properties": { "nutrients": { "type": "array", "items": { "type": "object", "required": [ "name", "amount", "unit" ], "properties": { "name": { "type": "string" }, "amount": { "type": "integer" }, "unit": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } }, "additionalProperties": false } }, "total_calories": { "type": "string" }, "meal_score": { "type": "string" }, "is_favorite": { "type": "boolean" }, "meal_classifications": { "type": "array", "items": { "type": "object", "required": [ "key", "label" ], "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "additionalProperties": false } }, "meal_classification_version": { "type": "string" }, "meal_classified_at": { "type": "string", "format": "date-time" }, "meal_behavior_events": { "type": "array", "items": {} }, "meal_behavior_version": { "type": "string" }, "meal_behavior_detected_at": { "type": "string", "format": "date-time" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "workouts": { "type": "array", "items": { "type": "object", "required": [ "id", "user_id", "type", "start_time", "end_time", "duration_minutes", "calories_burned", "average_heart_rate", "min_heart_rate", "max_heart_rate", "heart_rate_samples", "distance_meters", "steps", "elevation_gain_meters", "average_speed_mps", "max_speed_mps", "average_power_watts", "average_cadence", "calorie_samples", "provider", "original_id", "grade", "synced_at", "created_at", "updated_at", "raw_type", "source_app_id" ], "properties": { "id": { "type": "string" }, "user_id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "duration_minutes": { "type": "integer" }, "calories_burned": { "type": "integer" }, "average_heart_rate": { "type": "integer" }, "min_heart_rate": { "type": "integer" }, "max_heart_rate": { "type": "integer" }, "heart_rate_samples": { "type": "array", "items": { "type": "object", "required": [ "offset_seconds", "bpm" ], "properties": { "offset_seconds": { "type": "integer" }, "bpm": { "type": "integer" } }, "additionalProperties": false } }, "distance_meters": { "type": "integer" }, "steps": { "type": "integer" }, "elevation_gain_meters": { "type": "integer" }, "average_speed_mps": { "type": "number" }, "max_speed_mps": { "type": "number" }, "average_power_watts": { "type": "integer" }, "average_cadence": { "type": "integer" }, "calorie_samples": { "type": "array", "items": { "type": "object", "required": [ "offset_seconds", "calories" ], "properties": { "offset_seconds": { "type": "integer" }, "calories": { "type": "integer" } }, "additionalProperties": false } }, "provider": { "type": "string" }, "original_id": { "type": "string" }, "grade": { "type": "string" }, "synced_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "raw_type": { "type": "string" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "moods": { "type": "array", "items": { "type": "object", "required": [ "id", "user_id", "mood_value", "mood_key", "mood_label", "mood_emoji", "source", "meal_log_id", "recorded_at", "local_entry_date", "timezone", "created_at", "source_app_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "mood_value": { "type": "integer" }, "mood_key": { "type": "string" }, "mood_label": { "type": "string" }, "mood_emoji": { "type": "string" }, "source": { "type": "string" }, "meal_log_id": { "type": "string" }, "recorded_at": { "type": "string", "format": "date-time" }, "local_entry_date": { "type": "string", "format": "date" }, "timezone": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "physical_exams": { "type": "array", "items": { "type": "object", "required": [ "id", "user_id", "snapshot_at", "source", "height", "weight", "bmi", "systolic_bp", "diastolic_bp", "body_temp_f", "resting_hr", "respiratory_rate", "created_at", "source_app_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "snapshot_at": { "type": "string", "format": "date-time" }, "source": { "type": "string" }, "height": { "type": "string" }, "weight": { "type": "string" }, "bmi": { "type": "string" }, "systolic_bp": { "type": "integer" }, "diastolic_bp": { "type": "integer" }, "body_temp_f": { "type": "string" }, "resting_hr": { "type": "integer" }, "respiratory_rate": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "source_app_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } } }, "additionalProperties": false }, "example": { "user_id": "6bc72c8d-6d8a-4e85-9cbb-c02d19dca12f", "meals": [ { "id": "1042", "user_id": "6bc72c8d-6d8a-4e85-9cbb-c02d19dca12f", "timestamp": "2026-06-29T18:30:00.000Z", "name": "Chicken quinoa bowl", "ingredients": [ { "name": "Grilled chicken breast", "amount": 5, "unit": "oz", "nutrition": { "nutrients": [ { "name": "Calories", "amount": 234, "unit": "kcal" }, { "name": "Protein", "amount": 44, "unit": "g" }, { "name": "Carbohydrates", "amount": 0, "unit": "g" }, { "name": "Fat", "amount": 5, "unit": "g" } ] } }, { "name": "Cooked quinoa", "amount": 1, "unit": "cup", "nutrition": { "nutrients": [ { "name": "Calories", "amount": 222, "unit": "kcal" }, { "name": "Protein", "amount": 8, "unit": "g" }, { "name": "Carbohydrates", "amount": 39, "unit": "g" }, { "name": "Fat", "amount": 4, "unit": "g" } ] } } ], "total_calories": "612", "meal_score": "A", "is_favorite": false, "meal_classifications": [ { "key": "high_protein", "label": "High protein" } ], "meal_classification_version": "v1", "meal_classified_at": "2026-06-29T18:30:08.000Z", "meal_behavior_events": [], "meal_behavior_version": "v1", "meal_behavior_detected_at": "2026-06-29T18:30:08.000Z", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } ], "workouts": [ { "id": "api_3a99efb4-6ac9-44f7-8a0c-663a8ee6464f", "user_id": "6bc72c8d-6d8a-4e85-9cbb-c02d19dca12f", "type": "Outdoor Run", "start_time": "2026-06-28T13:00:00.000Z", "end_time": "2026-06-28T13:32:00.000Z", "duration_minutes": 32, "calories_burned": 348, "average_heart_rate": 151, "min_heart_rate": 104, "max_heart_rate": 174, "heart_rate_samples": [ { "offset_seconds": 60, "bpm": 132 } ], "distance_meters": 5020, "steps": 6234, "elevation_gain_meters": 41, "average_speed_mps": 2.61, "max_speed_mps": 3.9, "average_power_watts": 248, "average_cadence": 168, "calorie_samples": [ { "offset_seconds": 300, "calories": 54 } ], "provider": "api", "original_id": "run-2026-06-28", "grade": "A", "synced_at": "2026-06-28T13:33:00.000Z", "created_at": "2026-06-28T13:33:00.000Z", "updated_at": "2026-06-28T13:33:00.000Z", "raw_type": "running", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } ], "moods": [ { "id": "7fd304e1-7823-4352-a855-33d0da83bf28", "user_id": "6bc72c8d-6d8a-4e85-9cbb-c02d19dca12f", "mood_value": 4, "mood_key": "good", "mood_label": "Good", "mood_emoji": "🙂", "source": "api", "meal_log_id": "1042", "recorded_at": "2026-06-29T20:15:00.000Z", "local_entry_date": "2026-06-29", "timezone": "America/Denver", "created_at": "2026-06-29T20:15:01.000Z", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } ], "physical_exams": [ { "id": "296d2c48-e9ab-44b8-a988-7b7332640af4", "user_id": "6bc72c8d-6d8a-4e85-9cbb-c02d19dca12f", "snapshot_at": "2026-06-15T16:00:00.000Z", "source": "api", "height": "70", "weight": "176.4", "bmi": "25.3", "systolic_bp": 118, "diastolic_bp": 76, "body_temp_f": "98.4", "resting_hr": 62, "respiratory_rate": 14, "created_at": "2026-06-15T16:00:01.000Z", "source_app_id": "64a5163c-3ca0-4c54-bc71-b6f66d5862f7" } ] } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "compliance_required", "message": "Compliance verification is required.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "404": { "description": "The requested resource does not exist or is not visible to this credential.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "not_found", "message": "Resource not found.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "partner.users.records", "x-foodabcs-token-classes": [ "partner" ], "x-foodabcs-tier": "tier2", "x-foodabcs-requires-compliance": true, "x-foodabcs-price-key": "partner.users.records", "x-foodabcs-price-cents": 0.5, "x-foodabcs-tier2-price-cents": 1, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/partner/webhooks": { "get": { "operationId": "get_partner_webhooks_list_create_delete", "summary": "List webhooks", "description": "Lists registered webhook destinations without returning signing secrets.", "tags": [ "Webhooks" ], "security": [ { "apiKey": [] } ], "parameters": [], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "url", "events", "status", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } }, "additionalProperties": false }, "example": { "data": [ { "id": "7d3fb86b-470d-4855-8daf-c574a81bf2dc", "url": "https://partner.example.com/webhooks/foodabcs", "events": [ "meal.graded", "grant.revoked" ], "status": "active", "created_at": "2026-06-20T16:00:00.000Z" } ] } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "partner.webhooks.list/create/delete", "x-foodabcs-token-classes": [ "partner" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "partner.webhooks.list/create/delete", "x-foodabcs-price-cents": 1, "x-foodabcs-tier2-price-cents": 2, "x-foodabcs-infra-cost-cents": 0.02 }, "post": { "operationId": "post_partner_webhooks_list_create_delete", "summary": "Create a webhook", "description": "Registers a destination and returns its signing secret once. Store the secret securely; later list calls omit it.", "tags": [ "Webhooks" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key that safely replays the first response when the same request body is retried.", "schema": { "type": "string" }, "example": "61d6c26b-4f60-4a03-a8df-c65bf86a6b64" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "example": { "url": "https://partner.example.com/webhooks/foodabcs", "events": [ "meal.graded", "grant.revoked" ] } } } }, "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "url", "events", "status", "created_at", "secret" ], "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "secret": { "type": "string" } }, "additionalProperties": false }, "example": { "id": "7d3fb86b-470d-4855-8daf-c574a81bf2dc", "url": "https://partner.example.com/webhooks/foodabcs", "events": [ "meal.graded", "grant.revoked" ], "status": "active", "created_at": "2026-06-29T16:00:00.000Z", "secret": "whsec_o4dYb5lqVUEXAMPLE" } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "409": { "description": "The Idempotency-Key was already used with a different request body.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "idempotency_conflict", "message": "Idempotency-Key was already used with a different request.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "partner.webhooks.list/create/delete", "x-foodabcs-token-classes": [ "partner" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "partner.webhooks.list/create/delete", "x-foodabcs-price-cents": 1, "x-foodabcs-tier2-price-cents": 2, "x-foodabcs-infra-cost-cents": 0.02 } }, "/v1/partner/webhooks/{webhookId}": { "delete": { "operationId": "delete_partner_webhooks_list_create_delete", "summary": "Delete a webhook", "description": "Deletes one webhook destination owned by the partner.", "tags": [ "Webhooks" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "description": "Webhook UUID.", "schema": { "type": "string" }, "example": "7d3fb86b-470d-4855-8daf-c574a81bf2dc" } ], "responses": { "200": { "description": "The request completed successfully.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted", "id" ], "properties": { "deleted": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, "example": { "deleted": true, "id": "7d3fb86b-470d-4855-8daf-c574a81bf2dc" } } } }, "401": { "description": "The bearer token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "invalid_token", "message": "Missing bearer token.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "402": { "description": "Billing setup is required, or API access is suspended after the payment grace period.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "billing_setup_required", "message": "Complete billing setup before using API credentials.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "403": { "description": "The credential lacks the required scope, tier, compliance state, consent, or active partner status.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "insufficient_scope", "message": "Required scope is missing.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "404": { "description": "The requested resource does not exist or is not visible to this credential.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "not_found", "message": "Resource not found.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "422": { "description": "A body, path, or query value failed validation.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "validation_failed", "message": "One or more request values are invalid.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "429": { "description": "The app exceeded its rate limit or monthly spend cap.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "500": { "description": "FoodABCs could not complete the request.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "internal_error", "message": "Internal server error.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } }, "503": { "description": "Billing access or durable usage metering could not be verified before endpoint work began.", "headers": { "Request-Id": { "description": "Unique request identifier for support and audit correlation.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Current app request limit.", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "error": { "code": "metering_unavailable", "message": "API metering is temporarily unavailable.", "request_id": "8f6d26b4-4a8b-4c61-a2ba-f08a3f5c15a1" } } } } } }, "x-foodabcs-endpoint-key": "partner.webhooks.list/create/delete", "x-foodabcs-token-classes": [ "partner" ], "x-foodabcs-tier": null, "x-foodabcs-requires-compliance": false, "x-foodabcs-price-key": "partner.webhooks.list/create/delete", "x-foodabcs-price-cents": 1, "x-foodabcs-tier2-price-cents": 2, "x-foodabcs-infra-cost-cents": 0.02 } } } }