> ## 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. # Connect one discovered configuration and queue its exact revision ## OpenAPI ````yaml /api-reference/openapi.json post /v1/projects/{projectId}/repositories 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}/repositories: post: tags: - projects summary: Connect one discovered configuration and queue its exact revision operationId: repositories.connect 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/ConnectRepositoryRequest' responses: '200': description: Existing idempotent connection content: application/json: schema: $ref: '#/components/schemas/RepositoryConnectionResponse' '201': description: Repository connected content: application/json: schema: $ref: '#/components/schemas/RepositoryConnectionResponse' default: description: Canonical error envelope content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' components: schemas: ConnectRepositoryRequest: type: object properties: installationId: type: string pattern: ^[1-9][0-9]{0,19}$ repositoryId: type: string pattern: ^[1-9][0-9]{0,19}$ repository: type: string minLength: 3 maxLength: 201 pattern: ^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$ branch: type: string minLength: 1 maxLength: 255 projectRoot: anyOf: - type: string minLength: 1 maxLength: 1024 - type: string enum: - . configPath: type: string minLength: 1 maxLength: 1024 required: - installationId - repositoryId - repository - branch - projectRoot - configPath additionalProperties: false RepositoryConnectionResponse: type: object properties: binding: type: object properties: schemaVersion: type: number enum: - 1 repositoryBindingId: type: string pattern: ^repo_[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}$ installationId: type: string pattern: ^[1-9][0-9]{0,19}$ repositoryId: type: string pattern: ^[1-9][0-9]{0,19}$ repository: type: string minLength: 3 maxLength: 201 pattern: ^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$ branch: type: string minLength: 1 maxLength: 255 projectRoot: anyOf: - type: string minLength: 1 maxLength: 1024 - type: string enum: - . configPath: type: string minLength: 1 maxLength: 1024 state: type: string enum: - connected - suspended - disconnected - attention lastObservedSha: type: string pattern: ^[0-9a-f]{40}$ lastBuiltSha: type: string pattern: ^[0-9a-f]{40}$ version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 createdAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 updatedAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - schemaVersion - repositoryBindingId - organizationId - projectId - installationId - repositoryId - repository - branch - projectRoot - configPath - state - version - createdAtMs - updatedAtMs additionalProperties: false initialBuild: type: object properties: 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: number enum: - 1 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/RepositoryConnectionResponse___schema0 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 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/RepositoryConnectionResponse___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: - attempt - operation additionalProperties: false required: - binding - initialBuild 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 RepositoryConnectionResponse___schema0: description: Any JSON-compatible value securitySchemes: controlCredential: type: http scheme: bearer description: Opaque control credential ````