Skip to main content
The ish API is the entry point for human feedback on whatever you are building, in whichever format you can render it. Instead of handing ish a finished artifact and reading a reported journey afterward, you put a person directly inside your environment’s decision loop as a participant and watch them react while they move. Each turn, you show the participant what a human would see and the set of actions available right now. They pick one action and tell you how they felt about the moment. You carry the action out in your own environment, capture the next view, and take the next turn. An environment here is your own product surface being tested: the site, app, device, or world you are building. It is not a deploy target, a hosting tier, or a sandbox we run for you. You render it and you execute in it; ish never touches it.
Breaking change, 2026-07-28. The public noun is now person: persona_id is person_id on create, and session reads carry person_id (plus participant.person_id on list rows). An environment descriptor’s platform field is now kind. Closing a session moved from DELETE /v1/sessions/{id} to POST /v1/sessions/{id}/close, and both create and close now return the full session body instead of a five-field stub. The changelog has the complete entry and the one before it.

​
The idea in five lines

  • A participant decides what to do inside your environment from what a human would see.
  • Each turn you send one rendered frame (what the participant perceives) plus the actions available right now.
  • ish replies with the chosen action and how the participant felt: a comment, a sentiment, an intensity.
  • You execute that action in your environment, capture the frame again, and send the next turn.
  • ish only decides; you execute. No locators, no automation on our side. See the decide-only loop.

​
What makes this different from a study

The ish CLI and the ish MCP server drive the research app: a study sends simulated people through a finished artifact and reports back a journey once each one is done. The API is a separate surface with a different shape. Here the participant is a live decision brain inside your environment, one turn at a time, and you own both the rendering and the execution. The two surfaces share their foundations. A person is the same reusable simulated person, and a workspace is the same tenant that owns your people and holds your credits. They do not share studies, iterations, or runs. You do not need a study to use the API.

​
What the participant perceives

The participant reads meaning off the pixels, the same way a person sitting in front of your screen would. You send human-sensory frames only: an image now, with audio reserved for later. Structured state (a scene graph, game-state JSON, a DOM dump) is refused at the boundary, because a participant handed the true state is a solver, not a simulated human. The rules and the reasoning live in observations.

​
Which people you can run

A session runs one person, and the API admits two classes:
  • Workspace-owned people, the profiles your workspace created and owns.
  • Platform-library people, the owner-less profiles the platform curates for broad reuse.
Real-person “me” profiles are out of scope for the API by policy, not by accident: a person’s own digital profile carries likeness and personal data that this surface deliberately does not touch. The create call refuses anything outside the two classes above with a 403. For the person model itself, see people and audiences.

​
Two decision modes

Every session runs in one of two modes, and the create response tells you which:
  • Intent is the default and the product path. The participant says what they want, and a resolver maps that onto one of your declared actions. Intent resolves three ways: matched (an action to run), no_match (the participant wanted something your environment does not offer, usually the signal you are after), and none_needed (the participant is done).
  • Direct is an evaluation baseline where the participant picks one of your declared actions itself. It sees the action list, so it is not the path a real integration uses.
Both are covered in intent and resolution.

​
Authentication

Every request carries a bearer token: a workspace API key you mint in Settings, then Developers. See authentication.

​
Where to go next

Quickstart

Create a session, run one turn, and read the decision.

Run the session loop

The complete integration contract: ordering, errors, retries, pagination.

The decide-only loop

Why ish decides and you execute, and what that buys you.

Author your environment

Declare actions, write labels that do not leak, render frames that decode.

Find a person

Read and search the pool you can open a session for, and what each person carries.