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 <key>; 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=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of "<t>.<raw body>" 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=<remaining>;t=<seconds to reset>); 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.

Patients

Patient management endpoints

• GET
  List all patients for an expert/patients
• POST
  Create a new patient/patients
• GET
  Get a specific patient/patients/{patient_id}
• PUT
  Update a patient/patients/{patient_id}

Appointments

Scheduled appointment management endpoints

• GET
  List scheduled appointments/appointments
• POST
  Create a scheduled appointment/appointments
• GET
  Get a specific scheduled appointment/appointments/{appointment_id}
• PUT
  Update or reschedule a scheduled appointment/appointments/{appointment_id}
• DELETE
  Delete a scheduled appointment/appointments/{appointment_id}

Health Plans

Health plan and purchased health plan management endpoints

• GET
  List health plans/health-plans
• GET
  Get active purchased health plan for a patient/patients/{patient_id}/purchased-health-plans/active

Meal Plans

Meal plans of the account: days, meals, options and exchange portions

• GET
  List meal plans/meal-plans
• POST
  Create a meal plan/meal-plans
• GET
  Get a meal plan/meal-plans/{meal_plan_id}
• PUT
  Edit a meal plan/meal-plans/{meal_plan_id}
• POST
  Send a meal plan to the patient/meal-plans/{meal_plan_id}/send

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
  Search foods/foods
• POST
  Create a custom food/foods
• GET
  Get a food/foods/{food_id}
• PUT
  Edit a custom food/foods/{food_id}

Recipes

Recipes of the account and public ones

• GET
  List recipes/recipes
• POST
  Create a recipe/recipes
• GET
  Get a recipe/recipes/{recipe_id}
• PUT
  Edit a recipe/recipes/{recipe_id}

Exchange Groups

Exchange groups used by exchange meal plans

• GET
  List exchange groups/exchange-groups
• POST
  Create an exchange group/exchange-groups
• PUT
  Edit an exchange group/exchange-groups/{exchange_group_id}

Clinical Data

Patients’ clinical history, consultation notes, measurements and lab results, and progress photos. Health data: needs the clinical:read permission.

• GET
  Get a patient's clinical history/patients/{patient_id}/clinical-history
• GET
  List a patient's consultations/patients/{patient_id}/consultations
• GET
  List a patient's progress photos/patients/{patient_id}/progress-photos