> ## 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. # Begin an explicit immutable build upload ## OpenAPI ````yaml /api-reference/openapi.json post /v1/projects/{projectId}/build-uploads 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}/build-uploads: post: summary: Begin an explicit immutable build upload operationId: buildUploads.begin parameters: - name: projectId in: path required: true schema: type: string pattern: ^prj_[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/BeginBuildUploadRequest' responses: '200': description: Existing build upload content: application/json: schema: $ref: '#/components/schemas/BuildUpload' '201': description: Build upload content: application/json: schema: $ref: '#/components/schemas/BuildUpload' default: description: Canonical error envelope content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' components: schemas: BeginBuildUploadRequest: type: object properties: buildHash: type: string pattern: ^sha256:[0-9a-f]{64}$ artifactDigest: type: string pattern: ^sha256:[0-9a-f]{64}$ bytes: type: integer minimum: 0 exclusiveMinimum: true maximum: 67108864 advanceEnvironmentId: type: string pattern: ^env_[0-9a-z]{12,32}$ expectedEnvironmentVersion: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - buildHash - artifactDigest - bytes additionalProperties: false BuildUpload: type: object properties: schemaVersion: type: number enum: - 1 attempt: type: object properties: schemaVersion: type: number enum: - 1 buildAttemptId: type: string pattern: ^attempt_[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}$ sourceKind: type: string enum: - github - upload - draft sourceDraftId: type: string pattern: ^draft_[0-9a-z]{12,32}$ sourceRevision: type: integer minimum: 1 maximum: 2147483647 sourceDigest: type: string pattern: ^sha256:[0-9a-f]{64}$ repositoryBindingId: type: string pattern: ^repo_[0-9a-z]{12,32}$ revision: type: string pattern: ^[0-9a-f]{40}$ expectedBuildHash: type: string pattern: ^sha256:[0-9a-f]{64}$ expectedArtifactDigest: type: string pattern: ^sha256:[0-9a-f]{64}$ expectedBytes: type: integer minimum: 0 exclusiveMinimum: true maximum: 67108864 advanceEnvironmentId: type: string pattern: ^env_[0-9a-z]{12,32}$ expectedEnvironmentVersion: type: integer minimum: -9007199254740991 maximum: 9007199254740991 advanceFollowers: default: false type: boolean requestedBy: type: string minLength: 1 maxLength: 255 state: type: string enum: - awaiting_upload - queued - fetching - compiling - verifying - succeeded - failed - cancelled diagnostics: type: array items: type: object additionalProperties: $ref: '#/components/schemas/BuildUpload___schema0' validationReview: type: object properties: schemaVersion: type: number enum: - 1 kind: type: string enum: - restricted-custom-tool-validation status: type: string enum: - not_configured - unsupported - failed - passed binding: type: object properties: sourceDigest: type: string pattern: ^sha256:[0-9a-f]{64}$ buildHash: type: string pattern: ^sha256:[0-9a-f]{64}$ artifactDigest: type: string pattern: ^sha256:[0-9a-f]{64}$ packageLockHash: type: string pattern: ^sha256:[0-9a-f]{64}$ toolArtifacts: minItems: 1 maxItems: 256 type: array items: type: object properties: schemaVersion: type: number enum: - 1 packageId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ version: type: string pattern: >- ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$ manifestHash: type: string pattern: ^sha256:[0-9a-f]{64}$ artifactHash: type: string pattern: ^sha256:[0-9a-f]{64}$ capabilities: maxItems: 6 type: array items: type: string enum: - state.read - state.write - clock.read - clock.schedule - random.draw - event.emit required: - schemaVersion - packageId - version - manifestHash - artifactHash - capabilities additionalProperties: false planDigest: nullable: true type: string pattern: ^sha256:[0-9a-f]{64}$ runtimeIdentity: nullable: true type: string pattern: ^sha256:[0-9a-f]{64}$ runtimePolicyDigest: type: string pattern: ^sha256:[0-9a-f]{64}$ required: - sourceDigest - buildHash - artifactDigest - packageLockHash - toolArtifacts - planDigest - runtimeIdentity - runtimePolicyDigest additionalProperties: false policy: type: object properties: version: type: number enum: - 1 execution: type: string enum: - restricted-declarative-direct-operations replay: type: string enum: - two-fresh-worlds-exact-identities limits: type: object additionalProperties: type: number minimum: 0 exclusiveMinimum: true maxSpecBytes: type: number enum: - 262144 maxSteps: type: number enum: - 128 maxAssertions: type: number enum: - 64 maxValidationMs: type: number enum: - 120000 required: - version - execution - replay - limits - maxSpecBytes - maxSteps - maxAssertions - maxValidationMs additionalProperties: false diagnostics: maxItems: 32 type: array items: type: object properties: code: type: string minLength: 1 maxLength: 96 message: type: string minLength: 1 maxLength: 500 suggestion: type: string minLength: 1 maxLength: 500 required: - code - message - suggestion additionalProperties: false coverage: maxItems: 256 type: array items: type: object properties: operation: type: object properties: packageId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ instanceId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ operationId: type: string minLength: 1 maxLength: 160 pattern: >- ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*(?:\.[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*)*$ required: - packageId - operationId additionalProperties: false exercised: type: integer minimum: 0 maximum: 256 required: - operation - exercised additionalProperties: false drills: maxItems: 8 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]+)*$ deterministic: type: boolean trials: maxItems: 2 type: array items: type: object properties: runId: type: string pattern: ^run_[A-Za-z0-9][A-Za-z0-9_-]{5,95}$ worldInstanceId: type: string pattern: ^world_[A-Za-z0-9][A-Za-z0-9_-]{5,95}$ seed: type: string enum: - '1' status: type: string enum: - sealed - runner_failed - cancelled - error verdict: type: string enum: - passed - failed - inconclusive stateHash: nullable: true type: string pattern: ^sha256:[0-9a-f]{64}$ trajectoryHash: nullable: true type: string pattern: ^sha256:[0-9a-f]{64}$ evidenceHash: nullable: true type: string pattern: ^sha256:[0-9a-f]{64}$ transcriptDigest: type: string pattern: ^sha256:[0-9a-f]{64}$ calls: maxItems: 32 type: array items: type: object properties: step: type: integer minimum: 0 maximum: 31 operation: type: object properties: packageId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ instanceId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ operationId: type: string minLength: 1 maxLength: 160 pattern: >- ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*(?:\.[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*)*$ required: - packageId - operationId additionalProperties: false inputDigest: type: string pattern: ^sha256:[0-9a-f]{64}$ status: type: string enum: - ok - denied - tool_error - unsupported - invalid errorCode: type: string minLength: 1 maxLength: 128 value: type: object properties: digest: type: string pattern: ^sha256:[0-9a-f]{64}$ bytes: type: integer minimum: -9007199254740991 maximum: 9007199254740991 value: allOf: - $ref: >- #/components/schemas/BuildUpload___schema0 preview: type: string maxLength: 256 required: - digest - bytes additionalProperties: false expected: oneOf: - type: object properties: status: type: string enum: - ok value: type: object properties: digest: type: string pattern: ^sha256:[0-9a-f]{64}$ bytes: type: integer minimum: -9007199254740991 maximum: 9007199254740991 value: allOf: - $ref: >- #/components/schemas/BuildUpload___schema0 preview: type: string maxLength: 256 required: - digest - bytes additionalProperties: false required: - status additionalProperties: false - type: object properties: status: type: string enum: - tool_error code: type: string pattern: ^tool\.[A-Z][A-Z0-9_]*$ required: - status - code additionalProperties: false matched: type: boolean handlerExercised: type: boolean required: - step - operation - inputDigest - status - expected - matched - handlerExercised additionalProperties: false checks: maxItems: 64 type: array items: type: object properties: assertionId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ kind: type: string minLength: 1 maxLength: 100 status: type: string enum: - passed - failed - inconclusive - invalid gate: type: boolean message: type: string minLength: 1 maxLength: 500 expected: type: object properties: digest: type: string pattern: ^sha256:[0-9a-f]{64}$ bytes: type: integer minimum: -9007199254740991 maximum: 9007199254740991 value: allOf: - $ref: >- #/components/schemas/BuildUpload___schema0 preview: type: string maxLength: 256 required: - digest - bytes additionalProperties: false actual: type: object properties: digest: type: string pattern: ^sha256:[0-9a-f]{64}$ bytes: type: integer minimum: -9007199254740991 maximum: 9007199254740991 value: allOf: - $ref: >- #/components/schemas/BuildUpload___schema0 preview: type: string maxLength: 256 required: - digest - bytes additionalProperties: false required: - assertionId - kind - status - gate - message - expected - actual additionalProperties: false errorCode: type: string minLength: 1 maxLength: 128 required: - runId - worldInstanceId - seed - status - verdict - stateHash - trajectoryHash - evidenceHash - transcriptDigest - calls - checks additionalProperties: false required: - drillId - targetId - deterministic - trials additionalProperties: false reviewDigest: type: string pattern: ^sha256:[0-9a-f]{64}$ required: - schemaVersion - kind - status - binding - policy - diagnostics - coverage - drills - reviewDigest additionalProperties: false libraryDataReview: type: object properties: schemaVersion: type: number enum: - 1 kind: type: string enum: - reviewed_library_data buildHash: type: string pattern: ^sha256:[0-9a-f]{64}$ sourceDigest: type: string pattern: ^sha256:[0-9a-f]{64}$ ancestorBuildHash: type: string pattern: ^sha256:[0-9a-f]{64}$ reviewDigest: type: string pattern: ^sha256:[0-9a-f]{64}$ proofDigest: type: string pattern: ^sha256:[0-9a-f]{64}$ required: - schemaVersion - kind - buildHash - sourceDigest - ancestorBuildHash - reviewDigest - proofDigest additionalProperties: false sourceClosure: default: [] maxItems: 2000 type: array items: type: string minLength: 1 maxLength: 1024 buildHash: type: string pattern: ^sha256:[0-9a-f]{64}$ createdAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 updatedAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 finishedAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - schemaVersion - buildAttemptId - organizationId - projectId - sourceKind - advanceFollowers - requestedBy - state - diagnostics - sourceClosure - createdAtMs - updatedAtMs additionalProperties: false method: type: string enum: - PUT uploadUrl: type: string maxLength: 4096 format: uri headers: default: {} type: object additionalProperties: type: string expiresAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - schemaVersion - attempt - method - uploadUrl - headers - expiresAtMs 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 BuildUpload___schema0: description: Any JSON-compatible value securitySchemes: controlCredential: type: http scheme: bearer description: Opaque control credential ````