API & Contracts
PsyCloud's public surface is best understood as contracts first, code second. Studios, SDKs, importers, the runtime, and the data pipeline all interoperate by agreeing on a small set of versioned JSON contracts. If you are integrating with PsyCloud — generating studies, consuming telemetry, or building tooling — these contracts are the stable boundary to target. The TypeScript runtime API is documented separately and is lower-level.
The core library is versioned 0.0.1 and is not published to a package registry; you consume it
from the monorepo. Contracts carry their own schema versions (e.g. telemetry 2.0.0,
manifests 1.0.0) and are the most stable thing to build against. Expect runtime module shapes to
move faster than contracts.
The stable contracts
| Contract | What it defines | Version | Reference |
|---|---|---|---|
| Component manifests | The ~80 built-in components (stimuli, responses, containers) and their config schemas. Ids look like psycloud.stimulus.text@1.0.0. | 1.0.0 | Components · Manifests & Schemas |
| Study Bundle | The compiled, runnable study — design program, screen program, and bindings — that the runtime executes. | v0.1 | Manifests & Schemas |
| Design / Screen / Bindings programs | The canonical authoring output every language (Studio, R, Python, CoffeeScript) compiles to. | 0.1 / design v0.2 | Core Concepts |
| Telemetry envelope | The event stream a run emits (session_start, trial_start, response, …). | 2.0.0 | Telemetry & Events |
These live in the repo under src/manifests/ (component manifests + JSON schemas), src/ir/
(IR, design, and bundle schemas), src/telemetry/ (event types + EventEnvelope), and are
documented in prose under docs/contracts/.
Generating the runtime API reference
The low-level TypeScript API (classes, functions, interfaces for flow, factory, the component
library, the design builders, and more) is documented with TypeDoc. Generate
it from the repo root:
npm run docs:apiThis emits Markdown (via typedoc-plugin-markdown) covering the entry points configured in
typedoc.json — including src/flow.ts, src/factory.ts, src/stimresp.ts, the canvas and HTML
components, and the fluent experiment builder.
The generated TypeDoc output is not currently published on this site. Run npm run docs:api
locally to browse it, or read the source under src/. Most integrators want the
contracts above, not the runtime internals.
Authoring APIs (SDKs)
If you want to build studies programmatically rather than integrate at the contract level, use a language SDK — they emit the contracts above for you:
psycloudpy — the fluent builder and expression DSL.
psycloudr — the same model, idiomatic R.