> ## 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. # Create Session > Open a session: one of your people, working toward one task, inside your environment. The TASK is required and is exactly one of two shapes: `{"instructions": "..."}` describes the intent inline, or `{"id": "..."}` binds a task you registered. A bound task's instructions are frozen onto the session, so later edits to the registry never change a run that already happened. An id that does not resolve is a 404; one that resolves but is retired is a 409. The ENVIRONMENT is also exactly one of two shapes: `environment_id` names one you registered, or `environment` describes an ad-hoc one inline. A registered environment's name, kind and configuration are snapshot onto the session for the same reason. Send an `Idempotency-Key` header to make retries safe: the same key with the same body replays the original session as a 200, and the same key with a different body is a 409. ## OpenAPI ````yaml /api/openapi.public.json post /api/v1/workspaces/{workspace_id}/sessions 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}/sessions: post: tags: - sessions summary: Create Session description: >- Open a session: one of your people, working toward one task, inside your environment. The TASK is required and is exactly one of two shapes: `{"instructions": "..."}` describes the intent inline, or `{"id": "..."}` binds a task you registered. A bound task's instructions are frozen onto the session, so later edits to the registry never change a run that already happened. An id that does not resolve is a 404; one that resolves but is retired is a 409. The ENVIRONMENT is also exactly one of two shapes: `environment_id` names one you registered, or `environment` describes an ad-hoc one inline. A registered environment's name, kind and configuration are snapshot onto the session for the same reason. Send an `Idempotency-Key` header to make retries safe: the same key with the same body replays the original session as a 200, and the same key with a different body is a 409. operationId: createSession parameters: - in: path name: workspace_id required: true schema: format: uuid title: Workspace Id type: string - in: header name: Idempotency-Key required: false schema: anyOf: - type: string - type: 'null' title: Idempotency-Key requestBody: content: application/json: examples: default: summary: Open a session against a registered environment value: environment_id: 3c2a1f80-7e64-4b19-8d55-11aa22bb33cc max_turns: 20 pacing: pause_on_decide person_id: 9f1c7b52-0d3a-4a1e-9c4f-2b8e5a6d1234 reasoning_effort: low task: instructions: Find the refund policy and start a return. schema: $ref: '#/components/schemas/CreateSessionRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SessionResponse' description: >- Idempotent replay: an existing session was returned because the Idempotency-Key and request body matched a prior create. 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' '201': content: application/json: schema: $ref: '#/components/schemas/SessionResponse' 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: >- Either the API key lacks the `sessions:run` scope (`detail.error_kind = 'insufficient_scope'`, with `detail.required_scope`), or the person is out of scope for this lane (`person_out_of_scope`): a session can only be opened for a person the workspace owns or one published in the platform library. 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, person, environment, or task (`workspace_id`, `person_id`, `environment_id`, `task.id`) was not found, or is not reachable with this credential. `detail.error_kind` is `workspace_not_found`, `person_not_found`, `environment_not_found` or `task_not_found`. A `person_id` that names a real person who participates in ish under consent also answers `person_not_found`: this lane runs simulated people only, and the answer is deliberately identical to the one a nonexistent id earns. 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' '409': content: application/json: schema: $ref: '#/components/schemas/Error' description: >- The create was refused and no session was opened BY THIS REQUEST. `detail.error_kind` says which: `idempotency_conflict` (the Idempotency-Key was reused with a different request body; a key maps to one create request), `environment_archived` (the environment resolves but is retired and cannot accept new sessions; register a new environment, or pass an inline environment descriptor), or `task_archived` (the task resolves but is retired; register a new task, or pass the instructions inline). An environment or task that does not exist, or belongs to another tenant, is a 404 instead. 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: >- Either the API key's request rate limit is exceeded (`detail.error_kind = 'rate_limited'`) or its daily session-create quota is used up (`session_quota_exceeded`). Both are transient and carry `Retry-After`, but they reset on different clocks: the first within the minute, the second on a day boundary. Existing sessions are unaffected by either. 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' '500': content: application/json: schema: $ref: '#/components/schemas/Error' description: >- An unexpected server-side failure. `detail.error_kind` is `environment_unresolved` or `session_actor_missing`. Not a state to handle: quote `request_id` and the kind in a bug report. 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: CreateSessionRequest: additionalProperties: false properties: decision_mode: $ref: '#/components/schemas/DecisionMode' default: intent environment: anyOf: - $ref: '#/components/schemas/EnvironmentDescriptor' - type: 'null' description: >- An ad-hoc environment described inline. Mutually exclusive with `environment_id`; supply exactly one. environment_id: anyOf: - format: uuid type: string - type: 'null' description: >- A registered environment in this workspace. Mutually exclusive with `environment`; supply exactly one. title: Environment Id environment_version: anyOf: - maxLength: 120 minLength: 1 type: string - type: 'null' description: >- Pin this session to a declared version of the registered environment, by label (case-insensitive; the canonical label is recorded). Requires `environment_id`. Omit to use the environment's default version, or to run unversioned when it has none. An unknown label is a 404, never a new bucket. title: Environment Version max_turns: default: 50 maximum: 200 minimum: 1 title: Max Turns type: integer observation_retention: anyOf: - $ref: '#/components/schemas/ObservationRetention' - type: 'null' description: >- How long this session's observation frames are retained: `none` (discard after the turn), `30d`, `90d`, or `indefinite`. Omit to inherit the registered environment's setting; an inline environment descriptor defaults to `none`. Resolved once at open and fixed for the session's lifetime. Open union: new values may be added over time; clients must tolerate unknown values rather than failing on them. pacing: $ref: '#/components/schemas/PacingContract' person_id: format: uuid title: Person Id type: string reasoning_effort: default: low enum: - low - medium - high title: Reasoning Effort type: string resolver_guidance: anyOf: - maxLength: 8000 type: string - type: 'null' title: Resolver Guidance task: anyOf: - $ref: '#/components/schemas/TaskRef' - $ref: '#/components/schemas/TaskDescriptor' description: >- The session's intent: `{instructions}` describes it inline, `{id}` binds a registered task (its instructions are frozen onto the session). Supply exactly one shape. title: Task required: - person_id - task - pacing title: CreateSessionRequest type: object SessionResponse: allOf: - $ref: '#/components/schemas/SessionBase' - properties: observation_retention: description: >- Retention window resolved at open: `none`, `30d`, `90d`, or `indefinite`. Open union: new values may be added over time; clients must tolerate unknown values rather than failing on them. title: Observation Retention type: string pacing: $ref: '#/components/schemas/PacingContract' person_id: anyOf: - format: uuid type: string - type: 'null' title: Person Id person_snapshot: $ref: '#/components/schemas/PersonSnapshot' reasoning_effort: description: >- Deliberation budget the session was opened with: `low`, `medium` or `high`. Open union: new values may be added over time; clients must tolerate unknown values rather than failing on them. title: Reasoning Effort type: string workspace_id: format: uuid title: Workspace Id type: string required: - person_id - workspace_id - pacing - observation_retention - reasoning_effort - person_snapshot type: object description: >- The full session, without its decision trace. What create and close return: a caller that opened a session holds the same object a read would give it, so nothing has to be fetched twice to learn what was actually frozen. The TRACE is deliberately absent: turns are a paged subresource of the detail read, and a create has none yet. title: SessionResponse 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 DecisionMode: enum: - direct - intent title: DecisionMode type: string EnvironmentDescriptor: description: >- An ad-hoc environment, described inline on the session that uses it. Also the shape of the FROZEN SNAPSHOT a session carries after it was opened against a REGISTERED environment (`environment_id`), so `kind` means the same thing on both paths and on the environments surface: one noun for one concept, rather than a wire that says `platform` where the registry says `kind`. properties: kind: description: >- The kind of surface (e.g. `web`, `device`, `world`). Open union: new values may be added over time; clients must tolerate unknown values rather than failing on them. maxLength: 40 minLength: 1 title: Kind type: string name: maxLength: 120 minLength: 1 title: Name type: string required: - name - kind title: EnvironmentDescriptor type: object ObservationRetention: description: >- How long a session's observation frames are kept: `none` (discarded after the turn), `30d`, `90d`, or `indefinite`. One field rather than a flag beside a window, so the incoherent pair (off, 90 days) cannot be expressed. Resolved once when the session opens, from the session's own value or the registered environment's default, and fixed for that session's lifetime: editing the environment later never changes what an open session promised. Open union: new windows may be added over time; clients must tolerate unknown values rather than failing on them. enum: - none - 30d - 90d - indefinite title: ObservationRetention type: string PacingContract: enum: - pause_on_decide - frame_on_demand - free_running title: PacingContract type: string TaskRef: additionalProperties: false description: A registered task in this workspace, bound by id. properties: id: description: >- A registered task. Its instructions are frozen onto the session at create; later edits to the registry row never touch this session. format: uuid title: Id type: string required: - id title: TaskRef type: object TaskDescriptor: additionalProperties: false description: >- A task described inline on the session that uses it. Instructions only, by design: on this lane your code executes the actions, so verification steps in the create body would hand the answer key to the process being measured. Register a task to attach steps. properties: instructions: description: >- What the person is trying to do, in their own terms. Rendered into their prompt as the situation paragraph. maxLength: 2000 minLength: 1 title: Instructions type: string required: - instructions title: TaskDescriptor type: object SessionBase: description: >- Everything every session read carries, wherever the session is served. The one place the shared fields are declared: the list row, the create/close body and the detail read all extend this, so an SDK generator sees ONE Session family instead of three types that happen to overlap. properties: accrued_credits: description: This session's spend in credits (0 if it had no billable turns). title: Accrued Credits type: integer created_at: format: date-time title: Created At type: string created_by_api_key_id: anyOf: - format: uuid type: string - type: 'null' title: Created By Api Key Id decision_mode: $ref: '#/components/schemas/DecisionMode' ended_at: anyOf: - format: date-time type: string - type: 'null' description: >- When the session left `open` (UTC), stamped on the first terminal transition and never moved. Null while the session is open. This is the timestamp `sessions_ended` usage buckets on. title: Ended At ended_reason: anyOf: - type: string - type: 'null' description: >- Why the session ended, when that is finer than `status`: `credits_exhausted` or `plan_allowance_exhausted` (both end the session as `balance_exhausted`), or `spend_cap_reached`. Null for an ordinary ending. Open union: new values may be added over time; clients must tolerate unknown values rather than failing on them. title: Ended Reason environment: $ref: '#/components/schemas/EnvironmentDescriptor' description: The environment as frozen at create (name + kind snapshot). environment_id: anyOf: - format: uuid type: string - type: 'null' title: Environment Id environment_revision: anyOf: - type: integer - type: 'null' title: Environment Revision environment_version_id: anyOf: - format: uuid type: string - type: 'null' title: Environment Version Id environment_version_label: anyOf: - type: string - type: 'null' title: Environment Version Label id: format: uuid title: Id type: string max_turns: title: Max Turns type: integer status: $ref: '#/components/schemas/SessionStatus' description: >- Session status. Open union: new values may be added over time; clients must tolerate unknown values rather than failing on them. task: $ref: '#/components/schemas/TaskSnapshot' description: >- The session's intent, frozen when it was created. A later edit to a registered task never changes it. turn_count: title: Turn Count type: integer updated_at: format: date-time title: Updated At type: string required: - id - status - task - environment - environment_id - environment_revision - environment_version_id - environment_version_label - decision_mode - turn_count - max_turns - created_by_api_key_id - accrued_credits - ended_reason - created_at - updated_at - ended_at title: SessionBase type: object PersonSnapshot: additionalProperties: true description: >- The person as they were when the session was created, frozen onto the session. This, not the live person, is what the session was run against: it stays readable and unchanged after the person is edited or deleted, which is what makes an old trace still mean something. `id` is the person's id at create time. Additional keys may be present and more may be added over time; treat anything not listed here as unspecified rather than failing on it. properties: avatar_url: anyOf: - type: string - type: 'null' default: null title: Avatar Url bio: anyOf: - type: string - type: 'null' default: null title: Bio city: anyOf: - type: string - type: 'null' default: null title: City country: anyOf: - type: string - type: 'null' default: null title: Country date_of_birth: anyOf: - format: date type: string - type: 'null' default: null title: Date Of Birth education_level: anyOf: - $ref: '#/components/schemas/EducationLevel' - type: 'null' default: null employment_status: anyOf: - $ref: '#/components/schemas/EmploymentStatus' - type: 'null' default: null gender: anyOf: - $ref: '#/components/schemas/Gender' - type: 'null' default: null household: anyOf: - $ref: '#/components/schemas/Household' - type: 'null' default: null id: format: uuid title: Id type: string income_level: anyOf: - $ref: '#/components/schemas/IncomeLevel' - type: 'null' default: null languages: anyOf: - items: type: string type: array - type: 'null' default: null title: Languages locale_type: anyOf: - $ref: '#/components/schemas/LocaleType' - type: 'null' default: null name: title: Name type: string occupation: anyOf: - type: string - type: 'null' default: null title: Occupation snapshot_version: default: '2' enum: - '1' - '2' title: Snapshot Version type: string snapshotted_at: format: date-time title: Snapshotted At type: string timezone: anyOf: - type: string - type: 'null' default: null title: Timezone type: $ref: '#/components/schemas/IterationType' required: - id - name - type - snapshotted_at title: PersonSnapshot 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 SessionStatus: enum: - open - completed - gave_up - closed - max_turns - spend_cap_reached - balance_exhausted title: SessionStatus type: string TaskSnapshot: description: |- The session's intent as frozen at create. `instructions` is always present (the snapshot). `id`/`name`/ `revision` are null for a session opened with an inline descriptor; `name` reads the LIVE registry row (display only) while `instructions` and `revision` stay frozen, so a rename shows through but content never drifts. properties: id: anyOf: - format: uuid type: string - type: 'null' title: Id instructions: title: Instructions type: string name: anyOf: - type: string - type: 'null' title: Name revision: anyOf: - type: integer - type: 'null' description: >- The registry row's revision at bind time. Two runs of one task are comparable within a revision of its content. title: Revision required: - id - name - revision - instructions title: TaskSnapshot 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 IterationType: description: Iteration execution type. enum: - ai - human title: IterationType 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 ````