PlaySpaceWhat you can build
PlaySpace builds the interactive layer of child and family mental health care: a shared sandtray two people can move figures in from different cities, a dollhouse, a collaborative whiteboard, therapeutic games, illustrated storybooks written for one child, worksheets and forms. This page is the honest menu of how much of that a partner can reach from outside PlaySpace today, and what is still internal.
There are four integration levels. They are a ladder, not a menu of alternatives: each one is the level below it plus more of your own work. Pick the lowest level that does the job, and move up only for the thing it lacks. Most partners end up on more than one, because the level that suits a clinician's screen is rarely the level that suits a nightly synchronisation job.
Level 1 — the whole workspace in one frame
What the clinician sees. The real PlaySpace workspace inside your product: its navigation, its header, its feature gating, acting as them. Your domain, your page, no PlaySpace login. Their day, their calendar, their clients, their notes, and everything they create — storybooks, worksheets, forms and the rooms that hold them.
What you build. One route on your backend that mints a token for the signed-in clinician, and one frame in your page. Nothing else.
What you cannot do at this level. Anything about one named patient, and anything carrying a live join credential. The frame shows the controls, presses them, and hands the request back to you — so at Level 1 those presses go unanswered. The framed calendar deliberately carries no join link at all.
Level 2 — the whole workspace, plus host controls
What the clinician sees. Exactly Level 1, with the controls now working. Pressing Open session on an appointment opens a session. Choosing a client under the in-person tools starts one. Filling a form with a client opens the form. Sending a form emails it.
What you build. Four handlers, each of them a call from your own server with your own credential: mint the session links, create an in-person appointment and mint its links, mint a patient-bound token and frame the form yourself, mint a patient-bound token and ask PlaySpace to send the form.
What you cannot do at this level. Change what is inside the frame. The workspace is the product, the areas it offers are decided by the clinician's PlaySpace entitlements, and nothing you pass widens them.
Level 3 — a single PlaySpace surface at a time
What the clinician sees. One PlaySpace thing in a panel of your own choosing, surrounded by your interface. A storybook reader beside a chart. A form to fill in during a session. A live sandtray or dollhouse, two seats on one scene.
What you build. The same token route, plus a component per surface: you choose the mode, pass the identifier it needs, and act on the event it hands back.
What you cannot do at this level. Frame the areas that exist only inside the workspace — clinical notes, the client roster, the calendar, the day's summary, and the Rooms area. Their data is still readable from your server; what has no single-surface form is the screen.
Level 3: single surfaces, and a reference page per surface: storybooks, forms, worksheets, games, the whole workspace
Level 4 — the Partner API directly
What the clinician sees. Nothing PlaySpace made, unless you hand them a session link and let PlaySpace host the whole thing.
What you build. Server-to-server calls. The records a session runs against, the content a clinician produced read back into your own product, storybooks generated overnight, session links dropped into your own appointment view.
What you cannot do at this level. Put a PlaySpace surface on a screen without either framing one — Levels 1 to 3 — or sending someone a hosted session link.
Level 4: the Partner API directly
You can bring your own video call. After PlaySpace enables partner video and approves your HTTPS origins, each new virtual appointment requires clinician and patient provider URLs. The returned session links still open PlaySpace; each participant receives only their own provider URL there. Activities and PlaySpace admission work independently of the call. Inline and separate-window presentation are supported. PlaySpace audio recording remains available when the organization's recording settings and clinician access allow it. See Use your own appointment video.
What is reachable today, surface by surface
| Surface | From your server | In the framed workspace | As a single surface | In a hosted session |
|---|---|---|---|---|
| Clinics and practitioners | Create, read, update, soft-delete | No | No | No |
| Patients | Create, read, update, soft-delete | The clinician's roster, and one client's usage summary | No | No |
| Appointments | List, get, create, update, session links | The calendar, and today's launchable list | No | No |
| Storybooks | List, generate, read, make shelf-ready, delete, download | Author, read, publish and shelve | Author, read | Read from the shelf |
| Worksheets | List, create, read, delete, download | Upload, read, edit, delete, shelve | Upload, read, edit | Read from the shelf |
| Forms | List published forms, create, make shelf-ready, delete, read submissions | Author, list, preview, place on a shelf | List, author, fill, place on a shelf | Open one shared to a playroom |
| Sandtray | Start a session, read and delete saved scenes | No | Live, two seats | Yes |
| Dollhouse | Start a session, read and delete saved scenes | No | Live, two seats | Yes |
| Whiteboard | No | No | No | Yes |
| Games catalogue | No | No | No | Yes |
| Playrooms | List, create, update, attach content | The Rooms area: list, create, edit, and one room's shelf | No | The space the session runs in |
| Toolkits | List, create, update, attach content | Only as a destination when placing content on a shelf | No | The named bundles inside that space |
| Clinical notes | List and read the acting clinician's notes | Read | No | No |
What is not reachable from outside PlaySpace yet
Stated plainly, because a gap nobody names gets assumed away. Every item below exists inside the product and has no external surface at all today.
- Exports. There is no export endpoint and no bundle format. A clinician's data request is served inside PlaySpace.
- A change feed. There are no webhooks and no ordered feed of what changed. You poll the resources you care about, or you act on the lifecycle events an embedded surface sends your page.
- A unified artifact index. There is no single artifact type and no cross-type query, so "everything this child has made" is assembled by you from the individual lists.
- Sessions as a resource. A session is a side effect of minting appointment links. There is no session object, no status model, no summary and no participant record.
- Addressing a record by your own identifier, and
upsert. Every write creates or updates by PlaySpace identifier. You create the record and you store the identifier we return. - Caregiver and dependent links, and any hierarchy above the clinic. Practitioner roles are recorded but gate nothing.
- An embedded whiteboard or game catalogue. Both exist in PlaySpace and are reachable through a hosted session link, not as a component.
- Generation beyond storybooks. Worksheet, form, game and three-dimensional model generation are internal. Storybook generation is the one generation endpoint on the partner surface.
- Writing a clinical note from your server. Notes are readable from your server, and so is the verbatim session transcript behind a drafted one (Read a session note); creating and deleting a note stay inside PlaySpace entirely. A clinician can edit, sign and unlock their OWN note without leaving your product, but only in the framed workspace on a seat minted
note:write— the clinician does it, not your application. - Usage, quota and spend reporting. The health endpoint is an authenticated liveness check, not an operational surface.
- A public sandbox. There is no permanently addressable sandbox with stable synthetic data and a self-serve key. Integration work happens against the development host, with a credential you apply for there.
- Any package other than
@playspace-health/embed. No framework wrapper beyond the React components, and no separate server package — the server client is the@playspace-health/embed/serverentry point of that same package, and it wraps the embed-surface operations. Everything else you call directly over HTTP.
What we ask of you
A token endpoint on your own backend. One route that authenticates your user and returns an embed token minted for them. It exists so your Partner API credential never reaches a browser.
The origins you will frame from. Named in the mint call, checked at mint time. A malformed origin is an error you can read rather than a blank rectangle you have to diagnose from a browser console.
A delegated token for anything a clinician owns. Storybooks, worksheets, forms, playrooms, toolkits, game sessions and embed tokens all belong to one practitioner. An organisation-wide token has nobody to act as and is refused.
Somewhere to keep our identifiers. Until external-identifier addressing exists, the correspondence between your records and ours lives in your database.
What we do not ask of you
We do not ask you to move your data. There is no import, no nightly file and no reconciliation job. You create records here as you need them.
We do not compete with your core. PlaySpace does not schedule, bill, or handle claims, and nothing here writes into your clinical notes.
We do not require your clinicians to hold their own PlaySpace subscription. A practitioner your organisation creates through the Partner API is a practitioner PlaySpace accepts.