> ## 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. # Offer one ready runner slot > Records one free callback slot and its supported targets. No customer code, Tool allocation or timed run starts merely because this request succeeds. Keep the original key if the response is lost. A terminal batch returns its actual result without inventing a work receipt. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/projects/{projectId}/simulations/{batchId}/work 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: post: summary: Offer one ready runner slot description: >- Records one free callback slot and its supported targets. No customer code, Tool allocation or timed run starts merely because this request succeeds. Keep the original key if the response is lost. A terminal batch returns its actual result without inventing a work receipt. operationId: simulations.requestWork 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: 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/SimulationRequestWorkRequest' responses: '200': description: Replayed work or terminal batch content: application/json: schema: $ref: '#/components/schemas/SimulationRequestWorkResponse' '202': description: Original work receipt and current state content: application/json: schema: $ref: '#/components/schemas/SimulationRequestWorkResponse' default: description: Canonical error envelope content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' components: schemas: SimulationRequestWorkRequest: type: object properties: runnerId: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$ supportedTargetIds: minItems: 1 maxItems: 10000 type: array items: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ capacity: type: integer minimum: 0 exclusiveMinimum: true maximum: 64 required: - runnerId - supportedTargetIds - capacity additionalProperties: false SimulationRequestWorkResponse: anyOf: - 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 - type: object properties: status: type: string enum: - batch_terminal batch: type: object properties: schemaVersion: type: number enum: - 1 batchId: type: string pattern: ^cisuite_[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}$ planId: type: string pattern: ^simplan_[0-9a-z]{12,32}$ planDigest: type: string pattern: ^sha256:[0-9a-f]{64}$ buildHash: type: string pattern: ^sha256:[0-9a-f]{64}$ state: type: string enum: - preparing - running - cancelling - completed - failed - cancelled counts: type: object properties: logicalCases: type: integer minimum: -9007199254740991 maximum: 9007199254740991 attemptCases: type: integer minimum: -9007199254740991 maximum: 9007199254740991 pending: type: integer minimum: -9007199254740991 maximum: 9007199254740991 active: type: integer minimum: -9007199254740991 maximum: 9007199254740991 passed: type: integer minimum: -9007199254740991 maximum: 9007199254740991 failed: type: integer minimum: -9007199254740991 maximum: 9007199254740991 inconclusive: type: integer minimum: -9007199254740991 maximum: 9007199254740991 error: type: integer minimum: -9007199254740991 maximum: 9007199254740991 cancelled: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - logicalCases - attemptCases - pending - active - passed - failed - inconclusive - error - cancelled additionalProperties: false version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 createdAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 updatedAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 finishedAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 conclusion: type: string enum: - passed - failed - inconclusive - error - cancelled result: type: object properties: schemaVersion: type: number enum: - 1 kind: type: string enum: - simulation conclusion: type: string enum: - passed - failed - inconclusive - error - cancelled durationMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 counts: type: object properties: logicalCases: type: integer minimum: 0 maximum: 10000 passed: type: integer minimum: 0 maximum: 10000 failed: type: integer minimum: 0 maximum: 10000 inconclusive: type: integer minimum: 0 maximum: 10000 error: type: integer minimum: 0 maximum: 10000 cancelled: type: integer minimum: 0 maximum: 10000 required: - logicalCases - passed - failed - inconclusive - error - cancelled additionalProperties: false attemptCases: type: integer minimum: 0 maximum: 110000 batchId: type: string pattern: ^cisuite_[0-9a-z]{12,32}$ required: - schemaVersion - kind - conclusion - durationMs - counts - attemptCases - batchId additionalProperties: false failure: type: object properties: schemaVersion: type: number enum: - 1 code: type: string pattern: ^[a-z][a-z0-9-]*\.[A-Z][A-Z0-9_]*$ source: type: string enum: - framework - world - tool - target - assertion - reporter - control message: type: string minLength: 1 maxLength: 4000 retryable: type: boolean correlationId: type: string pattern: ^corr_[A-Za-z0-9][A-Za-z0-9_-]{5,95}$ issues: default: [] type: array items: type: object properties: code: type: string minLength: 1 maxLength: 128 message: type: string minLength: 1 maxLength: 2000 path: type: array items: anyOf: - type: string - type: integer minimum: 0 maximum: 9007199254740991 suggestion: type: string minLength: 1 maxLength: 4000 required: - code - message additionalProperties: {} details: type: object additionalProperties: $ref: >- #/components/schemas/SimulationRequestWorkResponse___schema0 evidence: type: object properties: runId: type: string pattern: ^run_[A-Za-z0-9][A-Za-z0-9_-]{5,95}$ sequence: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 additionalProperties: {} required: - schemaVersion - code - source - message - retryable - issues additionalProperties: {} resultsUrl: type: string maxLength: 2048 format: uri required: - schemaVersion - batchId - projectId - environmentId - planId - planDigest - buildHash - state - counts - version - createdAtMs - updatedAtMs - resultsUrl additionalProperties: false required: - status - batch 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 SimulationRequestWorkResponse___schema0: description: Any JSON-compatible value securitySchemes: controlCredential: type: http scheme: bearer description: Opaque control credential ````