> ## Documentation Index > Fetch the complete documentation index at: https://docs.firedrill.run/llms.txt > Use this file to discover all available pages before exploring further. # Preview and retain an exact simulation plan > Select saved drills from one immutable Tool setup. Omitted repetition uses each saved drill's count. Explicit seeds are exact inputs; repeated seeds remain separate isolated cases. Returns the first paginated case preview. No Tool session or customer agent is started. Reuse the idempotency key and identical request after an interrupted response. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/projects/{projectId}/simulation-plans openapi: 3.1.0 info: title: Firedrill Control API version: 1.0.0 description: >- The control plane for drills, drill runs, and the worlds they run in. Errors always carry the canonical envelope; unsafe operations require an Idempotency-Key; long work returns an operation resource. servers: - url: https://api.firedrill.run security: - controlCredential: [] paths: /v1/projects/{projectId}/simulation-plans: post: summary: Preview and retain an exact simulation plan description: >- Select saved drills from one immutable Tool setup. Omitted repetition uses each saved drill's count. Explicit seeds are exact inputs; repeated seeds remain separate isolated cases. Returns the first paginated case preview. No Tool session or customer agent is started. Reuse the idempotency key and identical request after an interrupted response. operationId: simulations.preview parameters: - name: projectId in: path required: true schema: type: string pattern: ^prj_[0-9a-z]{12,32}$ - name: Idempotency-Key in: header required: true schema: type: string minLength: 8 maxLength: 128 pattern: ^[A-Za-z0-9._:-]+$ requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PreviewSimulationPlanRequest' responses: '200': description: Original preview replay content: application/json: schema: $ref: '#/components/schemas/SimulationPreviewResponse' '201': description: Retained plan and first case page content: application/json: schema: $ref: '#/components/schemas/SimulationPreviewResponse' default: description: Canonical error envelope content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' components: schemas: PreviewSimulationPlanRequest: type: object properties: environmentId: type: string pattern: ^env_[0-9a-z]{12,32}$ buildHash: type: string pattern: ^sha256:[0-9a-f]{64}$ toolSetupId: type: string pattern: ^setup_[0-9a-z]{12,32}$ drillIds: minItems: 1 maxItems: 10000 type: array items: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ seeds: minItems: 1 maxItems: 10000 type: array items: type: string pattern: ^(0|[1-9]\d{0,19})$ repetitions: type: integer minimum: 0 exclusiveMinimum: true maximum: 10000 concurrency: default: 1 type: integer minimum: 0 exclusiveMinimum: true maximum: 64 retries: default: 0 type: integer minimum: 0 maximum: 10 browserInvocations: minItems: 1 maxItems: 64 type: array items: type: object properties: targetId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ testId: type: string pattern: ^btest_[a-z0-9]{12,64}$ expectedTestVersion: type: integer minimum: -9007199254740991 maximum: 9007199254740991 role: oneOf: - type: object properties: kind: type: string enum: - tool_ui packageId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ instanceId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ required: - kind - packageId additionalProperties: false - type: object properties: kind: type: string enum: - agent_ui origin: type: string maxLength: 2048 format: uri binding: type: string enum: - per_case required: - kind - origin - binding additionalProperties: false mode: default: replay type: string enum: - replay - agent timeoutMs: default: 120000 type: integer minimum: 1000 maximum: 300000 maxActions: default: 100 type: integer minimum: 1 maximum: 200 capture: type: object properties: screenshot: default: 'off' type: string enum: - 'off' - always - retain-on-failure video: default: 'off' type: string enum: - 'off' - always - retain-on-failure trace: default: 'off' type: string enum: - 'off' - always - retain-on-failure required: - screenshot - video - trace additionalProperties: false captureConsent: type: string enum: - include-sensitive-content captureMask: maxItems: 32 type: array items: anyOf: - type: object properties: by: type: string enum: - role role: type: string enum: - button - link - textbox - checkbox - radio - combobox - option - heading - alert - status - tab - menuitem name: type: string minLength: 1 maxLength: 4000 required: - by - role - name additionalProperties: false - type: object properties: by: type: string enum: - label value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false - type: object properties: by: type: string enum: - text value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false - type: object properties: by: type: string enum: - testId value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false - type: object properties: by: type: string enum: - css value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false required: - targetId - testId - expectedTestVersion - role - mode - timeoutMs - maxActions additionalProperties: false required: - drillIds - concurrency - retries additionalProperties: false SimulationPreviewResponse: type: object properties: plan: type: object properties: schemaVersion: type: number enum: - 1 planId: type: string pattern: ^simplan_[0-9a-z]{12,32}$ organizationId: type: string pattern: ^org_[0-9a-z]{12,32}$ projectId: type: string pattern: ^prj_[0-9a-z]{12,32}$ environmentId: type: string pattern: ^env_[0-9a-z]{12,32}$ toolSetupId: type: string pattern: ^setup_[0-9a-z]{12,32}$ buildHash: type: string pattern: ^sha256:[0-9a-f]{64}$ digest: type: string pattern: ^sha256:[0-9a-f]{64}$ concurrency: type: integer minimum: 0 exclusiveMinimum: true maximum: 64 retries: type: integer minimum: 0 maximum: 10 logicalCases: type: integer minimum: 0 exclusiveMinimum: true maximum: 10000 maxAttempts: type: integer minimum: 0 exclusiveMinimum: true maximum: 110000 browserInvocations: minItems: 1 maxItems: 64 type: array items: type: object properties: targetId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ testId: type: string pattern: ^btest_[a-z0-9]{12,64}$ expectedTestVersion: type: integer minimum: -9007199254740991 maximum: 9007199254740991 role: oneOf: - type: object properties: kind: type: string enum: - tool_ui packageId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ instanceId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ required: - kind - packageId additionalProperties: false - type: object properties: kind: type: string enum: - agent_ui origin: type: string maxLength: 2048 format: uri binding: type: string enum: - per_case required: - kind - origin - binding additionalProperties: false mode: default: replay type: string enum: - replay - agent timeoutMs: default: 120000 type: integer minimum: 1000 maximum: 300000 maxActions: default: 100 type: integer minimum: 1 maximum: 200 capture: type: object properties: screenshot: default: 'off' type: string enum: - 'off' - always - retain-on-failure video: default: 'off' type: string enum: - 'off' - always - retain-on-failure trace: default: 'off' type: string enum: - 'off' - always - retain-on-failure required: - screenshot - video - trace additionalProperties: false captureConsent: type: string enum: - include-sensitive-content captureMask: maxItems: 32 type: array items: anyOf: - type: object properties: by: type: string enum: - role role: type: string enum: - button - link - textbox - checkbox - radio - combobox - option - heading - alert - status - tab - menuitem name: type: string minLength: 1 maxLength: 4000 required: - by - role - name additionalProperties: false - type: object properties: by: type: string enum: - label value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false - type: object properties: by: type: string enum: - text value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false - type: object properties: by: type: string enum: - testId value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false - type: object properties: by: type: string enum: - css value: type: string minLength: 1 maxLength: 4000 required: - by - value additionalProperties: false definitionDigest: type: string pattern: ^sha256:[0-9a-f]{64}$ required: - targetId - testId - expectedTestVersion - role - mode - timeoutMs - maxActions - definitionDigest additionalProperties: false createdBy: type: string minLength: 1 maxLength: 255 createdAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - schemaVersion - planId - organizationId - projectId - buildHash - digest - concurrency - retries - logicalCases - maxAttempts - createdBy - createdAtMs additionalProperties: false cases: type: object properties: planId: type: string pattern: ^simplan_[0-9a-z]{12,32}$ planDigest: type: string pattern: ^sha256:[0-9a-f]{64}$ items: maxItems: 100 type: array items: type: object properties: ordinal: type: integer minimum: 0 exclusiveMinimum: true maximum: 10000 drillId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ targetId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ classification: type: string enum: - contract - safety - quality trial: type: integer minimum: 0 exclusiveMinimum: true maximum: 10000 trialCount: type: integer minimum: 0 exclusiveMinimum: true maximum: 10000 seed: type: string pattern: ^(0|[1-9]\d{0,19})$ timeoutMs: type: integer minimum: 1 maximum: 86400000 required: - ordinal - drillId - targetId - classification - trial - trialCount - seed - timeoutMs additionalProperties: false total: type: integer minimum: 0 exclusiveMinimum: true maximum: 10000 nextAfter: type: integer minimum: 0 exclusiveMinimum: true maximum: 10000 required: - planId - planDigest - items - total additionalProperties: false replayed: type: boolean required: - plan - cases - replayed additionalProperties: false ErrorEnvelope: type: object properties: code: type: string pattern: ^(control|world)\.[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$ message: type: string minLength: 1 correlationId: type: string minLength: 1 retryable: type: boolean retryAfterMs: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 operationId: type: string source: type: string enum: - platform - simulated_provider issues: type: array items: type: object properties: path: type: string code: type: string message: type: string required: - path - code - message additionalProperties: false details: type: object propertyNames: type: string additionalProperties: {} evidence: type: object properties: sessionId: type: string runId: type: string journalSeq: type: integer minimum: 0 maximum: 9007199254740991 buildHash: type: string additionalProperties: false required: - code - message - correlationId - retryable - source additionalProperties: true securitySchemes: controlCredential: type: http scheme: bearer description: Opaque control credential ````