PlaySpaceGlossary
Terms that mean something specific on this platform.
Access token — The bearer token you present on every request, obtained by exchanging your client credentials with Auth0. Server-side only. Its lifetime is measured in hours; cache and reuse one rather than minting per request.
Appointment — A scheduled meeting linking a practitioner and a patient inside one clinic. All three must belong to the same clinic. Cancelling is a PATCH setting status to cancelled, not a DELETE.
Audit log — The tamper-evident record PlaySpace writes for every authenticated request, each row hash-chained to the previous one in your organisation's chain. It holds identifiers, statuses and counts, never patient data. It is what an X-Request-Id resolves against when you quote one to support.
Client credentials — Your organisation's client identifier and secret, issued once on approval. They are exchanged for an access token; they are never sent to the API itself, and never reach a browser.
Clinic — The top of the resource model and the container for everything else. Create one before creating practitioners or patients. Its name is unique within your organisation, case-insensitively.
Cursor — An opaque position marker used for pagination. Read meta.pagination.next_cursor, pass it back as cursor, and repeat until it is null. Never construct one by hand.
Delegated token — An access token bound to one practitioner, requested by adding practitioner_id to the client-credentials call. Narrows reads to that clinician's roster and appointments, requires writes to be self-attributed, and is the only token that can reach anything a clinician personally owns. Enabled per organisation by PlaySpace.
Embed capability token — A short-lived token minted by POST /v1/partner/embed-tokens that authorises one embedded surface in an iframe. Names its capabilities, the origins allowed to frame it, and — where the surface writes patient data — the patient it writes for. Minted server-side from a delegated token, per page load.
Form — A structured instrument a clinician authors and a client answers. Listing returns that clinician's published forms only; a draft is still being authored. Answers never leave PlaySpace: they are readable by the clinician inside the product, never through this API.
Game save — A stored scene from a sandtray or dollhouse session, belonging to one clinician. Carries a preview thumbnail; its scene data is large and is omitted from list responses.
Game session — One live two-seat sandtray or dollhouse scene. Starting one returns two embed tokens, a practitioner seat and a patient seat, bound to the same session and the same patient.
Idempotency key — A caller-chosen opaque string, required on every POST, PATCH and DELETE. A repeat with the same key and payload within 24 hours replays the original response rather than performing the work twice. A missing key is a 422.
Organisation token — An access token with no practitioner_id, seeing every clinic, practitioner, patient and appointment your organisation owns. The right token for back-office work, and the wrong one for anything acting as a single clinician.
Partner organisation — Your tenant. Derived from your token on every request, never sent in one. Another organisation's data is unreachable and unaddressable; its identifiers behave exactly like identifiers that never existed.
Patient — The identity resource for a person receiving care. PlaySpace uses "patient" on the wire and "client" in prose, following how clinicians in this field usually speak. No PlaySpace account or login is created for one.
Playroom — A themed space a clinician runs a session in: a room type (child, teen, adult), a colour palette, and the session items enabled inside it. Belongs to one clinician, so it is reachable only with that clinician's delegated token. Its artwork is derived from the theme and is read-only.
Practitioner — The identity resource for a clinician. A practitioner your platform vouches for is one PlaySpace accepts; no PlaySpace account or login is created for one you create. A clinic owner can later add direct PlaySpace logins for their whole clinic through an in-workspace upgrade, entirely on their own initiative — your integration is unaffected either way: every delegated read and write keeps working exactly as before. playspace_account_linked_at on the practitioner tells you which is true for a given person. playspace_login_status says where that stands for each person. Once a clinic has upgraded, a practitioner you add is emailed a PlaySpace set-password link automatically, and setting one to disabled or deleting them also suspends their direct PlaySpace login; you cannot disable or delete the clinic's owner while the clinic is upgraded (409 practitioner-owner-protected), reassign owner first. Carries a status of active or disabled, which is how you suspend that clinician's delegated access regardless of whether they have also upgraded.
Problem document — An RFC 9457 error body, served as application/problem+json. Branch on type, which is a stable identifier; never on title or detail, which are prose.
Rate limit — Requests per unit time, two windows per organisation, per minute and per hour. The more restrictive window wins. Clears in seconds; honour Retry-After. A request that fails authentication does not consume budget.
Role — A practitioner's membership role in their clinic: member, admin or owner. It is informational and settable, and it gates nothing on this API. Access control is which token you attach, not which role you set.
Sandtray — One of the two live game surfaces, alongside the dollhouse. A tray with a categorised figure library, synchronised between two participants. Sand tray work is an established modality in child and family therapy; this is the remote form of it.
Scope — A resource:verb permission string carried inside your token. The vocabulary is twelve strings across clinics, practitioners, patients and appointments. Fixed on the credential at approval, and changed by asking PlaySpace rather than per call.
Session item — A capability enabled inside a playroom or toolkit: activity_shelf, multiplayer_games, single_player_games, whiteboard, sand_tray, dollhouse.
Session link — A whole-page join link for an appointment, minted in a pair: one for the patient, one for the clinician. Each is a short https://<host>/join/<code> address that redirects to that participant's session credential, so each IS a credential — deliver it to its one intended person and keep it out of your logs. A short link is not a shareable identifier. The hosted alternative to embedding.
Shelf-ready — A flag on a piece of content saying the clinician has additionally shared it to their playrooms and toolkits, which is what makes it eligible to open from inside a live session. Off by default, so expect false for most of a library. Eligible is not placed: placement is a separate attachment.
Soft delete — The only kind of delete this API performs. A deleted resource is de-listed rather than destroyed: it returns 404 and drops out of lists, unless the list supports include_deleted=true, in which case it returns carrying deleted_at.
Storybook — An illustrated book generated for a clinician from their own prompt. Created asynchronously, so the create response is the book in its generating state and you poll what you were handed. Its title is model-generated and can echo details of the child it was written for: treat titles as patient-adjacent, fine in a clinical interface, not in logs or analytics.
Toolkit — A curated set of content belonging to one clinician, lighter-weight than a playroom and without the theming. Like a playroom it carries a content shelf.
Transcript — The verbatim, speaker-diarised record of what was said in a session PlaySpace drafted a note from, as an ordered list of speaker turns — every consecutive word from the same speaker joined into one entry — each carrying speaker, text, start_seconds and end_seconds. Returned by GET /v1/partner/notes/{id} and only when you add include=transcript; never on the list, at any page size. Absent when you did not ask, null when the note has none. It is everything both people said rather than what the clinician chose to write down, so treat it as the most sensitive thing this API returns.
Worksheet — A page-based activity in a clinician's library, created by converting a document inside an embedded surface rather than through this API. A client's annotated copy is clinical content and is never returned here.