One primitive is spelled differently in each half of the product. In a
study (the CLI, the MCP server, and the web app) what a simulated person is
asked to do is an assignment. In the ish API the same idea is a
task: a per-workspace registry a session binds by id, or an inline
task
object on session create. They are separate records on separate endpoints, not
two names for one thing. Entries below name the lane where it matters.Core objects
| Term | Definition |
|---|---|
| Workspace | The top-level container that holds your studies, asks, people, sources, and secrets, and the unit ish bills and caps against. Alias prefix w-. |
| Study | The persistent unit of research: show simulated people something, read their reactions, change it, and run again. Alias prefix s-. |
| Iteration | One configured version of a study that attaches the single artifact (a URL, a media file, or a chatbot endpoint) participants experience. Labelled A, B, C, with alias prefix i-. |
| Ask | A lighter comparison: one prompt and one or more variants of creative put in front of a fixed panel. Alias prefix a-. |
| Round | One pass of an ask’s panel over a prompt and its variants. The first round is created with the ask; later rounds reuse the same people. An ask holds up to five. |
| Variant | One candidate inside an ask round: a headline, a hero image, an ad cut. Each has a kind and a value. |
| reference | A workspace flagged as a comparison target (product_type is always reference). Shares the w- alias prefix. Available through the MCP reference_* tools and the CLI’s ish workspace reference. |
| Benchmark | A clone of a study across a set of references so each reference runs the same study head to head. Available through MCP and the CLI’s ish study benchmark. |
People
| Term | Definition |
|---|---|
| Person | A persistent Person record, explicitly HUMAN or AI. A HUMAN Person may participate directly or through a simulated self; an AI Person participates only through simulation. |
| Participant | One run-scoped instance of a Person, explicitly HUMAN or AI. A HUMAN Person may participate directly or through a simulated self; an AI Person may participate only as AI. |
| contributor | The real person who supplies authorized evidence or corrections and controls how that contribution may be used. |
| Audience | Deprecated. Use panel for the set of people a run dispatches. The word survives as the audience: parameter on study_run and ask_run, which is not renamed. |
| Panel | The set of people a run dispatches: sampled from the pool, named explicitly, or generated to fit a brief. An ask’s panel is fixed at creation so every round runs the same people. |
| Pool | The people available to a workspace, filtered by demographic to assemble a panel. |
| Visibility | The scope that decides who can see and use a Person: workspace, shared, or platform. |
| Source | Real evidence (a transcript, recording, screenshot, support email, PDF) handed to person generation to ground the resulting Person in how someone actually reacted. |
| Situation | A short prompt put to a real person during person creation, in one of four forms, whose answer becomes behavioral evidence grounding that Person. |
Study definition
| Term | Definition |
|---|---|
| Modality | The kind of thing a study puts in front of people. ish supports eight: interactive, text, image, video, audio, document, chat, survey. |
| Content type | An optional sub-type that tunes a modality (for example editorial or reference for text). Six modalities carry one; interactive and chat do not. |
| Assignment | Study lane. One thing a simulated person is asked to do during a run. A study carries one or more, run in order. Authored as --assignment on the CLI and assignments through MCP. The ish API’s equivalent is a task. |
| Step | An ordered atomic action inside an assignment, each a name of 1 to 80 characters plus an optional description of up to 500. An API task accepts the same shape, stored but not yet read during a session. |
| Questionnaire | The set of questions each simulated person answers. Lives on the study, alongside assignments. |
| Site access | How ish reaches a gated URL: public, HTTP basic auth, a session cookie, or a login form. Configured per workspace. |
| Secret | A per-workspace named value that backs a {{secret:KEY}} placeholder in chatbot endpoint config, resolved on the wire at dispatch. |
Running and reading
| Term | Definition |
|---|---|
| run | To send simulated people through a real surface end to end (a link, an app, a video) against the latest or a named iteration. A verb: there is no run object, and a participant belongs to an iteration, an ask or a session directly. |
| Dispatch | One request that sends a group of simulated people at once. Capped at 20 participants, independent of tier. |
| Reactions | What a simulated person reports during one turn or segment: what they noticed, felt, did, and why. |
| Reported journey | The full record a run returns for one participant: transcript, signals, and the reasoning behind them, plus screenshots for interactive runs. Not a score. |
| Signals | Derived measures within a reported journey, including sentiment, friction, blockers, and completion. Each carries the reasoning behind it. |
| Sentiment | A per-participant label and valence, rolled up as a histogram across the panel from completed participants only. |
| Share link | A public, no-login URL to one study’s results, hosted on the web app, that anyone opens in a browser to read the run as a stakeholder would. |
The ish API
The ish API puts a simulated person inside your own environment’s decision loop, so it carries its own object vocabulary. These terms belong to that lane only.| Term | Definition |
|---|---|
| Session | One participant working toward one task inside one environment, turn by turn. Not a study run, and unrelated to a browser session or the login session ish status reports. |
| Task | A named intent, registered per workspace, that a session binds by id: the bind freezes the task’s instructions and revision onto the session, so later edits never change what a past session ran against. A session can describe one inline instead. The study lane’s equivalent is an assignment. |
| Environment | The target a session runs against, registered once and referenced by id instead of described on every session. |
| Turn | One exchange in a session: you send what the participant perceives and the actions available, and the participant decides. One row per turn on the server, so you never re-send history. |
Credits and limits
| Term | Definition |
|---|---|
| Credits | A usage allowance every run draws down. Paid plans refill monthly; the free tier gets a one-time grant of 200 at signup. Not money. |
| Limits | Per-tier caps on how many entities (workspaces, studies, people) an account can hold. Enforced at create time, distinct from credits. |
| Dispatch cap | The structural limit of 20 participants on every single dispatch, independent of tier and credits. Larger panels split into multiple runs. |
Surfaces and tooling
| Term | Definition |
|---|---|
| CLI | The ish command line, reading as ish <noun> <verb>. One developer surface onto studies. |
| MCP server | The same study operations exposed as tools an AI agent calls, hosted at https://mcp.ishlabs.io/mcp. The other developer surface onto studies. |
| ish API | The HTTP API under https://api.ishlabs.io/api/v1, where a simulated person runs inside an environment you drive turn by turn. A separate lane from studies, with its own nouns (see above). |
| Active context | The CLI’s saved workspace, study, and ask, kept in ~/.ish/config.json (or ISH_HOME), so you do not repeat IDs. The MCP server is stateless. |
| Alias | A short, prefixed id every object carries (w-, s-, i-, a-, p- for a person, ps- for a source) that any tool taking that object’s id accepts. |
New to ish? Start with how ish works for the mental model, then the CLI quickstart or connect an agent.