> ## 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. # Prepare a drill suite from immutable repository revisions ## OpenAPI ````yaml /api-reference/openapi.json post /v1/ci/suites 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/ci/suites: post: tags: - github-ci summary: Prepare a drill suite from immutable repository revisions operationId: ci.suites.prepare parameters: - 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/PrepareCiSuiteRequest' responses: '200': description: Idempotent replay of the existing suite content: application/json: schema: $ref: '#/components/schemas/CiSuite' '202': description: Suite accepted for preparation content: application/json: schema: $ref: '#/components/schemas/CiSuite' default: description: Canonical error envelope content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' components: schemas: PrepareCiSuiteRequest: oneOf: - type: object properties: kind: type: string enum: - github_invocation required: - kind additionalProperties: false - type: object properties: kind: type: string enum: - repository_revisions environmentId: type: string pattern: ^env_[0-9a-z]{12,32}$ repositoryBindingId: type: string pattern: ^repo_[0-9a-z]{12,32}$ suiteKey: default: default type: string minLength: 1 maxLength: 96 pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*$ source: oneOf: - type: object properties: kind: type: string enum: - single_revision candidateRevision: type: string pattern: ^[0-9a-f]{40}$ required: - kind - candidateRevision additionalProperties: false - type: object properties: kind: type: string enum: - revision_comparison baseRevision: type: string pattern: ^[0-9a-f]{40}$ candidateRevision: type: string pattern: ^[0-9a-f]{40}$ required: - kind - baseRevision - candidateRevision additionalProperties: false required: - kind - environmentId - repositoryBindingId - suiteKey - source additionalProperties: false CiSuite: type: object properties: schemaVersion: type: number enum: - 1 ciSuiteId: type: string pattern: ^cisuite_[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}$ repositoryBindingId: type: string pattern: ^repo_[0-9a-z]{12,32}$ credentialId: type: string pattern: ^cred_[0-9a-z]{12,32}$ ciInvocationId: type: string pattern: ^ci_[0-9a-z]{12,32}$ provider: type: string enum: - github_actions - service suiteKey: type: string minLength: 1 maxLength: 96 pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*$ source: oneOf: - type: object properties: kind: type: string enum: - single_revision candidateRevision: type: string pattern: ^[0-9a-f]{40}$ required: - kind - candidateRevision additionalProperties: false - type: object properties: kind: type: string enum: - revision_comparison baseRevision: type: string pattern: ^[0-9a-f]{40}$ candidateRevision: type: string pattern: ^[0-9a-f]{40}$ required: - kind - baseRevision - candidateRevision additionalProperties: false evidenceUrl: type: string maxLength: 2048 format: uri state: type: string enum: - preparing - running - cancelling - completed - failed - cancelled cancellationReason: type: string minLength: 1 maxLength: 1000 conclusion: type: string enum: - passed - failed - inconclusive - error - cancelled result: type: object properties: schemaVersion: type: number enum: - 1 ciSuiteId: type: string pattern: ^cisuite_[0-9a-z]{12,32}$ conclusion: type: string enum: - passed - failed - inconclusive - error - cancelled durationMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 gate: type: object properties: blockingClassifications: type: array items: anyOf: - type: string enum: - contract - type: string enum: - safety minItems: 2 maxItems: 2 candidate: type: object properties: logicalCases: 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 - passed - failed - inconclusive - error - cancelled additionalProperties: false blocksMerge: type: boolean reason: type: string enum: - passed - contract_or_safety_failed - inconclusive - execution_error - cancelled required: - blockingClassifications - candidate - blocksMerge - reason additionalProperties: false summaries: maxItems: 6 type: array items: type: object properties: logicalCases: 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 side: type: string enum: - baseline - candidate classification: type: string enum: - contract - safety - quality attemptCases: type: integer minimum: -9007199254740991 maximum: 9007199254740991 observedSamples: type: integer minimum: -9007199254740991 maximum: 9007199254740991 passRate: type: number minimum: 0 maximum: 1 confidence95: type: object properties: method: type: string enum: - wilson lower: type: number minimum: 0 maximum: 1 upper: type: number minimum: 0 maximum: 1 required: - method - lower - upper additionalProperties: false timing: type: object properties: measuredRuns: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 meanMs: type: number minimum: 0 p50Ms: type: number minimum: 0 p95Ms: type: number minimum: 0 required: - measuredRuns - meanMs - p50Ms - p95Ms additionalProperties: false required: - logicalCases - passed - failed - inconclusive - error - cancelled - side - classification - attemptCases - observedSamples additionalProperties: false comparisons: type: object properties: totalPairs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 inspectedPairs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 changedPairs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 unchangedPairs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 notComparablePairs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 uninspectedPairs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 inspectionErrors: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: maxItems: 12 type: array items: type: object properties: drillId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ trial: type: integer minimum: 0 exclusiveMinimum: true maximum: 10000 seed: type: string pattern: ^(0|[1-9]\d{0,19})$ baseline: type: object properties: hostedRunId: type: string pattern: ^hrun_[0-9a-z]{12,32}$ evidenceBundleId: type: string pattern: ^evidence_[0-9a-z]{12,32}$ revision: type: string pattern: ^[0-9a-f]{40}$ attempt: type: integer minimum: 0 exclusiveMinimum: true maximum: 11 outcome: type: string enum: - passed - failed - inconclusive - error - cancelled durationMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - hostedRunId - evidenceBundleId - revision - attempt - outcome - durationMs additionalProperties: false candidate: type: object properties: hostedRunId: type: string pattern: ^hrun_[0-9a-z]{12,32}$ evidenceBundleId: type: string pattern: ^evidence_[0-9a-z]{12,32}$ revision: type: string pattern: ^[0-9a-f]{40}$ attempt: type: integer minimum: 0 exclusiveMinimum: true maximum: 11 outcome: type: string enum: - passed - failed - inconclusive - error - cancelled durationMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - hostedRunId - evidenceBundleId - revision - attempt - outcome - durationMs additionalProperties: false compatibility: type: object properties: status: type: string enum: - exact_inputs - descriptive_only - incompatible canAttributeBehaviorChange: type: boolean differences: type: array items: type: string enum: - drill - scenario - target - seed - build - package_lock - runtime_controls explanation: type: string minLength: 1 maxLength: 2000 required: - status - canAttributeBehaviorChange - differences - explanation additionalProperties: false outcome: type: string enum: - changed - not_comparable timing: type: object properties: baselineMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 candidateMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 deltaMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - baselineMs - candidateMs - deltaMs additionalProperties: false changes: type: object properties: verdictChanged: type: boolean stateChanged: type: boolean trajectoryChanged: type: boolean operationCounts: type: object properties: total: type: integer minimum: -9007199254740991 maximum: 9007199254740991 items: maxItems: 12 type: array items: type: object properties: subject: type: string minLength: 1 maxLength: 1024 baseline: type: integer minimum: -9007199254740991 maximum: 9007199254740991 candidate: type: integer minimum: -9007199254740991 maximum: 9007199254740991 delta: type: integer minimum: -9007199254740991 maximum: 9007199254740991 baselineErrors: type: integer minimum: -9007199254740991 maximum: 9007199254740991 candidateErrors: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - subject - baseline - candidate - delta - baselineErrors - candidateErrors additionalProperties: false omitted: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - total - items - omitted additionalProperties: false stateChangeCounts: type: object properties: total: type: integer minimum: -9007199254740991 maximum: 9007199254740991 items: maxItems: 12 type: array items: type: object properties: subject: type: string minLength: 1 maxLength: 1024 baseline: type: integer minimum: -9007199254740991 maximum: 9007199254740991 candidate: type: integer minimum: -9007199254740991 maximum: 9007199254740991 delta: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - subject - baseline - candidate - delta additionalProperties: false omitted: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - total - items - omitted additionalProperties: false eventCounts: type: object properties: total: type: integer minimum: -9007199254740991 maximum: 9007199254740991 items: maxItems: 12 type: array items: type: object properties: subject: type: string minLength: 1 maxLength: 1024 baseline: type: integer minimum: -9007199254740991 maximum: 9007199254740991 candidate: type: integer minimum: -9007199254740991 maximum: 9007199254740991 delta: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - subject - baseline - candidate - delta additionalProperties: false omitted: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - total - items - omitted additionalProperties: false assertions: type: object properties: total: type: integer minimum: -9007199254740991 maximum: 9007199254740991 items: maxItems: 12 type: array items: type: object properties: checkpointId: type: string minLength: 1 maxLength: 512 assertionId: type: string minLength: 1 maxLength: 512 baseline: type: string enum: - passed - failed - inconclusive - invalid candidate: type: string enum: - passed - failed - inconclusive - invalid actualChanged: type: boolean expectedChanged: type: boolean required: - checkpointId - assertionId - actualChanged additionalProperties: false omitted: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - total - items - omitted additionalProperties: false interactions: type: object properties: total: type: integer minimum: -9007199254740991 maximum: 9007199254740991 items: maxItems: 12 type: array items: type: object properties: interactionId: type: string minLength: 1 maxLength: 512 baseline: type: string minLength: 1 maxLength: 128 candidate: type: string minLength: 1 maxLength: 128 required: - interactionId additionalProperties: false omitted: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - total - items - omitted additionalProperties: false required: - verdictChanged - operationCounts - stateChangeCounts - eventCounts - assertions - interactions additionalProperties: false required: - drillId - trial - seed - baseline - candidate - compatibility - outcome - timing - changes additionalProperties: false omittedDetails: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - totalPairs - inspectedPairs - changedPairs - unchangedPairs - notComparablePairs - uninspectedPairs - inspectionErrors - details - omittedDetails additionalProperties: false required: - schemaVersion - ciSuiteId - conclusion - durationMs - gate - summaries - comparisons additionalProperties: false githubReviewDelivery: type: object properties: schemaVersion: type: number enum: - 1 state: type: string enum: - pending - delivered - failed commentExpected: type: boolean attempts: type: integer minimum: 0 maximum: 100 checkRunId: type: string pattern: ^[1-9][0-9]{0,19}$ checkUrl: type: string maxLength: 2048 format: uri commentId: type: string pattern: ^[1-9][0-9]{0,19}$ commentUrl: type: string maxLength: 2048 format: uri lastErrorCode: type: string minLength: 1 maxLength: 96 createdAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 updatedAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 finishedAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - schemaVersion - state - commentExpected - attempts - createdAtMs - updatedAtMs additionalProperties: false policy: type: object properties: schemaVersion: type: number enum: - 1 sourceSide: type: string enum: - baseline - candidate sourceBuildHash: type: string pattern: ^sha256:[0-9a-f]{64}$ suiteKey: type: string minLength: 1 maxLength: 96 pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*$ concurrency: type: integer minimum: 0 exclusiveMinimum: true maximum: 64 drills: minItems: 1 maxItems: 10000 type: array items: type: object properties: 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 trials: type: integer minimum: 0 exclusiveMinimum: true maximum: 10000 retries: type: integer minimum: 0 maximum: 10 timeoutMs: type: integer minimum: 0 exclusiveMinimum: true maximum: 86400000 required: - drillId - targetId - classification - trials - retries - timeoutMs additionalProperties: false logicalCases: type: integer minimum: 0 exclusiveMinimum: true maximum: 10000 required: - schemaVersion - sourceSide - sourceBuildHash - suiteKey - concurrency - drills - logicalCases additionalProperties: false builds: minItems: 1 maxItems: 2 type: array items: type: object properties: schemaVersion: type: number enum: - 1 side: type: string enum: - baseline - candidate revision: type: string pattern: ^[0-9a-f]{40}$ state: type: string enum: - queued - building - ready - failed - cancelled buildAttemptId: type: string pattern: ^attempt_[0-9a-z]{12,32}$ buildHash: type: string pattern: ^sha256:[0-9a-f]{64}$ 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/CiSuite___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: {} updatedAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - schemaVersion - side - revision - state - buildAttemptId - updatedAtMs additionalProperties: false 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 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/CiSuite___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: {} 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 required: - schemaVersion - ciSuiteId - organizationId - projectId - environmentId - repositoryBindingId - credentialId - provider - suiteKey - source - evidenceUrl - state - builds - counts - version - createdAtMs - updatedAtMs 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 CiSuite___schema0: description: Any JSON-compatible value securitySchemes: controlCredential: type: http scheme: bearer description: Opaque control credential ````