# Quickstart

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

Source: https://www.ordstage.com/docs/quickstart/

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

1. In the Ordstage dashboard, open **Settings → Developers**. You need to be an owner or admin of the business, on
   a paid plan.
2. Switch to **Test** and choose **Create key**.
3. Name it (for example "My laptop"), pick the scopes `bookings:read` and `bookings:write`, and create it.
4. 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:

```bash
export ORDSTAGE_API_KEY="paste your ord_test_ key here"
```

## 2. Make your first request

List the calendars the key can see:

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

```js [JavaScript]
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());
```

```python [Python]
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:

```json
{
  "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:

```json
{
  "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](https://www.ordstage.com/docs/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.

```bash [curl]
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"}'
```

```js [JavaScript]
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());
```

```python [Python]
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](https://www.ordstage.com/docs/reference/) (use your **test** key there).
- [Subscribe to webhooks](https://www.ordstage.com/docs/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](https://www.ordstage.com/docs/authentication/) first.