--- seo: description: >- REST API for Almendra (https://almendra.io), the practice-management platform for nutritionists, dietitians, coaches and personal trainers. Read and manage… sidebar: label: Descripción general title: Almendra API --- REST API for Almendra (https://almendra.io), the practice-management platform for nutritionists, dietitians, coaches and personal trainers. Read and manage the patients, scheduled appointments, health plans, meal plans, foods, recipes and exchange groups of one professional account. Every request needs an API key sent as `Authorization: Bearer `; each key is bound to a single professional account, so no account id is ever passed in the URL. Create keys in the Almendra dashboard under Settings > Developers > API keys (paid plans; a key stops working while the plan is inactive). List endpoints are paginated with a fixed page size of 50. **Permissions.** Each key is granted permissions when it is created or edited in Settings > Developers > API keys; an operation the key is not allowed answers 403 `forbidden`. Each operation names the permission it needs: `patients:read` (read patients), `patients:write` (create and edit patients), `appointments:read` (read scheduled appointments), `appointments:write` (book, reschedule and delete appointments), `health_plans:read` (read health plans and purchased plans), `meal_plans:read` (read meal plans), `meal_plans:write` (create, edit and send meal plans), `library:read` (read foods, recipes and exchange groups), `library:write` (create and edit foods, recipes and exchange groups), `clinical:read` (read clinical data: clinical history, consultation notes, measurements and lab results, progress photos and form responses). Keys created before permissions existed keep the patient, appointment and health plan permissions. **Webhooks.** In Settings > Developers > Webhooks, add an HTTPS endpoint and choose events. Almendra POSTs each event as JSON with the headers `Almendra-Event` (the type), `Almendra-Delivery` (the event id; deliveries can repeat, so ignore ids you already processed) and `Almendra-Signature: t=,v1=`, where `v1` is the HMAC-SHA256 of `"."` with the endpoint's signing secret (`whsec_…`). Answer 2xx within 10 seconds; anything else is retried with backoff for about a day. Events carry ids only: read the details through the API. **Errors.** Every 4xx/5xx response has the `Error` body: `{ "success": false, "message": "…", "error": { "status": 404, "code": "not_found", "message": "…" } }` — branch on `error.code`. **Rate limits.** 600 requests per 60 seconds per API key. Every response carries the IETF RateLimit header fields (`RateLimit-Policy: "default";q=600;w=60`, `RateLimit: "default";r=;t=`); past the limit the API answers 429 `rate_limited` with `Retry-After` in seconds. **Versioning.** The major version is part of the URL (`/openapi/v1`). Within a version, changes are additive only: new endpoints, new optional request fields, new response fields and new `error.code` values. Removing or renaming anything, or changing a type, ships as a new major version under a new path (`/openapi/v2`), and the previous version keeps working while clients migrate. `/openapi` (no version) is an alias of v1 kept for existing integrations. **Deprecation.** An endpoint or field that will be removed is marked `deprecated: true` in this document and its responses carry the `Deprecation` (RFC 9745) and `Sunset` (RFC 8594) headers, with a `Link: <…>; rel="deprecation"` to the migration notes, at least 6 months before the Sunset date. Version v1 Base URL: `https://api.almendra.io/openapi/v1` ## Patients Patient management endpoints - [`GET /patients`](/help/reference/patients/list-patients) — List all patients for an expert. - [`POST /patients`](/help/reference/patients/create-patient) — Create a new patient. - [`GET /patients/{patient_id}`](/help/reference/patients/get-patient) — Get a specific patient. - [`PUT /patients/{patient_id}`](/help/reference/patients/update-patient) — Update a patient. ## Appointments Scheduled appointment management endpoints - [`GET /appointments`](/help/reference/appointments/list-appointments) — List scheduled appointments. - [`POST /appointments`](/help/reference/appointments/create-appointment) — Create a scheduled appointment. - [`GET /appointments/{appointment_id}`](/help/reference/appointments/get-appointment) — Get a specific scheduled appointment. - [`PUT /appointments/{appointment_id}`](/help/reference/appointments/update-appointment) — Update or reschedule a scheduled appointment. - [`DELETE /appointments/{appointment_id}`](/help/reference/appointments/delete-appointment) — Delete a scheduled appointment. ## Health Plans Health plan and purchased health plan management endpoints - [`GET /health-plans`](/help/reference/health-plans/list-health-plans) — List health plans. - [`GET /patients/{patient_id}/purchased-health-plans/active`](/help/reference/health-plans/get-active-purchased-health-plans) — Get active purchased health plan for a patient. ## Meal Plans Meal plans of the account: days, meals, options and exchange portions - [`GET /meal-plans`](/help/reference/meal-plans/list-meal-plans) — List meal plans. - [`POST /meal-plans`](/help/reference/meal-plans/create-meal-plan) — Create a meal plan. - [`GET /meal-plans/{meal_plan_id}`](/help/reference/meal-plans/get-meal-plan) — Get a meal plan. - [`PUT /meal-plans/{meal_plan_id}`](/help/reference/meal-plans/update-meal-plan) — Edit a meal plan. - [`POST /meal-plans/{meal_plan_id}/send`](/help/reference/meal-plans/send-meal-plan) — Send a meal plan to the patient. ## Foods Foods the account created or uses, and a limited search (5 results, 50 searches a day) to find new ones. Almendra's food database can't be browsed through the API. - [`GET /foods`](/help/reference/foods/search-foods) — Search foods. - [`POST /foods`](/help/reference/foods/create-food) — Create a custom food. - [`GET /foods/{food_id}`](/help/reference/foods/get-food) — Get a food. - [`PUT /foods/{food_id}`](/help/reference/foods/update-food) — Edit a custom food. ## Recipes Recipes of the account and public ones - [`GET /recipes`](/help/reference/recipes/list-recipes) — List recipes. - [`POST /recipes`](/help/reference/recipes/create-recipe) — Create a recipe. - [`GET /recipes/{recipe_id}`](/help/reference/recipes/get-recipe) — Get a recipe. - [`PUT /recipes/{recipe_id}`](/help/reference/recipes/update-recipe) — Edit a recipe. ## Exchange Groups Exchange groups used by exchange meal plans - [`GET /exchange-groups`](/help/reference/exchange-groups/list-exchange-groups) — List exchange groups. - [`POST /exchange-groups`](/help/reference/exchange-groups/create-exchange-group) — Create an exchange group. - [`PUT /exchange-groups/{exchange_group_id}`](/help/reference/exchange-groups/update-exchange-group) — Edit an exchange group. ## Clinical Data Patients' clinical history, consultation notes, measurements and lab results, and progress photos. Health data: needs the `clinical:read` permission. - [`GET /patients/{patient_id}/clinical-history`](/help/reference/clinical-data/get-clinical-history) — Get a patient's clinical history. - [`GET /patients/{patient_id}/consultations`](/help/reference/clinical-data/list-consultations) — List a patient's consultations. - [`GET /patients/{patient_id}/progress-photos`](/help/reference/clinical-data/list-progress-photos) — List a patient's progress photos.