---
title: "Set a tool fixture"
method: POST
path: "/v1/simulation/tool-fixture"
tags: ["Simulation"]
---

# Set a tool fixture

`POST /v1/simulation/tool-fixture`

## Request

- Base URL: `https://api.roark.ai`
- URL: `https://api.roark.ai/v1/simulation/tool-fixture`
- Auth: HTTP bearer

Create-or-replace by scope: one fixture per tool project-wide, plus one per (tool, flow variant). Setting the same scope twice replaces the response, so CI can apply fixtures idempotently. During Roark test calls the tool guard answers with the fixture verbatim instead of generating a response; real callers are never affected.

## Request body

- UpsertSimulationToolFixtureRequest
  - `toolName` string, required: The tool this fixture answers for.
  - `response` unknown
  - `customerFlowVariantId` string, uuid: Pin the fixture to one flow variant (scenario). Omit for a project-wide fixture. A variant-pinned fixture beats the project-wide one.
  - `description` string: Why this fixture exists.
  - `enabled` boolean: Defaults to true.

## Response `200`

The fixture as stored.

- object
  - `data` SimulationToolFixture, required: A deterministic tool response for Roark test calls: where the scenario-aware model makes mocked tools plausible, a fixture makes one exact, so a simulation can force the branch under test. Never applies to real callers.
    - `id` string, uuid, required
    - `toolName` string, required
    - `customerFlowVariantId` string, uuid, nullable, required: The flow variant this fixture is pinned to. Null = project-wide.
    - `response` unknown
    - `description` string, nullable, required: Why this fixture exists.
    - `enabled` boolean, required
    - `createdAt` string, required: ISO 8601.
    - `updatedAt` string, required: ISO 8601.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: The referenced flow variant does not exist in this project.
- `429`: Too Many Requests
- `500`: Internal Server Error

## Changes

> 187 revisions in range; 1 not diffed.

- **2026-09-23** `1ecd4d7c5fe7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/roarkhq/apis/roark-analytics-api/changes/v1/simulation/tool-fixture/post.md)

---

[API](https://skmtc.dev/roarkhq/apis/roark-analytics-api.md) - [All operations](https://skmtc.dev/roarkhq/apis/roark-analytics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/roarkhq/apis/roark-analytics-api/revisions/1a91a5c90e44?raw)