> ## 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. # Keep the exact pre-start runner slot available > Requires the current work version and original mutation key. Returns the original immutable receipt separately from current work state. Acceptance is not callback permission: only a fresh common interaction start permits invocation. After any callback has started, use existing run cancellation rather than withdrawing or replaying execution. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/projects/{projectId}/simulations/{batchId}/work/{workId}/refresh 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}/simulations/{batchId}/work/{workId}/refresh: post: summary: Keep the exact pre-start runner slot available description: >- Requires the current work version and original mutation key. Returns the original immutable receipt separately from current work state. Acceptance is not callback permission: only a fresh common interaction start permits invocation. After any callback has started, use existing run cancellation rather than withdrawing or replaying execution. operationId: simulations.refreshWork parameters: - name: projectId in: path required: true schema: type: string pattern: ^prj_[0-9a-z]{12,32}$ - name: batchId in: path required: true schema: type: string pattern: ^cisuite_[0-9a-z]{12,32}$ - name: workId in: path required: true schema: type: string pattern: ^simwork_[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/SimulationRefreshWorkRequest' responses: '200': description: Mutation receipt and current state content: application/json: schema: $ref: '#/components/schemas/SimulationWorkMutationResponse' default: description: Canonical error envelope content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' components: schemas: SimulationRefreshWorkRequest: type: object properties: runnerId: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$ expectedVersion: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - runnerId - expectedVersion additionalProperties: false SimulationWorkMutationResponse: type: object properties: receipt: type: object properties: organizationId: type: string pattern: ^org_[0-9a-z]{12,32}$ projectId: type: string pattern: ^prj_[0-9a-z]{12,32}$ batchId: type: string pattern: ^cisuite_[0-9a-z]{12,32}$ schemaVersion: type: number enum: - 1 workId: type: string pattern: ^simwork_[0-9a-z]{12,32}$ runnerId: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$ action: type: string enum: - request - refresh - accept - withdraw version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 recordedAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 preStartExpiresAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 acceptedSession: type: object properties: sessionId: type: string pattern: ^ses_[0-9a-z]{12,32}$ leaseGeneration: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 required: - sessionId - leaseGeneration additionalProperties: false required: - organizationId - projectId - batchId - schemaVersion - workId - runnerId - action - version - recordedAtMs - preStartExpiresAtMs additionalProperties: false work: type: object properties: organizationId: type: string pattern: ^org_[0-9a-z]{12,32}$ projectId: type: string pattern: ^prj_[0-9a-z]{12,32}$ batchId: type: string pattern: ^cisuite_[0-9a-z]{12,32}$ schemaVersion: type: number enum: - 1 workId: type: string pattern: ^simwork_[0-9a-z]{12,32}$ runnerId: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$ version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 phase: type: string enum: - waiting - preparing - ready - accepted - running - finished - expired - withdrawn preStartExpiresAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 capacityOccupied: type: boolean waiting: type: object properties: code: type: string enum: - fair_queue - runner_unavailable - unsupported_target - runner_capacity - tool_capacity - organization_concurrency - batch_concurrency - usage_allowance - setup_unavailable - preparing_tools - cleanup_pending - insufficient_session_lifetime retryAfterMs: type: integer minimum: 0 exclusiveMinimum: true maximum: 300000 action: type: string enum: - wait - start_runner - free_runner_slot - review_usage - review_setup required: - code additionalProperties: false case: type: object properties: caseId: type: string pattern: ^cicase_[0-9a-z]{12,32}$ targetId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ buildHash: type: string pattern: ^sha256:[0-9a-f]{64}$ drillId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ seed: type: string pattern: ^(0|[1-9]\d{0,19})$ trial: type: integer minimum: 0 exclusiveMinimum: true maximum: 10000 attempt: type: integer minimum: 0 exclusiveMinimum: true maximum: 11 required: - caseId - targetId - buildHash - drillId - seed - trial - attempt additionalProperties: false session: type: object properties: sessionId: type: string pattern: ^ses_[0-9a-z]{12,32}$ leaseGeneration: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 required: - sessionId - leaseGeneration additionalProperties: false hostedRunId: type: string pattern: ^hrun_[0-9a-z]{12,32}$ required: - organizationId - projectId - batchId - schemaVersion - workId - runnerId - version - phase - preStartExpiresAtMs - capacityOccupied additionalProperties: false replayed: type: boolean required: - receipt - work - 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 ````