ish Usage API

openapi: 3.2.0
info:
  contact:
    name: ish developer platform
    url: https://docs.ishlabs.io/
  description: 'The ish Developer API: the entry point for getting human feedback on whatever you''re building, in whichever format you need. Its first surface is **sessions**: you open a session for one of your people inside *your own* environment, submit what that person perceives (human-sensory observations: a rendered screen, an error message) along with the set of actions your environment currently offers, and they decide one action per turn and tell you how it felt. Your code executes the chosen action and loops. **The loop is decide-only: ish never locates, drives, or executes anything inside your environment.** You stay in control of what runs; we tell you what a person would do next and why. ## Vocabulary


    The public vocabulary is **workspace**, **person**, **environment**, and **session**, and the wire uses these names directly:


    - `workspace_id`: the workspace that owns the person and is billed for the session (the create path is `/workspaces/{workspace_id}/sessions`). - `person_id`: the person the session drives. Two kinds are available to you: the ones your workspace owns, and the ones published in the shared ish library. Both are listed and searchable under `/v1/workspaces/{workspace_id}/people`, and each carries an `owner` saying which it is. - `environment_id`: a registered environment in that workspace: a named target with its own operating notes and default action vocabulary. Register one and reference it, or describe an ad-hoc one inline on the session; supply exactly one of the two. **"Session" here means one API session: a single person working toward one task in your environment, turn by turn.** It is not the ish product''s notion of a study session (someone sitting down with a study), and it is unrelated to a browser session. Sessions live under `/v1/sessions`. ## Authentication


    All requests use a bearer token: `Authorization: Bearer `. The token is a **workspace API key** (prefix `ish_sk_live_`), a workspace-scoped machine principal minted in Settings > Developers and shown exactly once at mint. Scopes: `sessions:run` (create, submit turns, close), `sessions:read` (read the session and trace), `environments:read` / `environments:write` for the environment registry, `tasks:read` / `tasks:write` for the task registry, `people:read` / `people:write` for the people you can run a session for, and `usage:read` for this workspace''s consumption, limits and rate-limit budgets. Keys are minted with `sessions:run`, `sessions:read`, and `tasks:read`; ask for any `:write` scope, and for `people:read` and `usage:read`, explicitly. `usage:read` is never implied by another scope: it covers the shape of the whole workspace''s operation, not just the lane a key was minted for. An ish user access token (JWT) also works on the same header for personal scripts; server integrations should use keys. ## Versioning & forward-compatibility


    The API is versioned in the URL path (`/api/v1`). Several enum-typed and block-typed fields are **open unions**: new values may be added over time, and clients MUST tolerate values they do not recognize rather than failing on them. The field descriptions call these out. ## Correlation & errors


    Every response carries an **`X-Request-Id`** header; quote it in support requests. Error responses additionally echo it in the body as `request_id`. Two error-body shapes exist; parse defensively, they differ:


    - **`ValidationError`**: the request-validation layer (HTTP 422): a malformed body (wrong types, missing fields, an invalid observation `type`, a bad enum value, `parameters` that don''t fit the model). A field-level envelope (`error_code`, `errors[]`, `suggestions[]`; `suggestions` is CLI-oriented boilerplate; ignore it for API use). - **`Error`**: everything else, a `{ detail, request_id }` envelope. This covers the handler layer''s business-rule 422s (e.g. `exactly one image observation block is required`; `person has no renderable background`) as well as 401 / 402 / 403 / 404 / 409 / 429 / 502.'
  license:
    identifier: LicenseRef-Proprietary
    name: Proprietary
  title: ish Developer Usage API
  version: 1.11.0
servers:
- description: Production
  url: https://api.ishlabs.io
security:
- bearerAuth: []
tags:


# --- truncated at 32 KB (38 KB total) ---
# Full source: https://artifacts.apis.io/ishlabs-io/openapi/ishlabs-io-usage-api-openapi.yml