> ## 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. # Set a declared fault in the selected hosted world > Requires session.control and an exact environment, build, session, and lease selection. The declared fault is enabled or disabled atomically with controller evidence, not an agent Tool call. Read the returned operation for its durable completed or interrupted receipt. Retry an uncertain response with the same Idempotency-Key and request; accepted work is never retargeted. Manual fault control requires a ready session with no hosted run in its current generation. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/projects/{projectId}/sessions/{sessionId}/faults 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: [] tags: - name: authentication description: Sessions, CLI exchange, credentials, and verification keys. x-group: Authentication - name: organizations description: Organization members, billing, usage, retention, audit, and exports. x-group: Organizations - name: projects description: Project lifecycle, access, grants, and repository bindings. x-group: Projects - name: builds description: Immutable builds, uploads, source drafts, and world definitions. x-group: Builds and source - name: tools description: Project Tool discovery, approval, source, and revocation. x-group: Tool library - name: worlds description: >- Managed environments, world sessions, state, time, reset, faults, forks, and snapshots. x-group: Environments and sessions - name: runs description: >- Hosted runs, comparisons, attachments, reports, evidence bundles, sharing, and exports. x-group: Runs and evidence - name: browser description: Managed browser tests, runs, messages, streams, frames, and artifacts. x-group: Browser testing - name: callbacks description: Callback receiver approval, revocation, and signing material. x-group: Callbacks - name: github-ci description: >- GitHub installations, repository automation, CI suites, cases, evidence, and checks. x-group: GitHub and CI - name: authoring description: Authoring sessions, proposals, turns, and scenario proposals. x-group: Cloud authoring paths: /v1/projects/{projectId}/sessions/{sessionId}/faults: post: tags: - worlds summary: Set a declared fault in the selected hosted world description: >- Requires session.control and an exact environment, build, session, and lease selection. The declared fault is enabled or disabled atomically with controller evidence, not an agent Tool call. Read the returned operation for its durable completed or interrupted receipt. Retry an uncertain response with the same Idempotency-Key and request; accepted work is never retargeted. Manual fault control requires a ready session with no hosted run in its current generation. operationId: sessions.setFault parameters: - name: projectId in: path required: true schema: type: string pattern: ^prj_[0-9a-z]{12,32}$ - name: sessionId in: path required: true schema: type: string pattern: ^ses_[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/SetSessionFaultRequest' responses: '200': description: Existing idempotent fault-control operation content: application/json: schema: $ref: '#/components/schemas/SessionOperationResponse' '202': description: Fault control accepted content: application/json: schema: $ref: '#/components/schemas/SessionOperationResponse' default: description: Canonical error envelope content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' components: schemas: SetSessionFaultRequest: type: object properties: environmentId: type: string pattern: ^env_[0-9a-z]{12,32}$ buildHash: type: string pattern: ^sha256:[0-9a-f]{64}$ expectedLeaseGeneration: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 packageId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ faultId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ active: type: boolean required: - environmentId - buildHash - expectedLeaseGeneration - packageId - faultId - active additionalProperties: false SessionOperationResponse: type: object properties: session: type: object properties: schemaVersion: type: number enum: - 1 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}$ sessionId: type: string pattern: ^ses_[0-9a-z]{12,32}$ buildHash: type: string pattern: ^sha256:[0-9a-f]{64}$ drillId: description: >- Run-ready setup from this drill. Mutually exclusive with scenarioId; omit both selectors for the build baseline. type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ scenarioId: description: >- Standalone setup from this compiled scenario, without a drill or target. Mutually exclusive with drillId. type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ seed: type: string minLength: 1 maxLength: 20 callbackReceiverBindingIds: default: [] maxItems: 64 type: array items: type: string pattern: ^cbr_[0-9a-z]{12,32}$ state: type: string enum: - creating - warming - ready - resetting - degraded - expired - destroying - destroyed warmPool: description: >- Explicitly reserved warm-world lineage. Only claimed worlds can become ready for agent access. type: object properties: state: type: string enum: - preparing - ready - claimed - retired setupHash: type: string pattern: ^sha256:[0-9a-f]{64}$ required: - state - setupHash additionalProperties: false leaseGeneration: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 parentSessionId: type: string pattern: ^ses_[0-9a-z]{12,32}$ parentHostedSnapshotId: type: string pattern: ^hsnap_[0-9a-z]{12,32}$ createdAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 updatedAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 expiresAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 destroyedAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - schemaVersion - organizationId - projectId - environmentId - sessionId - buildHash - seed - callbackReceiverBindingIds - state - leaseGeneration - createdAtMs - updatedAtMs - expiresAtMs - version additionalProperties: false not: required: - drillId - scenarioId operation: type: object properties: schemaVersion: type: number enum: - 1 operationId: type: string pattern: ^op_[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}$ kind: type: string pattern: ^[a-z][a-z0-9]*(?:\.[a-z][a-z0-9_-]*)+$ state: type: string enum: - pending - running - succeeded - failed - cancelled resourceType: type: string minLength: 1 maxLength: 80 resourceId: type: string minLength: 1 maxLength: 128 error: 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/SessionOperationResponse___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: {} result: oneOf: - type: object properties: schemaVersion: type: number enum: - 1 kind: type: string enum: - world.time.advance operationId: type: string pattern: ^op_[0-9a-z]{12,32}$ sessionId: type: string pattern: ^ses_[0-9a-z]{12,32}$ leaseGeneration: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 buildHash: type: string pattern: ^sha256:[0-9a-f]{64}$ correlationId: type: string pattern: ^corr_[A-Za-z0-9][A-Za-z0-9_-]{5,95}$ requestedUs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 startedUs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 reachedUs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 maxEvents: type: integer minimum: 0 maximum: 1000000 scheduledEventsProcessed: type: integer minimum: -9007199254740991 maximum: 9007199254740991 evidenceBeforeSequence: type: integer minimum: -9007199254740991 maximum: 9007199254740991 evidenceAfterSequence: type: integer minimum: -9007199254740991 maximum: 9007199254740991 status: type: string enum: - completed - failed - interrupted eventBudgetExhausted: type: boolean failure: type: object properties: code: type: string minLength: 1 maxLength: 128 pattern: ^(control|framework|world)\.[A-Z][A-Z0-9_]*$ message: type: string minLength: 1 maxLength: 1000 scheduledEventId: type: string pattern: ^pending_[A-Za-z0-9][A-Za-z0-9_-]{5,95}$ required: - code - message additionalProperties: false required: - schemaVersion - kind - operationId - sessionId - leaseGeneration - buildHash - correlationId - requestedUs - startedUs - reachedUs - maxEvents - scheduledEventsProcessed - evidenceBeforeSequence - evidenceAfterSequence - status - eventBudgetExhausted additionalProperties: false - type: object properties: schemaVersion: type: number enum: - 1 kind: type: string enum: - world.fault.set operationId: type: string pattern: ^op_[0-9a-z]{12,32}$ sessionId: type: string pattern: ^ses_[0-9a-z]{12,32}$ leaseGeneration: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 buildHash: type: string pattern: ^sha256:[0-9a-f]{64}$ correlationId: type: string pattern: ^corr_[A-Za-z0-9][A-Za-z0-9_-]{5,95}$ packageId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ faultId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ requestedActive: type: boolean virtualTimeUs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 evidenceBeforeSequence: type: integer minimum: -9007199254740991 maximum: 9007199254740991 evidenceAfterSequence: type: integer minimum: -9007199254740991 maximum: 9007199254740991 status: type: string enum: - completed - interrupted previouslyActive: type: boolean active: type: boolean changed: type: boolean failure: type: object properties: code: type: string enum: - control.FAULT_CONTROL_INTERRUPTED message: type: string minLength: 1 maxLength: 1000 required: - code - message additionalProperties: false required: - schemaVersion - kind - operationId - sessionId - leaseGeneration - buildHash - correlationId - packageId - faultId - requestedActive - virtualTimeUs - evidenceBeforeSequence - evidenceAfterSequence - status - previouslyActive - active - changed additionalProperties: false idempotencyKey: type: string minLength: 8 maxLength: 128 pattern: ^[A-Za-z0-9._:-]+$ requestHash: type: string pattern: ^sha256:[0-9a-f]{64}$ cancelRequestedAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 createdAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 updatedAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 startedAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 finishedAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - schemaVersion - operationId - organizationId - kind - state - idempotencyKey - requestHash - createdAtMs - updatedAtMs additionalProperties: false required: - session - operation 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 SessionOperationResponse___schema0: description: Any JSON-compatible value securitySchemes: controlCredential: type: http scheme: bearer description: Opaque control credential ````