> ## 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. # Start a reserved agent interaction > Only a fresh accepted start includes an access binding. A replay acknowledges the original start and must not invoke the customer agent again. A lost start acknowledgment is uncertain, not permission to retry the agent. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/ci/suites/{ciSuiteId}/cases/{ciCaseId}/claims/{ciClaimId}/start 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/ci/suites/{ciSuiteId}/cases/{ciCaseId}/claims/{ciClaimId}/start: post: summary: Start a reserved agent interaction description: >- Only a fresh accepted start includes an access binding. A replay acknowledges the original start and must not invoke the customer agent again. A lost start acknowledgment is uncertain, not permission to retry the agent. operationId: ci.suites.startClaim parameters: - name: ciSuiteId in: path required: true schema: type: string pattern: ^cisuite_[0-9a-z]{12,32}$ - name: ciCaseId in: path required: true schema: type: string pattern: ^cicase_[0-9a-z]{12,32}$ - name: ciClaimId in: path required: true schema: type: string pattern: ^ciclaim_[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/MutateCiCaseClaimRequest' responses: '200': description: Claim ownership receipt content: application/json: schema: $ref: '#/components/schemas/StartCiCaseClaimResponse' default: description: Canonical error envelope content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' components: schemas: MutateCiCaseClaimRequest: type: object properties: runnerId: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$ generation: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 expectedVersion: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - runnerId - generation - expectedVersion additionalProperties: false StartCiCaseClaimResponse: type: object properties: claim: type: object properties: schemaVersion: type: number enum: - 1 claimId: type: string pattern: ^iclaim_[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}$ hostedRunId: type: string pattern: ^hrun_[0-9a-z]{12,32}$ interactionId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ expectedRunRevision: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 runnerId: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$ simulationWorkId: type: string pattern: ^simwork_[0-9a-z]{12,32}$ generation: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 state: type: string enum: - reserved - started - submitted - expired - uncertain - cancelled createdAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 updatedAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 expiresAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 startedAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 finishedAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 completionOperationId: type: string pattern: ^op_[0-9a-z]{12,32}$ required: - schemaVersion - claimId - organizationId - projectId - hostedRunId - interactionId - expectedRunRevision - runnerId - generation - version - state - createdAtMs - updatedAtMs - expiresAtMs additionalProperties: false replayed: type: boolean binding: type: object properties: schemaVersion: type: number enum: - 1 sessionId: type: string pattern: ^ses_[0-9a-z]{12,32}$ environmentId: type: string pattern: ^env_[0-9a-z]{12,32}$ buildHash: type: string pattern: ^sha256:[0-9a-f]{64}$ actorId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ actorInstanceId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ hostedRunId: type: string pattern: ^hrun_[0-9a-z]{12,32}$ interactionId: type: string minLength: 1 maxLength: 96 pattern: ^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$ interactionClaim: type: object properties: claimId: type: string pattern: ^iclaim_[0-9a-z]{12,32}$ generation: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 runRevision: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 required: - claimId - generation - runRevision additionalProperties: false callbackReceiverBindingId: type: string pattern: ^cbr_[0-9a-z]{12,32}$ worldHttpUrl: type: string format: uri worldWireHttpUrl: type: string format: uri worldWireAuthorizationHeader: type: string enum: - X-Firedrill-World-Authorization worldMcpUrl: type: string format: uri credential: type: string minLength: 32 expiresAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 capabilities: minItems: 1 type: array items: 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 required: - schemaVersion - sessionId - environmentId - buildHash - actorId - worldHttpUrl - credential - expiresAtMs - capabilities additionalProperties: false required: - claim - replayed 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 securitySchemes: controlCredential: type: http scheme: bearer description: Opaque control credential ````