> ## Documentation Index > Fetch the complete documentation index at: https://docs.ishlabs.io/llms.txt > Use this file to discover all available pages before exploring further. # List People > List the people you can open a session for, newest first. Two kinds of person are reachable: the ones your workspace owns, and the ones published in the shared ish library. Both are usable in a session, and each row's `owner` says which it is. People that other workspaces have published are deliberately NOT listed: you could not open a session for them, and listing what you cannot use is worse than not listing it. Keyset-paginated: page forward with `after` set to the previous response's `next_cursor`, and stop when `has_more` is false. For anything beyond a name match, use the search endpoint. ## OpenAPI ````yaml /api/openapi.public.json get /api/v1/workspaces/{workspace_id}/people openapi: 3.1.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. That is why 422 is documented on the responses below as either shape (`oneOf`). **Branch on `detail.error_kind`, not on the status code.** On every refusal this API classifies, `detail` is an object rather than a string: ```json { "detail": { "error_kind": "turn_index_mismatch", "message": "expected turn_index 4, got 3", "expected_turn_index": 4 }, "request_id": "9f2c...", "docs_url": "https://docs.ishlabs.io/api/errors#turn_index_mismatch" } ``` `error_kind` is the stable, machine-readable classification; `message` is for humans and may be reworded; any further keys carry the specifics you would act on. One status often covers several kinds with different remedies. A 402 is either "top up" or "raise your cap"; a 429 is either "slow down" or "you are out of sessions for today". The status alone is not enough to decide what to do. `docs_url` links to that kind's entry in the error catalog. The set of kinds is an **open union**: new ones are added as new refusals are classified, so treat an unfamiliar `error_kind` as "an error of this status class" rather than failing on it. `message` is always present. ## Rate limits API keys carry a per-key request budget and, on session creates, a per-key daily session quota. Exceeding either is a `429` with a `Retry-After` header (also echoed as `detail.retry_after_seconds`) and a distinct `error_kind`: `rate_limited` resets within the minute, `session_quota_exceeded` on a day boundary. Both are transient and neither affects sessions that are already open. You do not have to wait for the `429` to find out. Every key-authed response, including the `429` itself, carries the budget it just spent: - **`x-ratelimit-limit`**: the ceiling for that window. - **`x-ratelimit-remaining`**: what is left in it after this request. - **`x-ratelimit-reset`**: **seconds from now** until the window resets. A delta, not a Unix timestamp. When a request charges more than one budget (a session create spends both), the headers describe the one closest to refusing you, so pacing off `remaining` is always pacing off the binding constraint. Treat all three as optional: they are absent when nothing was charged, and `reset` alone can be omitted if the limit backend cannot be read at that moment. User access tokens are deliberately not rate limited, so their responses carry no `x-ratelimit-*` headers. The per-key budgets exist because a key is a machine principal that can loop unattended; an interactive session is bounded by the person driving it. license: identifier: LicenseRef-Proprietary name: Proprietary title: ish Developer API version: 1.6.1 servers: - description: Production url: https://api.ishlabs.io security: - bearerAuth: [] tags: - description: >- Open a session for one of your people inside your own environment, submit what they perceive turn by turn, and read back the decision they made and how it felt. name: sessions - description: >- Register the targets your sessions run against, and the declared versions of each one. A registered environment carries its own operating notes and default action vocabulary, so a session only has to name it. name: environments - description: >- Register the intent a session works toward, so runs stay comparable across environments and over time. A session can also describe its instructions inline and skip the registry entirely. name: tasks - description: >- Find the person a session should run as. Read and search the pool you can draw on: the people your workspace owns, plus the ones published in the shared ish library. Read-only at this version. name: people - description: >- What this workspace has consumed, and what bounds it: the session usage series over time, the spend cap and the credits drawn against it, and the live rate-limit budgets this credential is spending. Read-only. name: usage paths: /api/v1/workspaces/{workspace_id}/people: get: tags: - people summary: List People description: >- List the people you can open a session for, newest first. Two kinds of person are reachable: the ones your workspace owns, and the ones published in the shared ish library. Both are usable in a session, and each row's `owner` says which it is. People that other workspaces have published are deliberately NOT listed: you could not open a session for them, and listing what you cannot use is worse than not listing it. Keyset-paginated: page forward with `after` set to the previous response's `next_cursor`, and stop when `has_more` is false. For anything beyond a name match, use the search endpoint. operationId: listPeople parameters: - in: path name: workspace_id required: true schema: format: uuid title: Workspace Id type: string - description: >- Restrict to one owner: `self` for people this workspace owns, `platform` for the shared ish library. Omit it to get both, which is exactly the set you can open a session for. in: query name: owner required: false schema: anyOf: - pattern: ^(self|platform)$ type: string - type: 'null' description: >- Restrict to one owner: `self` for people this workspace owns, `platform` for the shared ish library. Omit it to get both, which is exactly the set you can open a session for. title: Owner - description: Case-insensitive substring match on the person's name. in: query name: search required: false schema: anyOf: - maxLength: 200 type: string - type: 'null' description: Case-insensitive substring match on the person's name. title: Search - description: >- Look a person up by the id YOUR system gave them. Exact match, and at most one person can carry it, so a hit is a one-item page and a miss is an empty one. This is the lookup, and it lives here rather than on a path so that a missing external id is an empty result rather than a 404 you have to branch on. in: query name: external_id required: false schema: anyOf: - maxLength: 255 type: string - type: 'null' description: >- Look a person up by the id YOUR system gave them. Exact match, and at most one person can carry it, so a hit is a one-item page and a miss is an empty one. This is the lookup, and it lives here rather than on a path so that a missing external id is an empty result rather than a 404 you have to branch on. title: External Id - description: >- Restrict to the people one generation job produced. This is how a job's results are collected: poll the job, then list by its id. Reads its own writes. in: query name: generation_job_id required: false schema: anyOf: - format: uuid type: string - type: 'null' description: >- Restrict to the people one generation job produced. This is how a job's results are collected: poll the job, then list by its id. Reads its own writes. title: Generation Job Id - description: >- `false` (the default) lists live people; `true` lists the archive instead. The two sets are disjoint, so this chooses which one you are looking at rather than widening the list. in: query name: archived required: false schema: default: false description: >- `false` (the default) lists live people; `true` lists the archive instead. The two sets are disjoint, so this chooses which one you are looking at rather than widening the list. title: Archived type: boolean - description: Opaque keyset cursor from a prior page's `next_cursor`. in: query name: after required: false schema: anyOf: - type: string - type: 'null' description: Opaque keyset cursor from a prior page's `next_cursor`. title: After - in: query name: limit required: false schema: default: 25 maximum: 100 minimum: 1 title: Limit type: integer responses: '200': content: application/json: schema: $ref: '#/components/schemas/PublicPersonListResponse' description: Successful Response headers: X-Request-Id: $ref: '#/components/headers/XRequestId' x-ratelimit-limit: $ref: '#/components/headers/XRateLimitLimit' x-ratelimit-remaining: $ref: '#/components/headers/XRateLimitRemaining' x-ratelimit-reset: $ref: '#/components/headers/XRateLimitReset' '401': content: application/json: schema: $ref: '#/components/schemas/Error' description: >- The bearer token is missing, malformed, unknown, or revoked (`detail.error_kind = 'invalid_api_key'`). One kind covers all four deliberately: distinguishing them would confirm which guesses are real keys. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' x-ratelimit-limit: $ref: '#/components/headers/XRateLimitLimit' x-ratelimit-remaining: $ref: '#/components/headers/XRateLimitRemaining' x-ratelimit-reset: $ref: '#/components/headers/XRateLimitReset' '403': content: application/json: schema: $ref: '#/components/schemas/Error' description: >- The API key lacks the `people:read` scope (`detail.error_kind = 'insufficient_scope'`, with `detail.required_scope = 'people:read'`). Mint a key that includes it; an ish user access token is unconstrained by scopes. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' x-ratelimit-limit: $ref: '#/components/headers/XRateLimitLimit' x-ratelimit-remaining: $ref: '#/components/headers/XRateLimitRemaining' x-ratelimit-reset: $ref: '#/components/headers/XRateLimitReset' '404': content: application/json: schema: $ref: '#/components/schemas/Error' description: >- The workspace (`workspace_id`) was not found, or is not reachable with this credential. `detail.error_kind` is `workspace_not_found`. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' x-ratelimit-limit: $ref: '#/components/headers/XRateLimitLimit' x-ratelimit-remaining: $ref: '#/components/headers/XRateLimitRemaining' x-ratelimit-reset: $ref: '#/components/headers/XRateLimitReset' '422': content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/Error' description: >- Validation error. A request-shape failure uses the `ValidationError` envelope; a handler-raised domain-validation refusal uses the `Error` envelope. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' x-ratelimit-limit: $ref: '#/components/headers/XRateLimitLimit' x-ratelimit-remaining: $ref: '#/components/headers/XRateLimitRemaining' x-ratelimit-reset: $ref: '#/components/headers/XRateLimitReset' '429': content: application/json: schema: $ref: '#/components/schemas/Error' description: >- The API key's request rate limit is exceeded (`detail.error_kind = 'rate_limited'`). Transient: retry after the `Retry-After` interval, also echoed as `detail.retry_after_seconds`. Not applied to user access tokens. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' x-ratelimit-limit: $ref: '#/components/headers/XRateLimitLimit' x-ratelimit-remaining: $ref: '#/components/headers/XRateLimitRemaining' x-ratelimit-reset: $ref: '#/components/headers/XRateLimitReset' security: - bearerAuth: [] components: schemas: PublicPersonListResponse: description: |- A keyset-paginated page of people. Ordered `created_at DESC, id DESC`, the same order and the same envelope as the session list, so one pagination helper in an SDK drives both. properties: has_more: description: True when more people exist beyond this page. title: Has More type: boolean items: items: $ref: '#/components/schemas/PublicPersonResponse' title: Items type: array next_cursor: anyOf: - type: string - type: 'null' description: >- Opaque keyset cursor for the next page (pass as `after`); null on the final page. title: Next Cursor required: - items - has_more - next_cursor title: PublicPersonListResponse type: object Error: description: >- Generic error envelope for 4xx/5xx responses other than request-shape validation. properties: detail: anyOf: - type: string - additionalProperties: true type: object description: >- A human-readable message, OR a structured object carrying a machine-readable `error_kind` (e.g. `idempotency_conflict`, `turn_index_mismatch`, `decision_invalid`). title: Detail docs_url: description: >- Link to this error's entry in the error catalog. Present whenever `detail` carries a registered `error_kind`; absent on unclassified errors. title: Docs Url type: string request_id: description: >- Correlation id; identical to the `X-Request-Id` response header. Quote it in support requests. title: Request Id type: string required: - detail - request_id title: Error type: object ValidationError: description: >- Request body / parameter validation failure (HTTP 422). A field-level envelope so callers can pinpoint the offending field, value, and allowed values without parsing prose. properties: detail: title: Detail type: string error: title: Error type: string error_code: description: Stable machine code, e.g. `validation_error`. title: Error Code type: string errors: items: $ref: '#/components/schemas/FieldError' title: Errors type: array retryable: title: Retryable type: boolean status: title: Status type: integer suggestions: items: type: string title: Suggestions type: array required: - error - error_code - status - retryable - detail - errors title: ValidationError type: object PublicPersonResponse: description: >- One person, as an external integrator sees them. The field list is CLOSED and hand-maintained. It carries who the person is (identity + demographics + interests) and nothing about how ish came to hold that row: no moderation verdict, no publisher, no viewer-specific state, no internal config pointer, no custom fields. properties: accessibility_profile: anyOf: - additionalProperties: true type: object - type: 'null' description: >- Declared accessibility needs, as a nested object of boolean and enum flags. Only non-default keys are present. An open union: new keys appear over time. title: Accessibility Profile archived_at: anyOf: - format: date-time type: string - type: 'null' description: >- When this person was archived, or null while they are live. An archived person is hidden from the default listing and closed to edits, but stays readable by id and keeps every session that ran for them intact. `POST .../restore` clears it. title: Archived At avatar_url: anyOf: - type: string - type: 'null' description: Publicly fetchable avatar image, when one exists. title: Avatar Url bio: anyOf: - type: string - type: 'null' description: >- Free-text background in the person's own register. This is the bulk of what the model is told about them when a session runs. title: Bio city: anyOf: - type: string - type: 'null' title: City country: anyOf: - type: string - type: 'null' title: Country created_at: format: date-time title: Created At type: string date_of_birth: anyOf: - format: date type: string - type: 'null' title: Date Of Birth education_level: anyOf: - $ref: '#/components/schemas/EducationLevel' - type: 'null' employment_status: anyOf: - $ref: '#/components/schemas/EmploymentStatus' - type: 'null' external_id: anyOf: - type: string - type: 'null' description: >- Your own identifier for this person, if you set one. Unique among the people your workspace owns. Always null on a `platform` person: the shared library is nobody's to label. title: External Id gender: anyOf: - $ref: '#/components/schemas/Gender' - type: 'null' generation_job_id: anyOf: - format: uuid type: string - type: 'null' description: >- The generation job that produced this person, when one did. This is how you collect a job's results: list people filtered by it. title: Generation Job Id household: anyOf: - $ref: '#/components/schemas/Household' - type: 'null' id: format: uuid title: Id type: string income_level: anyOf: - $ref: '#/components/schemas/IncomeLevel' - type: 'null' interests: description: >- IAB taxonomy node ids this person is tagged with. Filterable via the `qualification` rule source, where a parent node also matches everyone tagged at a node beneath it. items: type: string title: Interests type: array locale_type: anyOf: - $ref: '#/components/schemas/LocaleType' - type: 'null' name: description: The person's display name. title: Name type: string occupation: anyOf: - type: string - type: 'null' description: Free-text job title, as written on the person. title: Occupation occupation_code: anyOf: - type: string - type: 'null' description: >- Canonical ESCO/ISCO code beside the free-text `occupation`. Codes are hierarchical, so a `starts_with` filter on a group prefix selects a whole occupational family. title: Occupation Code owner: description: >- `self` for a person your workspace owns; `platform` for one published in the shared ish library. Both are usable in a session; only `self` rows are yours to edit. enum: - self - platform title: Owner type: string type: const: ai default: ai description: >- Always `ai` on this API. ish also models real people who have consented to participate, and they are never readable here or through any credential you can mint. Treat this as an open union and tolerate a value you do not recognize. title: Type type: string updated_at: format: date-time title: Updated At type: string workspace_id: anyOf: - format: uuid type: string - type: 'null' description: >- The owning workspace, present only when `owner` is `self`. A `platform` person belongs to no workspace, so this is null rather than naming one. title: Workspace Id required: - id - name - owner - created_at - updated_at title: PublicPersonResponse type: object FieldError: description: One field-level entry in a ValidationError envelope. properties: allowed_values: description: For enum/literal failures, the accepted values. items: {} title: Allowed Values type: array input: anyOf: - type: string - type: number - type: boolean - type: 'null' description: Offending value (truncated); omitted for containers. title: Input loc: description: Path to the offending field. items: anyOf: - type: string - type: integer title: Location type: array msg: title: Message type: string type: title: Error Type type: string required: - loc - msg - type title: FieldError type: object EducationLevel: enum: - less_than_secondary - secondary - some_post_secondary - vocational_or_associate - bachelor - graduate title: EducationLevel type: string EmploymentStatus: enum: - employed_full_time - employed_part_time - self_employed - unemployed_seeking - student - homemaker - retired - unable_to_work - other title: EmploymentStatus type: string Gender: description: Gender options for people. enum: - male - female - non-binary - prefer_not_to_say title: Gender type: string Household: enum: - single - couple_no_kids - couple_with_kids - single_parent - shared_housing - adult_with_parents - multi_generational title: Household type: string IncomeLevel: enum: - lower - lower_middle - middle - upper_middle - upper - prefer_not_to_say title: IncomeLevel type: string LocaleType: enum: - urban - suburban - small_town - rural title: LocaleType type: string headers: XRequestId: description: >- Per-response correlation id, present on EVERY response (success and error). Error bodies echo it as `request_id`. schema: type: string XRateLimitLimit: description: >- Ceiling for the rate-limit window this request charged. Present on responses made with an API key against a rate-limited operation, including the `429` itself; absent for user access tokens (which carry no per-key budget) and when the rate-limit backend could not be read. schema: type: integer XRateLimitRemaining: description: >- Requests left in that window AFTER this one was counted. Pace off this rather than waiting for a `429`. schema: type: integer XRateLimitReset: description: >- **Seconds from now** until that window resets (a delta, NOT a Unix timestamp). Measured when the response is written. Omitted on the rare occasion the reset instant could not be read, while `limit` and `remaining` are still published. schema: type: integer securitySchemes: bearerAuth: description: >- Workspace API key as a bearer token: `Authorization: Bearer ish_sk_live_...`. Keys are workspace-scoped machine principals minted in Settings > Developers (shown once at mint). Scopes: `sessions:run` (create a session, submit turns, close), `sessions:read` (read the session and its decision trace), `environments:read` and `environments:write` (manage the workspace's registered environments), `tasks:read` and `tasks:write` (manage the workspace's registered tasks), `people:read` and `people:write` (the people the workspace can run a session for), and `usage:read` (the workspace's own consumption, spend limits and rate-limit budgets). A key is minted with `sessions:run`, `sessions:read`, and `tasks:read` by default; every other scope must be requested, `people:read` and `usage:read` included. An ish user access token also works on the same header for personal scripts. scheme: bearer type: http ````