> ## Documentation Index > Fetch the complete documentation index at: https://docs.guidinghand.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update a test case > Send only the fields to change. Runs already made keep the copy they took. Needs the admin role or an API key. ## OpenAPI ````yaml /api-reference/openapi.json patch /v1/test_cases/{test_case_id} openapi: 3.1.0 info: title: GuidingHand API version: 1.0.0 description: >- Create sessions (an invite link with a code for the person at the computer), run tasks on their computer with one of your agents, follow them, answer their questions and approvals, and fetch history and recordings. Test your agents with evals: test cases on fresh machines, run in test sets, scored by a check script or a rubric. Agents are versioned (save a draft, publish it), have tools (their own file system, and your HTTP endpoints), and every change is in the org’s audit log. servers: - url: https://guidinghand.ai description: Production - url: https://dev.guidinghand.ai description: Development (Stripe test mode) security: - bearerAuth: [] tags: - name: Agents - name: Agent files - name: Agent tools - name: Sessions - name: Tasks - name: Webhooks - name: Audit log - name: Test cases - name: Test sets - name: Test runs - name: Start states - name: Runners paths: /v1/test_cases/{test_case_id}: parameters: - name: test_case_id in: path required: true description: The test case’s id (`tc_…`) or its `key` (e.g. `DSP-01`). schema: type: string patch: tags: - Test cases summary: Update a test case description: >- Send only the fields to change. Runs already made keep the copy they took. Needs the admin role or an API key. operationId: updateTestCase requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TestCaseUpdate' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/TestCase' '400': $ref: '#/components/responses/E400' '401': $ref: '#/components/responses/E401' '403': $ref: '#/components/responses/E403' '404': $ref: '#/components/responses/E404' '409': $ref: '#/components/responses/E409' components: schemas: TestCaseUpdate: type: object description: Only the fields you send change. properties: key: type: - string - 'null' pattern: ^(?!tc_)[A-Za-z0-9._-]{1,64}$ example: DSP-01 description: >- Your own id for the case, unique in the org: 1 to 64 of `A-Za-z0-9._-`, not starting with `tc_`. Every `{test_case_id}` in the API also takes it. name: type: string minLength: 1 maxLength: 200 example: Apps switched to dark mode prompt: type: string minLength: 1 maxLength: 8000 example: All my windows suddenly went black. How do I get the white back? description: 'What the customer says to the agent: the task’s prompt.' start_state: type: string example: win10-22h2 description: >- The start state (`ss_…`) or image (e.g. `win10-22h2`) each try’s machine is made from. setup_script: type: - string - 'null' maxLength: 100000 description: >- Runs at the start of every try, elevated, as the signed-in user: it breaks the machine the way the case needs. success: type: object properties: check_script: type: - string - 'null' maxLength: 100000 description: >- Runs on the machine (elevated, as the signed-in user) and prints `True` once the problem is fixed. It must print `False` before the task, or the attempt is an `error`. The agent’s final answer is in the `GH_AGENT_ANSWER` environment variable, and `GH_CHECK_PHASE` is `before` or `after` the task. rubric: type: - string - 'null' maxLength: 8000 description: >- What a fix looks like, in plain language. A model judges it from the recorded conversation and the first and last screens. description: >- How to tell the problem is fixed: a `check_script`, a `rubric`, or both (an attempt passes only when each one it has passes). At least one. customer: oneOf: - $ref: '#/components/schemas/Customer' - type: 'null' description: >- The simulated customer. Null: the test set’s `customer`, else a built-in default. operator: type: object properties: approvals: type: string enum: - approve - deny description: How the agent’s approval requests are decided during the test. limits: type: object properties: minutes: type: integer minimum: 1 maximum: 60 default: 10 description: The task is stopped after this many minutes (1 to 60). steps: type: - integer - 'null' minimum: 1 maximum: 500 description: >- Model turns (1 to 500). Null: the agent’s own `guardrails.max_steps`. runs_on: type: string example: vm description: >- A runner label the case needs: `vm` for any virtual machine, or one of your runners’ labels (e.g. `lenovo`). category: type: - string - 'null' example: Display & graphics tags: type: array items: type: string maxLength: 64 maxItems: 50 example: - uac metadata: $ref: '#/components/schemas/Metadata' TestCase: type: object description: A problem on a machine, and how to tell it’s fixed. properties: object: const: test_case test_case_id: type: string example: tc_8Kq2mZ0aLp4x key: type: - string - 'null' pattern: ^(?!tc_)[A-Za-z0-9._-]{1,64}$ example: DSP-01 description: >- Your own id for the case, unique in the org: 1 to 64 of `A-Za-z0-9._-`, not starting with `tc_`. Every `{test_case_id}` in the API also takes it. name: type: string minLength: 1 maxLength: 200 example: Apps switched to dark mode prompt: type: string minLength: 1 maxLength: 8000 example: All my windows suddenly went black. How do I get the white back? description: 'What the customer says to the agent: the task’s prompt.' start_state: type: string example: win10-22h2 description: >- The start state (`ss_…`) or image (e.g. `win10-22h2`) each try’s machine is made from. setup_script: type: - string - 'null' maxLength: 100000 description: >- Runs at the start of every try, elevated, as the signed-in user: it breaks the machine the way the case needs. success: type: object properties: check_script: type: - string - 'null' maxLength: 100000 description: >- Runs on the machine (elevated, as the signed-in user) and prints `True` once the problem is fixed. It must print `False` before the task, or the attempt is an `error`. The agent’s final answer is in the `GH_AGENT_ANSWER` environment variable, and `GH_CHECK_PHASE` is `before` or `after` the task. rubric: type: - string - 'null' maxLength: 8000 description: >- What a fix looks like, in plain language. A model judges it from the recorded conversation and the first and last screens. description: >- How to tell the problem is fixed. An attempt passes only when each one it has passes. customer: oneOf: - $ref: '#/components/schemas/Customer' - type: 'null' description: >- The simulated customer. Null: the test set’s `customer`, else a built-in default. operator: type: object properties: approvals: type: string enum: - approve - deny description: How the agent’s approval requests are decided during the test. limits: type: object properties: minutes: type: integer minimum: 1 maximum: 60 default: 10 description: The task is stopped after this many minutes (1 to 60). steps: type: - integer - 'null' minimum: 1 maximum: 500 description: >- Model turns (1 to 500). Null: the agent’s own `guardrails.max_steps`. runs_on: type: string example: vm description: >- A runner label the case needs: `vm` for any virtual machine, or one of your runners’ labels (e.g. `lenovo`). category: type: - string - 'null' example: Display & graphics tags: type: array items: type: string maxLength: 64 maxItems: 50 example: - uac metadata: $ref: '#/components/schemas/Metadata' created_at: type: string format: date-time updated_at: type: string format: date-time Customer: type: object description: >- The simulated customer who answers the agent during a test: a model with this persona, these facts and the machine’s screen. It never sees the expected fix or the check. properties: persona: type: string example: Retired teacher. Not technical. Short, polite answers. description: Who they are and how they answer. facts: type: object maxProperties: 50 additionalProperties: oneOf: - type: string - type: object required: - secret properties: secret: type: string description: >- A secret: the simulated customer’s model only sees its name, and can type it into the focused field. description: >- What the customer knows, by name (up to 50). A `{ "secret": … }` value is never shown to the model: the customer can only type it into the field that has focus. example: Wi-Fi network: HomeNet Wi-Fi password: secret: blue-kite-42 clicks_admin_prompts: type: boolean description: >- When the agent asks, the customer clicks Yes on an admin (UAC) prompt. does_steps: type: boolean description: >- The customer does steps themselves when the agent asks. When false, they ask the agent to do it. Metadata: type: object additionalProperties: type: string maxLength: 500 maxProperties: 50 description: >- Your own ids and labels (e.g. a ticket or customer id), returned as given. example: customer_id: cus_42 Error: type: object required: - error properties: error: type: object required: - type - message properties: type: type: string enum: - invalid_request - authentication - payment_required - permission - not_found - conflict - rate_limit - server_error message: type: string code: type: string description: >- Why it was refused, when there’s more to say than the status. Starting a task: `insufficient_balance`, `auto_topup_limit_reached` or `card_needs_attention` (402: the balance can’t cover a minute; add funds, raise the auto top-up limit, or update the card), `concurrency_limit` (429), `model_unavailable` (503: the agent’s `model` can’t run on this server; choose another). On `/respond`: `already_answered` (someone answered or decided first: see `answered_by`) or `not_pending` (that question or approval isn’t open any more). The GuidingHand app hears two more, which the API never returns: `customer_answers_off` and `customer_approvals_off` (the agent keeps its questions or approvals for your team). Deleting a start state that test cases use: `in_use` (409, with `test_case_ids`). answered_by: type: string enum: - customer - operator - timeout description: >- With `already_answered`: who answered or decided first (`customer`: the person at the computer; `timeout`: nobody decided an approval within the agent’s `approval_timeout_minutes`, so it was denied). test_case_ids: type: array items: type: string description: 'With `in_use`: the test cases that use the start state.' responses: E400: description: The request is invalid. content: application/json: schema: $ref: '#/components/schemas/Error' E401: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' E403: description: Your role can’t do this. content: application/json: schema: $ref: '#/components/schemas/Error' E404: description: Not found in this org. content: application/json: schema: $ref: '#/components/schemas/Error' E409: description: >- Conflicts with the current state (e.g. no computer connected, a task already running, nothing pending, no draft to publish, an agent’s file limits). content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer description: An org API key (`gh_live_…`) from Settings → API keys in the console. ````