Developer API quickstart

The shortest path to a 200. Every step is explained properly in Authentication — this page just gets you there.

1. Find your server's public address

The key will only work from the addresses you register, so start there. From the server that will call Medos — not your laptop — run:

curl -s https://checkip.amazonaws.com

That is the address your requests leave from. Behind a NAT gateway or a load balancer it is often not the server's own address. See IP allowlist if you are unsure.

2. Create the key

In the dashboard, Workspace Settings → API Keys → Add API Key:

3. Call the API

curl -s "https://api.medos.one/v2/workspaces" \
  -H "x-api-key: $MEDOS_API_KEY"

Or from Node:

const res = await fetch("https://api.medos.one/v2/workspaces", {
  headers: { "x-api-key": process.env.MEDOS_API_KEY },
});

console.log(res.status, await res.json());

A 200 and your workspace payload means everything is wired up: the key is live and your server's address is on its allowlist.

What just happened

Two things had to be true:

The key is the credential, so keep it secret. The allowlist is why a copy of it is useless to anyone calling from somewhere else.

Before you book anything

Routes that book or read a patient's records need the patient's phone verified by one-time code first, and they need one more header naming that patient:

x-end-user-id: <your id for this patient>

See OTP-gated routes — it is two calls and a header, but skipping it is the most common reason a first booking returns 400 or 403.

If it didn't work

Full list in Errors.

Next