Endpoint summary

Every operation the Partner API serves: 83 across 52 paths. This page is a map — the interactive reference carries the parameters, request and response schemas, and examples for each one.

Every path below is relative to the base URL for your environment, and every request carries Authorization: Bearer <token>. The scope column names the organisation scope an operation requires; a blank cell means the operation is reached with a delegated practitioner token rather than an organisation scope.

Meta

Service health and connectivity. Use these endpoints to confirm a token authenticates and the API is reachable before exercising any business endpoint.

Practitioners

Clinic-bound provider records. Every practitioner belongs to exactly one clinic. A practitioner’s email maps to a login identity, so an email already in use returns 409. Deleting a practitioner de-lists rather than destroys it.

Clinics

Clinics are the partition that practitioners, patients, and appointments belong to. Deleting a clinic de-lists rather than destroys it. A clinic cannot be deleted while it still has active practitioners, patients, or appointments: that returns 409 with problem type clinic-not-empty and counts of the blocking dependents. Clear or reassign the dependents first.

Patients

Patient records are maintained per organization: a patient created by your organization is yours alone, and the same person may exist independently under another organization. Email is not unique — duplicate emails within or across organizations are legitimate, because families commonly share an inbox. These records carry protected health information; handle and store them accordingly. A delegated token (see "Acting as a clinician") narrows this surface to the token clinician's roster.

Playrooms

Playrooms are the themed virtual spaces a clinician runs a session in: a name, an age band, a colour theme, and the set of session items available inside. Each playroom belongs to exactly one practitioner, so this surface requires a delegated token (see "Acting as a clinician") on every verb; an organization token is refused. Every new practitioner account starts with a set of PlaySpace-created rooms, flagged is_default. There is no delete endpoint: unpublish a room with PATCH setting published to false.

Toolkits

Toolkits are named bundles of session items, using the same item vocabulary as a playroom but without the room theming. Like playrooms they belong to a single practitioner and require a delegated token on every verb, ship as PlaySpace-created defaults on a new account, and have no delete endpoint — unpublish with PATCH setting published to false.

Appointments

Appointments link one practitioner and one patient who belong to the same clinic. There is no delete endpoint: cancel an appointment with PATCH setting status to cancelled. Cancelling removes the appointment from connected calendars and notifies the patient. A delegated token (see "Acting as a clinician") narrows this surface to the token clinician's own appointments.

Forms

Questionnaires a clinician authors and owns. Each form belongs to a single practitioner, so this surface requires a delegated token (see "Acting as a clinician") and always lists that clinician's own library. Only published forms are listed: a draft is still being authored, and answers recorded against one would not be meaningful. Answers are never returned here — a listed form is a blank template. To have a patient fill one, mint an embed token for the form and frame the embedded form surface.

Storybooks

Illustrated stories a clinician creates and owns. Every endpoint here requires a delegated token (see "Acting as a clinician"): a story belongs to one clinician, so an organization-wide token has nobody to scope to and is refused. Generation is asynchronous and bills per story — the response returns the story in its generating state, so poll it rather than retrying the create. Image links expire about an hour after they are issued: re-read the pages for fresh links, or fetch the asset bytes, rather than storing a link.

Games

Live sandtray and dollhouse sessions, and the scenes they leave behind. Starting a session returns one ready-to-frame URL per seat — clinician and patient — both bound to the same session key, so the two participants share one scene. Every endpoint here requires a delegated token (see "Acting as a clinician"), and the clinician is read from the token rather than from the request. Deleting a saved scene de-lists it rather than destroying it. Scene preview images are served as bytes and most scenes have none, so check has_thumbnail before asking for one.

Notes

Clinical notes a clinician writes about a session, including the ones PlaySpace drafts automatically from a recorded session. Read-only: a note is the clinician's own record, so this API can return one but can never create, change or remove one. Every endpoint here requires a delegated token (see "Acting as a clinician") — a note belongs to one clinician, so an organization-wide token has nobody to scope to and is refused. Each note carries the appointment, patient and practitioner it belongs to as ids on your own records. Bodies are omitted from the list by default and returned on request; a single note always carries its body. The verbatim, speaker-diarised session recording is returned only by GET /v1/partner/notes/{id}, and only when you ask for it with include=transcript — never on the list, at any page size.

Exports

A complete copy of one clinician's PlaySpace records, delivered as a single ZIP archive. Every endpoint here requires a delegated token (see "Acting as a clinician"): an export is one clinician's whole record, so an organization-wide token has nobody to scope to and is refused. Starting one is asynchronous — the response is the export in its queued state, so poll it rather than retrying the start. A clinician can have only one export running at a time and that slot is shared with the exports they start themselves, so a start while one is in flight returns 409. A finished archive stays downloadable for seven days and is then deleted. The download answers a redirect to a short-lived link: follow it and fetch the bytes promptly rather than storing the link.

Embed

Short-lived tokens that let your own application frame a PlaySpace surface for one clinician. Mint them server-side, once per session, and never expose your partner credential to a browser. Requires a delegated token (see "Acting as a clinician"); the clinician the surface acts as comes from your token, never from the request body. Supply the exact origins that will frame the surface — an origin you omit cannot render it.

Clinic community

What the clinicians of one clinic have shared with each other: worksheets, storybooks and forms a practitioner published for colleagues to preview and copy into their own library. Delegated tokens act as one clinician; an organization token may list one clinic's items.

Session configuration

Worksheets

What is not here

This table is the whole external surface. If an operation is not listed, no route serves it — see what you can build for the shape of the platform, and the machine-readable OpenAPI document for the full contract.