Glossary
Terms that mean something specific on this platform.
Access token — A one-hour bearer token obtained by exchanging client credentials. Authorises the REST API. Server-side only. The server SDK manages these and you never see one.
Artifact — Anything PlaySpace produced and kept: a storybook, a worksheet or a completed copy of one, a form response, a saved sandtray or dollhouse, a whiteboard snapshot, a generated game, a three-dimensional model, a session summary, a note. Every artifact carries the attribution triple.
Attribution triple — createdBy, subject, session. The clinician who made an artifact, the client it was made for, and the session it happened in. createdBy is always present; the other two may be null. This is the structure the client library, the export bundle, the spend report and the session summary are each a query over.
Caregiver link — The relationship between a dependent client and the adult who holds consent. Decides who receives a session link, who may join alongside a child, and who may request an export. Not decorative — the flags on it are checked.
Change feed — One ordered, resumable feed of everything that changed in your organisation. Polled, not pushed. There are no webhooks.
Client credentials — Your organisation's long-lived identifier and secret. Authorise everything your organisation can do. Server-side only, never in a browser.
Clinician — One of two roles. A clinician token renders the facilitation side of every surface: figure library, tool palette, navigation, saves, session controls.
Cursor — An opaque, monotonic position marker. Used for pagination and for the change feed. Store it, resume from it, and you cannot miss an entry or process one twice.
Embed capability token — Older name for a session token. Retained in some material; the two are the same thing.
External identifier (externalId) — Your identifier for a person or an appointment. Unique within your organisation per resource type. Works everywhere a PlaySpace identifier does, prefixed ext: in a URL. This is why you never need to store a PlaySpace identifier.
Generation — Producing new content with a model: a storybook, worksheet, form, game or three-dimensional model. Always asynchronous, always a job, always metered against quota.
Idempotency key — A unique string on every mutation. A repeat with the same key and body replays the original response rather than performing the work twice. Required, not optional.
Job — Asynchronous work with a status, a progress percentage and a terminal result. Every generation call returns one. A failed job does not consume quota.
Library content — An artifact with no subject: made for the clinic's shelf rather than for one child. The distinction matters for exports, which follow a person.
Patient — One of two roles, and also the identity resource for a client. A patient token renders the participation side of a surface only. PlaySpace uses "patient" on the wire and "client" in prose, following how clinicians in this field usually speak.
Playroom — A themed environment aggregating live surfaces and content, typed child, teen or adult. A toolkit is the lighter-weight equivalent.
Practitioner — The identity resource for a clinician. A practitioner your platform vouches for is one PlaySpace accepts; no PlaySpace account or login is created.
Problem document — An RFC 9457 error body. Branch on type, which is stable; never on title or detail, which are prose.
Quota — The generation allowance per organisation per period. Distinct from a rate limit: waiting does not clear it, only resetsAt does. Both surface as 429.
Rate limit — Requests per unit time, two windows, per organisation. Clears in seconds. Honour Retry-After.
Role — clinician or patient. Carried by the session token, which is why components take no role parameter and cannot be handed the wrong one.
Sandtray — The flagship live surface. A three-dimensional tray with a categorised figure library, synchronised between participants. Sand tray work is an established modality in child and family therapy; this is the remote form of it.
Session — One appointment's worth of PlaySpace, with a clinician, participants, a playroom and a surface ceiling. Everything produced inside one is attributed to it. Does not have to correspond to a real appointment — a session with an identifier of your own devising is a durable container for asynchronous work.
Session token — Short-lived, role-scoped, single-person. Minted by your backend, consumed by a browser, authorises a rendered surface. Fifteen minutes by default, sixty maximum, renewed silently by the SDK.
Subject — The client an artifact was made for, or the person a token was minted for. Context distinguishes them.
Surface — A thing a person interacts with: sandtray, dollhouse, whiteboard, games, playroom, storybooks, worksheets, forms, studio, models. Declared twice — on the session as a ceiling, on the token as an individual's share of it — and the narrower always wins.
Surface ceiling — The surfaces list on a session. Nothing outside it can be opened by anyone in that session, whatever a token or a front end asks for.
Toolkit — A curated set of content, lighter-weight than a playroom and without environment settings.
Upsert — The write verb on identity resources. Creates on first sight, updates thereafter, keyed on externalId. Safe on every synchronisation pass, which is why there is no reconciliation story.
Worksheet copy — A client's filled-in instance of a worksheet. Its own artifact, distinct from the blank it came from: the blank has no subject, the copy has one.