Medoura Landing Page API

Overview

Every request is made with an API key that belongs to one practice, so each response contains only that practice's data. The API is read-only: it never creates orders or collects patient information. Checkout stays in Medoura.

To send a visitor to checkout, link to your own Medoura `/start` page. Each product carries a `start_url_path` (for example `/start?medication_family=semaglutide`). It is a path, not a full URL: prefix it with your own Medoura domain, such as `https://your-practice-domain.com` + `start_url_path`.

Quickstart

Create a key in Settings > API (`/staff/settings/api`), then call each endpoint from your server. Replace the host with your own Medoura domain.

export MEDOURA_API_KEY="med_live_..."
export MEDOURA_HOST="https://your-practice-domain.com"

# Branding: name, logo, colors
curl -H "Authorization: Bearer $MEDOURA_API_KEY" "$MEDOURA_HOST/api/v1/branding"

# Categories: the treatment categories you offer
curl -H "Authorization: Bearer $MEDOURA_API_KEY" "$MEDOURA_HOST/api/v1/categories"

# Products, optionally filtered to one category
curl -H "Authorization: Bearer $MEDOURA_API_KEY" "$MEDOURA_HOST/api/v1/products?category=weightLoss"

# Pricing, plans and promotions
curl -H "Authorization: Bearer $MEDOURA_API_KEY" "$MEDOURA_HOST/api/v1/pricing"

# Published home-page content, in English or Spanish
curl -H "Authorization: Bearer $MEDOURA_API_KEY" "$MEDOURA_HOST/api/v1/content/home?locale=en"

Category keys are camelCase (for example `weightLoss`). Take the `key` values from `GET /api/v1/categories` rather than guessing; the key in the example above is illustrative.

Authentication

Send your API key in the `Authorization` header on every request:

Authorization: Bearer med_live_...

Keys are created in Settings > API at `/staff/settings/api`. A key is shown exactly once, when it is created, so copy it immediately. A practice can have up to 10 active keys.

To rotate a key with no downtime: create a new key, switch your server over to it, then revoke the old one.

Rate Limits

Over the limit, the API returns `429 rate_limited` with a `Retry-After` header giving the seconds to wait. Requests count against both limits even when they end in `304 Not Modified`. Requests with a missing or invalid key are limited separately, to 20 per minute per IP address, and also answer `429` with `Retry-After`. Combine the caching below with your own server-side cache so a busy landing page does not spend your budget on every visit.

Caching

Responses carry `Cache-Control: private, max-age=<seconds>, stale-while-revalidate=<seconds>` (both values equal the TTL below), `Vary: Authorization` and a weak `ETag`. A cache may serve a response for up to the TTL and then, while it revalidates, up to the same time again, so data can be up to about twice the TTL old. Send the ETag back in `If-None-Match` and an unchanged response returns `304 Not Modified` with no body.

curl -i -H "Authorization: Bearer $MEDOURA_API_KEY" \
  -H 'If-None-Match: W/"<etag from the previous response>"' \
  "$MEDOURA_HOST/api/v1/products"

Errors

Every error uses one shape:

{
  "error": {
    "code": "validation_failed",
    "message": "Invalid locale",
    "details": [{ "field": "locale", "message": "Must be \"en\" or \"es\"" }]
  }
}

`details` appears only on validation errors.

Filtering by Category

Pass `?category=<key>` to `/api/v1/products` or `/api/v1/pricing` to narrow the response to one category. Use a key returned by `/api/v1/categories`; an unknown key returns `404 not_found`.

On `/api/v1/pricing` the filter applies to `products` only. `promos`, `nutritionProducts`, `nutritionBundles` and `stateCoverage` are not category-filtered and are always returned in full.

Branding Values May Be Null

`GET /api/v1/branding` only returns what the practice has configured. Any field the practice has not set is `null`, never a Medoura or platform default, and the `colors` object is always present with each color either a CSS color string or `null`.

A few fields are derived from the practice's own data: `url` and `nppUrl` come from the practice's domain, `shortName`, `legalName` and `legalFooterCopy` fall back to the practice's own `name`, and the LegitScript URLs come from its seal id. `heroBottleShadowUrl` is reserved and always `null`.

Check every value for `null` before using it, and supply your own fallback (your agency's or the brand's own assets) rather than assuming a logo, color or name is present.

Content

In v1 the only content page is `home`: `GET /api/v1/content/home`. Any other page key returns `404 not_found`. If the practice has no published home content, `content` is `null`. Add `?locale=en` or `?locale=es` to choose the language (default `en`). Only published content is returned; drafts are never exposed.

Versioning

The API is versioned in the path (`/api/v1`). Within v1, changes are additive only: new fields and endpoints may appear, but existing fields are not removed or renamed. Ignore fields you do not recognize.