Get started

Quickstart

Create a test key, make your first request and read the answer, in about five minutes.

This walks you through one request against your test workspace, so nothing you do here touches real customers, sends messages or charges anything.

1. Create a test key

In the Ordstage dashboard, open Settings → Developers. You need to be an owner or admin of the business, on a paid plan.
Switch to Test and choose Create key.
Name it (for example "My laptop"), pick the scopes bookings:read and bookings:write, and create it.
Copy the key. It starts with ord_test_ and is shown only once; if you lose it, revoke it and create another.

Keep the key out of your code. Put it in an environment variable:

export ORDSTAGE_API_KEY="paste your ord_test_ key here"

2. Make your first request

List the calendars the key can see:

curl https://api.ordstage.com/v1/calendars \
  -H "Authorization: Bearer $ORDSTAGE_API_KEY"

const response = await fetch("https://api.ordstage.com/v1/calendars", {
  headers: { Authorization: `Bearer ${process.env.ORDSTAGE_API_KEY}` },
});
console.log(response.status, response.headers.get("Request-Id"));
console.log(await response.json());

import os
import requests

response = requests.get(
    "https://api.ordstage.com/v1/calendars",
    headers={"Authorization": f"Bearer {os.environ['ORDSTAGE_API_KEY']}"},
    timeout=30,
)
print(response.status_code, response.headers["Request-Id"])
print(response.json())

3. Read the answer

A successful answer is 200 OK with JSON like this:

{
  "calendars": [
    {
      "id": "6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f",
      "name": "Nile Clinic",
      "industry": "clinic",
      "timezone": "Africa/Cairo",
      "is_active": true,
      "resources": [{ "id": "…", "name": "Dr. Sara Adel", "kind": "staff", "capacity": 1 }],
      "services": [{ "id": "…", "name": "Checkup", "duration_minutes": 20, "price": 300.0, "currency": "EGP" }]
    }
  ]
}

id is what the other booking endpoints take as calendar_id.
resources are the people, rooms or tables that can be booked; services are what can be booked.

Look at the headers too:

Header	Meaning
`Request-Id`	This request's id. Log it; quote it to support.
`X-RateLimit-Limit`	Requests this key may make per minute.
`X-RateLimit-Remaining`	Requests left in this minute.
`X-RateLimit-Reset`	Unix time when a request is next freed.

If something is wrong you get an error with the same shape every time, for example a wrong key:

{
  "error": {
    "type": "authentication",
    "code": "invalid_api_key",
    "message": "Use a valid workspace API key: Authorization: Bearer ord_…",
    "param": null,
    "request_id": "req_4f2a9c0d1e7b3a5c6d8e9f01"
  }
}

Branch on error.type and error.code, never on the message. All codes are listed in Errors.

4. Next steps

Check free times, then record a booking made in your own system under your own id (his-1 below). Sending the same id again updates that booking, so the request is safe to retry.

CAL=6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f   # a calendar id from step 3

curl "https://api.ordstage.com/v1/calendars/$CAL/availability?date_from=2026-11-02" \
  -H "Authorization: Bearer $ORDSTAGE_API_KEY"

curl -X PUT "https://api.ordstage.com/v1/calendars/$CAL/bookings/his-1" \
  -H "Authorization: Bearer $ORDSTAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resource": "Dr. Sara Adel", "start": "2026-11-02T09:00", "end": "2026-11-02T09:20", "customer_name": "Mona"}'

const cal = "6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"; // a calendar id from step 3
const headers = {
  Authorization: `Bearer ${process.env.ORDSTAGE_API_KEY}`,
  "Content-Type": "application/json",
};

const free = await fetch(`https://api.ordstage.com/v1/calendars/${cal}/availability?date_from=2026-11-02`, { headers });
console.log(await free.json());

const saved = await fetch(`https://api.ordstage.com/v1/calendars/${cal}/bookings/his-1`, {
  method: "PUT",
  headers,
  body: JSON.stringify({ resource: "Dr. Sara Adel", start: "2026-11-02T09:00", end: "2026-11-02T09:20", customer_name: "Mona" }),
});
console.log(await saved.json());

import os
import requests

cal = "6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f"  # a calendar id from step 3
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['ORDSTAGE_API_KEY']}"

free = session.get(f"https://api.ordstage.com/v1/calendars/{cal}/availability", params={"date_from": "2026-11-02"}, timeout=30)
print(free.json())

saved = session.put(
    f"https://api.ordstage.com/v1/calendars/{cal}/bookings/his-1",
    json={"resource": "Dr. Sara Adel", "start": "2026-11-02T09:00", "end": "2026-11-02T09:20", "customer_name": "Mona"},
    timeout=30,
)
print(saved.json())

Then:

Try every endpoint from the browser in the API reference (use your test key there).
Subscribe to webhooks so Ordstage tells you about bookings made by the assistant or the team.
When you are ready for real data, create a live key and read Authentication first.

Quickstart

#1. Create a test key

#2. Make your first request

#3. Read the answer

#4. Next steps

1. Create a test key

2. Make your first request

3. Read the answer

4. Next steps