> ## 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. # Claim the next run > Requires `runs:execute`. Customer runners claim an attempt and receive its lease token and limits. A claim allocates ownership but does not prove the target started. Replay the exact claim key after an uncertain response; a new key may claim another run. Native SDKs manage this protocol. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/batches/{batchId}/claim openapi: 3.1.0 info: title: Firedrill API version: '2026-10-14' description: >- Authenticated simulation coordination, retained evidence and controlled Tools. Your customer-owned runner executes the target. This reference covers the documented JSON workflows; Tool-native HTTP routes and MCP methods are discovered from the selected Tool. Structural schemas do not replace canonical validation or capability checks. servers: - url: https://api.firedrill.run security: - FiredrillCredential: [] tags: - name: discovery description: Capabilities, authority and structural authoring schemas. - name: projects description: Projects and their logical environment. - name: simulations description: Preparation, queued batches and cancellation. - name: runs description: Individual recorded executions. - name: reports description: Retained observations, distributions and descriptive comparisons. - name: assessment description: Optional semantic assessment and authored scenario ranking. - name: evidence description: Authenticated captured files. - name: runner-protocol description: Advanced customer-runner coordination; native SDKs manage this protocol. - name: scenarios description: Immutable retained versions of repository-authored scenarios. - name: credentials description: Expiring scoped CI credentials. - name: authentication description: Human-approved sign-in boundaries. - name: tools description: Tool releases, data, instances and observations. - name: tool-connections description: Bounded target/manual grants, separate from control authority. - name: tool-lifecycle description: Epoch-fenced reusable Tool actions and exact-key recovery. paths: /v1/batches/{batchId}/claim: post: tags: - runner-protocol summary: Claim the next run description: >- Requires `runs:execute`. Customer runners claim an attempt and receive its lease token and limits. A claim allocates ownership but does not prove the target started. Replay the exact claim key after an uncertain response; a new key may claim another run. Native SDKs manage this protocol. operationId: batches_claim parameters: - name: batchId in: path required: true schema: type: string minLength: 1 maxLength: 160 - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: type: object properties: runnerId: type: string minLength: 1 maxLength: 160 required: - runnerId additionalProperties: false responses: '200': description: The retained resource or operation response. content: application/json: schema: $ref: '#/components/schemas/ClaimResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '410': $ref: '#/components/responses/Gone' '413': $ref: '#/components/responses/PayloadTooLarge' '415': $ref: '#/components/responses/UnsupportedMediaType' '422': $ref: '#/components/responses/InvalidInput' '429': $ref: '#/components/responses/Capacity' '500': $ref: '#/components/responses/Internal' '503': $ref: '#/components/responses/Unavailable' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: true description: >- Save a unique stable key for this exact logical action, at most 200 characters. Reuse it with identical input after an uncertain response. A new key is new intent; it must not be used merely to recover an accepted action. schema: type: string minLength: 1 maxLength: 200 schemas: ClaimResponse: type: object properties: claim: anyOf: - type: 'null' - $ref: '#/components/schemas/ClaimedRun' batch: $ref: '#/components/schemas/BatchProgress' required: - claim - batch ClaimedRun: type: object properties: run: $ref: '#/components/schemas/Run' attemptId: type: string leaseToken: type: string leaseExpiresAt: type: string limits: type: object properties: timeoutMs: type: number maxRuns: anyOf: - type: 'null' - type: number maxOutputBytes: type: number required: - timeoutMs - maxRuns - maxOutputBytes required: - run - attemptId - leaseToken - leaseExpiresAt - limits BatchProgress: type: object properties: projectId: type: string environmentId: type: string name: type: string id: type: string operations: anyOf: - $ref: '#/components/schemas/BatchOperations' targetExecution: anyOf: - $ref: '#/components/schemas/TargetExecutionDisclosure' submission: anyOf: - type: 'null' - $ref: '#/components/schemas/SubmissionMetadata' createdAt: type: string cancellationRequested: type: boolean total: type: number counts: type: object properties: error: type: number queued: type: number running: type: number completed: type: number interrupted: type: number cancelled: type: number required: - error - queued - running - completed - interrupted - cancelled charge: type: object properties: amount: type: number const: 0 policy: type: string const: free_early_access required: - amount - policy required: - projectId - environmentId - name - id - createdAt - cancellationRequested - total - counts - charge ApiError: type: object properties: error: type: object properties: code: type: string message: type: string repair: type: string requestId: type: string details: anyOf: - type: 'null' - type: string - type: number - type: boolean const: false - type: boolean const: true - type: array items: $ref: '#/components/schemas/JsonValue' - type: object properties: {} required: [] additionalProperties: $ref: '#/components/schemas/JsonValue' validation: anyOf: - $ref: '#/components/schemas/ValidationDiagnostics' required: - code - message - repair - requestId required: - error Run: type: object properties: id: type: string batchId: type: string projectId: type: string environmentId: type: string scenario: $ref: '#/components/schemas/Scenario' configuration: $ref: '#/components/schemas/Configuration' repetition: type: number target: $ref: '#/components/schemas/Target' scenarioRevision: anyOf: - type: string measurements: anyOf: - $ref: '#/components/schemas/RunMeasurements' execution: $ref: '#/components/schemas/ExecutionState' attemptId: anyOf: - type: 'null' - type: string startedAt: anyOf: - type: 'null' - type: string finishedAt: anyOf: - type: 'null' - type: string output: $ref: '#/components/schemas/JsonValue' reason: anyOf: - type: 'null' - type: string assessment: $ref: '#/components/schemas/AssessmentState' gate: $ref: '#/components/schemas/GateState' required: - id - batchId - projectId - environmentId - scenario - configuration - repetition - target - execution - attemptId - startedAt - finishedAt - output - reason - assessment - gate BatchOperations: type: object properties: schemaVersion: type: string const: 2026-10-15-batch-operations.1 observedAt: type: string runner: type: object properties: state: type: string enum: - live_lease_observed - no_live_lease_observed liveLeases: type: number expiredUnreconciled: type: number finishedAttempts: type: number lastClaimedAt: anyOf: - type: 'null' - type: string latestLeaseExpiresAt: anyOf: - type: 'null' - type: string required: - state - liveLeases - expiredUnreconciled - finishedAttempts - lastClaimedAt - latestLeaseExpiresAt resources: type: object properties: queuedRuns: type: number claimedRunSlots: type: number runSlotLimit: type: number toolInstances: type: object properties: creating: type: number active: type: number paused: type: number expired: type: number destroyed: type: number recoveryRequired: type: number required: - creating - active - paused - expired - destroyed - recoveryRequired toolSessions: type: object properties: preparing: type: number ready: type: number closing: type: number closed: type: number required: - preparing - ready - closing - closed pendingBindings: type: number retainedBindings: type: number cleanupPending: type: number required: - queuedRuns - claimedRunSlots - runSlotLimit - toolInstances - toolSessions - pendingBindings - retainedBindings - cleanupPending notes: type: array items: type: string required: - schemaVersion - observedAt - runner - resources - notes TargetExecutionDisclosure: type: object properties: schemaVersion: type: string const: 2026-10-16-target-execution.1 requestedConcurrency: type: number acknowledgement: type: string enum: - not_recorded - caller_declared mode: type: string enum: - isolated_runner_contract - sequential_non_hermetic - acknowledged_shared_state - unacknowledged_parallel automaticTargetReset: type: boolean const: false isolationAttestation: type: string const: not_provided required: - schemaVersion - requestedConcurrency - acknowledgement - mode - automaticTargetReset - isolationAttestation SubmissionMetadata: type: object properties: schemaVersion: type: string const: 2026-10-15-inspection.1 origin: type: string enum: - cli - sdk - mcp - ci - api ci: anyOf: - $ref: '#/components/schemas/CiContext' required: - schemaVersion - origin JsonValue: description: >- Any JSON value: null, boolean, finite number, string, array or object. The request transport must contain valid JSON; canonical validation rejects nonfinite numbers. ValidationDiagnostics: type: object properties: issues: type: array items: $ref: '#/components/schemas/ValidationIssue' totalIssues: type: number omittedIssues: type: number required: - issues - totalIssues - omittedIssues Scenario: type: object properties: id: type: string name: type: string input: $ref: '#/components/schemas/JsonValue' checks: type: array items: type: object properties: id: type: string description: type: string path: type: string comparator: type: string enum: - equals - contains - exists - lte - gte required: type: boolean expected: anyOf: - type: 'null' - type: string - type: number - type: boolean const: false - type: boolean const: true - type: array items: $ref: '#/components/schemas/JsonValue' - type: object properties: {} required: [] additionalProperties: $ref: '#/components/schemas/JsonValue' source: anyOf: - type: object properties: kind: type: string const: service_state namespace: type: string rowId: type: string schemaVersion: type: string const: 2026-10-15-effect-check.1 service: type: string required: - kind - namespace - rowId - schemaVersion - service - type: object properties: kind: type: string const: service_activity schemaVersion: type: string const: 2026-10-15-effect-check.1 service: type: string where: anyOf: - type: object properties: path: type: string equals: $ref: '#/components/schemas/JsonValue' required: - path - equals required: - kind - schemaVersion - service - type: object properties: kind: type: string const: service_pending schemaVersion: type: string const: 2026-10-15-effect-check.1 service: type: string required: - kind - schemaVersion - service numeric: anyOf: - $ref: '#/components/schemas/NumericCheck' required: - id - description - path - comparator - required description: anyOf: - type: string rubric: anyOf: - type: object properties: id: type: string version: type: string dimensions: type: array items: type: object properties: id: type: string description: type: string anchors: type: array prefixItems: - type: string - type: string - type: string - type: string - type: string minItems: 5 maxItems: 5 evidenceKinds: anyOf: - type: array items: type: string enum: - image - text - audio - video applicability: anyOf: - type: object properties: state: type: string const: applicable required: - state - type: object properties: state: type: string const: not_applicable reason: type: string required: - state - reason missingEvidence: type: string enum: - not_assessable required: - id - description - anchors composite: anyOf: - $ref: '#/components/schemas/CompositePolicy' policyVersion: type: string enum: - 2026-10-15-assessment.1 required: - id - version - dimensions metrics: anyOf: - type: array items: $ref: '#/components/schemas/TaskMetricDefinition' serviceDatasets: anyOf: - type: object properties: {} required: [] additionalProperties: type: string sequence: anyOf: - type: object properties: schemaVersion: type: string const: 2026-10-14-sequence.1 steps: type: array items: $ref: '#/components/schemas/SequenceStep' required: - schemaVersion - steps required: - id - name - input - checks Configuration: type: object properties: id: type: string parameters: type: object properties: {} required: [] additionalProperties: $ref: '#/components/schemas/JsonValue' required: - id - parameters Target: anyOf: - type: object properties: kind: type: string const: command argv: type: array items: type: string cwd: anyOf: - type: string metadata: anyOf: - $ref: '#/components/schemas/TargetMetadata' required: - kind - argv - type: object properties: kind: type: string const: http url: type: string method: type: string enum: - POST - PUT metadata: anyOf: - $ref: '#/components/schemas/TargetMetadata' required: - kind - url - method - type: object properties: kind: type: string const: native name: type: string metadata: anyOf: - $ref: '#/components/schemas/TargetMetadata' required: - kind - name - type: object properties: kind: type: string const: isolated_node entrypoint: type: string image: type: string files: type: array items: type: object properties: path: type: string bytes: type: number sha256: type: string required: - path - bytes - sha256 approvedServices: type: array items: type: object properties: id: type: string url: type: string routes: type: array items: type: object properties: method: type: string enum: - POST - PUT - GET - PATCH - DELETE path: type: string required: - method - path allowPrivateAddress: anyOf: - type: boolean const: true required: - id - url - routes metadata: anyOf: - $ref: '#/components/schemas/TargetMetadata' required: - kind - entrypoint - image - files - approvedServices RunMeasurements: type: object properties: schemaVersion: type: string const: 2026-10-16-run-measurements.1 items: type: array items: $ref: '#/components/schemas/RunMeasurement' notes: type: array items: type: string required: - schemaVersion - items - notes ExecutionState: type: string enum: - error - queued - running - completed - interrupted - cancelled AssessmentState: type: string enum: - error - completed - not_requested - pending - partial - unavailable GateState: type: string enum: - not_configured - allow - block - inconclusive CiContext: type: object properties: schemaVersion: type: string const: 2026-10-16-ci-context.1 provider: type: string const: github serverUrl: type: string repository: type: string runId: type: string runAttempt: type: number commit: type: string ref: anyOf: - type: string workflow: anyOf: - type: string job: anyOf: - type: string event: anyOf: - type: string pullRequest: anyOf: - type: number required: - schemaVersion - provider - serverUrl - repository - runId - runAttempt - commit ValidationIssue: type: object properties: path: type: array items: anyOf: - type: string - type: number code: type: string message: type: string pathTruncated: anyOf: - type: boolean const: true required: - path - code - message NumericCheck: type: object properties: schemaVersion: type: string const: 2026-10-16-numeric-check.1 unit: type: string absoluteTolerance: type: number required: - schemaVersion - unit - absoluteTolerance CompositePolicy: type: object properties: schemaVersion: type: string const: 2026-10-16-composite.1 method: type: string const: weighted_mean_ordinal weights: type: array items: type: object properties: dimensionId: type: string weight: type: number required: - dimensionId - weight required: - schemaVersion - method - weights TaskMetricDefinition: type: object properties: schemaVersion: type: string const: 2026-10-16-task-metric.1 id: type: string label: type: string path: type: string unit: type: string direction: type: string enum: - higher_is_better - lower_is_better - neutral source: anyOf: - type: object properties: kind: type: string const: service_state namespace: type: string rowId: type: string schemaVersion: type: string const: 2026-10-15-effect-check.1 service: type: string required: - kind - namespace - rowId - schemaVersion - service - type: object properties: kind: type: string const: service_activity schemaVersion: type: string const: 2026-10-15-effect-check.1 service: type: string where: anyOf: - type: object properties: path: type: string equals: $ref: '#/components/schemas/JsonValue' required: - path - equals required: - kind - schemaVersion - service - type: object properties: kind: type: string const: service_pending schemaVersion: type: string const: 2026-10-15-effect-check.1 service: type: string required: - kind - schemaVersion - service required: - schemaVersion - id - label - path - unit SequenceStep: anyOf: - type: object properties: kind: type: string const: target id: type: string input: anyOf: - type: 'null' - type: string - type: number - type: boolean const: false - type: boolean const: true - type: array items: $ref: '#/components/schemas/JsonValue' - type: object properties: {} required: [] additionalProperties: $ref: '#/components/schemas/JsonValue' when: anyOf: - type: object properties: path: type: string comparator: type: string enum: - equals - contains - exists - lte - gte step: type: string expected: anyOf: - type: 'null' - type: string - type: number - type: boolean const: false - type: boolean const: true - type: array items: $ref: '#/components/schemas/JsonValue' - type: object properties: {} required: [] additionalProperties: $ref: '#/components/schemas/JsonValue' required: - path - comparator - step required: - kind - id - type: object properties: kind: type: string const: service service: type: string operationId: type: string arguments: type: object properties: {} required: [] additionalProperties: $ref: '#/components/schemas/JsonValue' id: type: string when: anyOf: - type: object properties: path: type: string comparator: type: string enum: - equals - contains - exists - lte - gte step: type: string expected: anyOf: - type: 'null' - type: string - type: number - type: boolean const: false - type: boolean const: true - type: array items: $ref: '#/components/schemas/JsonValue' - type: object properties: {} required: [] additionalProperties: $ref: '#/components/schemas/JsonValue' required: - path - comparator - step required: - kind - service - operationId - arguments - id - type: object properties: kind: type: string const: wait_for service: type: string operationId: type: string arguments: type: object properties: {} required: [] additionalProperties: $ref: '#/components/schemas/JsonValue' until: $ref: '#/components/schemas/Predicate' maxAttempts: type: number intervalMs: type: number id: type: string when: anyOf: - type: object properties: path: type: string comparator: type: string enum: - equals - contains - exists - lte - gte step: type: string expected: anyOf: - type: 'null' - type: string - type: number - type: boolean const: false - type: boolean const: true - type: array items: $ref: '#/components/schemas/JsonValue' - type: object properties: {} required: [] additionalProperties: $ref: '#/components/schemas/JsonValue' required: - path - comparator - step required: - kind - service - operationId - arguments - until - maxAttempts - intervalMs - id - type: object properties: kind: type: string const: advance_time service: type: string toUs: type: number maxEvents: type: number id: type: string when: anyOf: - type: object properties: path: type: string comparator: type: string enum: - equals - contains - exists - lte - gte step: type: string expected: anyOf: - type: 'null' - type: string - type: number - type: boolean const: false - type: boolean const: true - type: array items: $ref: '#/components/schemas/JsonValue' - type: object properties: {} required: [] additionalProperties: $ref: '#/components/schemas/JsonValue' required: - path - comparator - step required: - kind - service - toUs - maxEvents - id - type: object properties: kind: type: string const: snapshot service: type: string id: type: string when: anyOf: - type: object properties: path: type: string comparator: type: string enum: - equals - contains - exists - lte - gte step: type: string expected: anyOf: - type: 'null' - type: string - type: number - type: boolean const: false - type: boolean const: true - type: array items: $ref: '#/components/schemas/JsonValue' - type: object properties: {} required: [] additionalProperties: $ref: '#/components/schemas/JsonValue' required: - path - comparator - step required: - kind - service - id - type: object properties: kind: type: string const: restore service: type: string snapshotStepId: type: string boundary: type: string const: service_only id: type: string when: anyOf: - type: object properties: path: type: string comparator: type: string enum: - equals - contains - exists - lte - gte step: type: string expected: anyOf: - type: 'null' - type: string - type: number - type: boolean const: false - type: boolean const: true - type: array items: $ref: '#/components/schemas/JsonValue' - type: object properties: {} required: [] additionalProperties: $ref: '#/components/schemas/JsonValue' required: - path - comparator - step required: - kind - service - snapshotStepId - boundary - id TargetMetadata: type: object properties: schemaVersion: type: string const: 2026-10-15-target-metadata.1 source: anyOf: - type: object properties: revision: type: string dirty: type: string enum: - clean - dirty - unknown contentDigest: anyOf: - type: string required: - revision - dirty resetCoverage: anyOf: - type: object properties: applicationDatabase: type: string enum: - unknown - customer_managed - not_reset - not_used cache: type: string enum: - unknown - customer_managed - not_reset - not_used filesystem: type: string enum: - unknown - customer_managed - not_reset - not_used conversationMemory: type: string enum: - unknown - customer_managed - not_reset - not_used outstandingJobs: type: string enum: - unknown - customer_managed - not_reset - not_used browserProfile: type: string enum: - unknown - customer_managed - not_reset - not_used externalState: type: string enum: - unknown - customer_managed - not_reset - not_used required: [] required: - schemaVersion RunMeasurement: anyOf: - type: object properties: name: $ref: '#/components/schemas/RunMeasurementName' unit: $ref: '#/components/schemas/RunMeasurementUnit' provenance: $ref: '#/components/schemas/RunMeasurementProvenance' state: type: string const: observed value: type: number required: - name - unit - provenance - state - value - type: object properties: name: $ref: '#/components/schemas/RunMeasurementName' unit: $ref: '#/components/schemas/RunMeasurementUnit' provenance: $ref: '#/components/schemas/RunMeasurementProvenance' state: type: string const: not_recorded value: type: 'null' required: - name - unit - provenance - state - value - type: object properties: name: $ref: '#/components/schemas/RunMeasurementName' unit: $ref: '#/components/schemas/RunMeasurementUnit' provenance: $ref: '#/components/schemas/RunMeasurementProvenance' state: type: string const: invalid value: type: 'null' required: - name - unit - provenance - state - value Predicate: type: object properties: path: type: string comparator: type: string enum: - equals - contains - exists - lte - gte expected: anyOf: - type: 'null' - type: string - type: number - type: boolean const: false - type: boolean const: true - type: array items: $ref: '#/components/schemas/JsonValue' - type: object properties: {} required: [] additionalProperties: $ref: '#/components/schemas/JsonValue' required: - path - comparator RunMeasurementName: type: string enum: - serviceClaimToFinishMs - runnerDurationMs - runnerLatencyMs - targetInputTokens - targetOutputTokens - targetCostUsd RunMeasurementUnit: type: string enum: - ms - tokens - USD RunMeasurementProvenance: type: string enum: - service_clock_claim_to_finish - runner_reported_metrics.durationMs - runner_reported_metrics.latencyMs - runner_reported_metrics.modelUsage.inputTokens - runner_reported_metrics.modelUsage.outputTokens - runner_reported_metrics.modelUsage.costUsd responses: BadRequest: description: >- Malformed request or missing operation key. Repair the input before retrying. content: application/json: schema: $ref: '#/components/schemas/ApiError' Unauthorized: description: >- Missing, expired or revoked authority. Complete supported sign-in or use an authorized credential. content: application/json: schema: $ref: '#/components/schemas/ApiError' Forbidden: description: >- The current capability, actor, audience or ownership grant does not allow this operation. content: application/json: schema: $ref: '#/components/schemas/ApiError' NotFound: description: The exact resource is unavailable under the current authority and scope. content: application/json: schema: $ref: '#/components/schemas/ApiError' Conflict: description: >- Selected context, epoch, revision, lease or saved operation intent conflicts; inspect retained state. content: application/json: schema: $ref: '#/components/schemas/ApiError' Gone: description: >- Retained content is expired, deleted or unavailable under its retention fence. Metadata is not a replacement payload. content: application/json: schema: $ref: '#/components/schemas/ApiError' PayloadTooLarge: description: >- Request, response or retained-resource size exceeds this operation’s enforced bound. content: application/json: schema: $ref: '#/components/schemas/ApiError' UnsupportedMediaType: description: Send the documented JSON or exact artifact media type. content: application/json: schema: $ref: '#/components/schemas/ApiError' InvalidInput: description: >- Input failed canonical validation. Inspect error.validation and repair the indicated fields. content: application/json: schema: $ref: '#/components/schemas/ApiError' Capacity: description: >- Bounded capacity or resource admission rejected the operation. Inspect retained work before retrying. content: application/json: schema: $ref: '#/components/schemas/ApiError' Internal: description: >- The service could not complete the request. Inspect retained state before exact-key recovery. content: application/json: schema: $ref: '#/components/schemas/ApiError' Unavailable: description: >- A required service, provider or authority check is unavailable. Existing evidence remains separate from this failure. content: application/json: schema: $ref: '#/components/schemas/ApiError' securitySchemes: FiredrillCredential: type: http scheme: bearer description: >- Opaque Firedrill interactive or scoped machine credential. The CLI handles human-approved login; CI stores its scoped credential as FIREDRILL_TOKEN. Capabilities and project/environment ownership are rechecked at use. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.