> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://apidoc.dreamclass.io/introduction/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://apidoc.dreamclass.io/_mcp/server.

# Introduction

Version 1.0 of the public DreamClass API.

The API gives you programmatic access to your school's data — admissions, students, curriculum, calendar, attendance, grading and finance — over a single HTTPS endpoint. A companion set of webhooks lets your own systems react to changes in DreamClass as they happen, without polling.

## Base URL

Every request goes to the same host:

```
https://api.dreamclass.io
```

## Getting access

API access is enabled per account. Contact [support@dreamclass.io](mailto:support@dreamclass.io) to request activation for your school.

Once it is enabled, an administrator creates API keys in the DreamClass app under **Settings > Integrations**. Your school code is shown there too.

* Name each key after the integration that uses it, for example "Zapier" or "SIS sync".
* **The full key is shown only once**, when it is created. Copy it then and store it securely. DreamClass keeps only a hash of it and cannot show it again. After that, the list shows a masked form (`••••••••••••a1b2`) with the date it was created and roughly when it was last used.
* If you lose a key, create a new one and revoke the old one.
* New keys start with `dc_live_`. Keys issued earlier keep working unchanged.

A key belongs to the school it was created in and only works with that school's `schoolCode`.

### Rotating a key

A school can have up to 5 active keys at once, so you can rotate without downtime:

1. Create a new key.
2. Switch your integration to it.
3. Revoke the old key. Requests using it are rejected immediately.

## Authentication

Every request must carry three values, all sent as HTTP headers:

| Header                  | Value            | Where to find it        |
| ----------------------- | ---------------- | ----------------------- |
| `dreamclass-secret-key` | Your API key     | Settings > Integrations |
| `schoolCode`            | Your school code | Settings > Integrations |
| `tenant`                | Your tenant code | See below               |

All three are required on every request, including any that the API reference shows as optional.

Your **tenant code** is your DreamClass subdomain. If you sign in at `https://myaccount.dreamclass.io`, your tenant code is `myaccount`. If your account uses a white-labelled domain, the tenant code is that whole domain — for `https://portal.mywebsite.com` it is `portal.mywebsite.com`.

A complete request looks like this:

```bash
curl https://api.dreamclass.io/dreamclassapi/v1/curriculum/schoolperiods/list \
  -H "dreamclass-secret-key: YOUR_API_KEY" \
  -H "schoolCode: YOUR_SCHOOL_CODE" \
  -H "tenant: myaccount"
```

## Errors

Authentication is checked before any endpoint runs. Any missing or incorrect credential returns `401 Unauthorized` with the message `Invalid API credentials`. That covers a missing header, an unknown school code, and a wrong or revoked key. The response deliberately doesn't say which one, so check all three headers.

## Conventions

* Dates are ISO 8601 (`2026-01-31`) and timestamps are UTC.
* Ids are numeric unless stated otherwise.
* Monetary amounts are decimal values, in the currency configured for your school.
* `PATCH` endpoints update only the fields you send; anything you omit is left unchanged.
* Where an endpoint needs a value from elsewhere in the API, its description names the call that returns it.

## Where to start

Almost everything in DreamClass is scoped to a **School Period** — a school year or term. `GET /dreamclassapi/v1/curriculum/schoolperiods/list` is therefore usually the first call you make: it returns the period ids that the rest of the API expects.

From there, **Curriculum** gives you the classes and class courses of a period, **Students** the people enrolled in it, and **Fees** and **Invoices** the money owed and collected.

## Webhooks

Rather than polling for changes, you can have DreamClass POST to a URL of your choosing whenever data changes. Configure this under **Settings > Integrations**. See the **Webhooks** section for the payload format, HMAC signature validation and retry behaviour.

Note that webhooks are requests DreamClass sends **to you** — the URL shown on each webhook page is a placeholder for your own endpoint, not an address you call.

## Using the Postman collection

The collection ships with variables for the three values above. Open its **Variables** tab, replace `YOUR_API_KEY` and `YOUR_SCHOOL_CODE` with your own, and set `tenant` to your subdomain. `server` is already set to `https://api.dreamclass.io`.