> ## 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.

# Extend an active Tool lifetime

> Requires `services:control` for an owned reusable instance and exact current epoch. Compare-and-set against exact expectedExpiresAt. Does not resume compute, renew connections or revive an ended instance.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/service-instances/{instanceId}/extend
openapi: 3.1.0
info:
  title: Firedrill API
  version: '2026-10-14'
  description: >-
    Authenticated simulation coordination, retained evidence and controlled
    Tools. Your customer-owned runner executes the target. This reference covers
    the documented JSON workflows; Tool-native HTTP routes and MCP methods are
    discovered from the selected Tool. Structural schemas do not replace
    canonical validation or capability checks.
servers:
  - url: https://api.firedrill.run
security:
  - FiredrillCredential: []
tags:
  - name: discovery
    description: Capabilities, authority and structural authoring schemas.
  - name: projects
    description: Projects and their logical environment.
  - name: simulations
    description: Preparation, queued batches and cancellation.
  - name: runs
    description: Individual recorded executions.
  - name: reports
    description: Retained observations, distributions and descriptive comparisons.
  - name: assessment
    description: Optional semantic assessment and authored scenario ranking.
  - name: evidence
    description: Authenticated captured files.
  - name: runner-protocol
    description: Advanced customer-runner coordination; native SDKs manage this protocol.
  - name: scenarios
    description: Immutable retained versions of repository-authored scenarios.
  - name: credentials
    description: Expiring scoped CI credentials.
  - name: authentication
    description: Human-approved sign-in boundaries.
  - name: tools
    description: Tool releases, data, instances and observations.
  - name: tool-connections
    description: Bounded target/manual grants, separate from control authority.
  - name: tool-lifecycle
    description: Epoch-fenced reusable Tool actions and exact-key recovery.
paths:
  /v1/service-instances/{instanceId}/extend:
    post:
      tags:
        - tool-lifecycle
      summary: Extend an active Tool lifetime
      description: >-
        Requires `services:control` for an owned reusable instance and exact
        current epoch. Compare-and-set against exact expectedExpiresAt. Does not
        resume compute, renew connections or revive an ended instance.
      operationId: tools_extend
      parameters:
        - name: instanceId
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 160
        - name: projectId
          in: query
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 160
        - name: environmentId
          in: query
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 160
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtendInput'
      responses:
        '200':
          description: The retained resource or operation response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceAction'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '410':
          $ref: '#/components/responses/Gone'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/InvalidInput'
        '429':
          $ref: '#/components/responses/Capacity'
        '500':
          $ref: '#/components/responses/Internal'
        '503':
          $ref: '#/components/responses/Unavailable'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: >-
        Save a unique stable key for this exact logical action, at most 200
        characters. Reuse it with identical input after an uncertain response. A
        new key is new intent; it must not be used merely to recover an accepted
        action.
      schema:
        type: string
        minLength: 1
        maxLength: 200
  schemas:
    ExtendInput:
      type: object
      properties:
        epoch:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        expectedExpiresAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        expiresAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
      required:
        - epoch
        - expectedExpiresAt
        - expiresAt
      additionalProperties: false
    ServiceAction:
      type: object
      properties:
        operationId:
          type: string
        instance:
          $ref: '#/components/schemas/ServiceInstance'
        result:
          $ref: '#/components/schemas/JsonValue'
      required:
        - operationId
        - instance
        - result
    ServiceInstance:
      type: object
      properties:
        id:
          type: string
        projectId:
          type: string
        environmentId:
          type: string
        buildId:
          type: string
        datasetId:
          anyOf:
            - type: 'null'
            - type: string
        epoch:
          type: number
        status:
          type: string
        createdAt:
          type: string
        expiresAt:
          type: string
        finishedAt:
          anyOf:
            - type: 'null'
            - type: string
        seed:
          type: string
        actorOperations:
          type: array
          items:
            type: string
        runtime:
          $ref: '#/components/schemas/JsonValue'
        invocationPolicy:
          type: string
          enum:
            - creating_credential_only
            - creating_member_or_credential_only
            - current_run_connection_only
        service:
          anyOf:
            - type: object
              properties:
                id:
                  type: string
                version:
                  type: string
                name:
                  type: 'null'
                httpRoutes:
                  type: array
                  items:
                    type: object
                    properties:
                      method:
                        type: string
                      path:
                        type: string
                      operationId:
                        type: string
                    required:
                      - method
                      - path
                      - operationId
                view:
                  type: object
                  properties:
                    declared:
                      type: boolean
                    available:
                      type: boolean
                    title:
                      anyOf:
                        - type: 'null'
                        - type: string
                    operationIds:
                      type: array
                      items:
                        type: string
                    readOnly:
                      anyOf:
                        - type: boolean
                          const: false
                        - type: boolean
                          const: true
                  required:
                    - declared
                    - available
                    - title
                    - operationIds
              required:
                - id
                - version
                - name
                - httpRoutes
                - view
      required:
        - id
        - projectId
        - environmentId
        - buildId
        - datasetId
        - epoch
        - status
        - createdAt
        - expiresAt
        - finishedAt
        - seed
        - actorOperations
        - runtime
        - invocationPolicy
    JsonValue:
      description: >-
        Any JSON value: null, boolean, finite number, string, array or object.
        The request transport must contain valid JSON; canonical validation
        rejects nonfinite numbers.
    ApiError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            repair:
              type: string
            requestId:
              type: string
            details:
              anyOf:
                - type: 'null'
                - type: string
                - type: number
                - type: boolean
                  const: false
                - type: boolean
                  const: true
                - type: array
                  items:
                    $ref: '#/components/schemas/JsonValue'
                - type: object
                  properties: {}
                  required: []
                  additionalProperties:
                    $ref: '#/components/schemas/JsonValue'
            validation:
              anyOf:
                - $ref: '#/components/schemas/ValidationDiagnostics'
          required:
            - code
            - message
            - repair
            - requestId
      required:
        - error
    ValidationDiagnostics:
      type: object
      properties:
        issues:
          type: array
          items:
            $ref: '#/components/schemas/ValidationIssue'
        totalIssues:
          type: number
        omittedIssues:
          type: number
      required:
        - issues
        - totalIssues
        - omittedIssues
    ValidationIssue:
      type: object
      properties:
        path:
          type: array
          items:
            anyOf:
              - type: string
              - type: number
        code:
          type: string
        message:
          type: string
        pathTruncated:
          anyOf:
            - type: boolean
              const: true
      required:
        - path
        - code
        - message
  responses:
    BadRequest:
      description: >-
        Malformed request or missing operation key. Repair the input before
        retrying.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Unauthorized:
      description: >-
        Missing, expired or revoked authority. Complete supported sign-in or use
        an authorized credential.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Forbidden:
      description: >-
        The current capability, actor, audience or ownership grant does not
        allow this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    NotFound:
      description: The exact resource is unavailable under the current authority and scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Conflict:
      description: >-
        Selected context, epoch, revision, lease or saved operation intent
        conflicts; inspect retained state.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Gone:
      description: >-
        Retained content is expired, deleted or unavailable under its retention
        fence. Metadata is not a replacement payload.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    PayloadTooLarge:
      description: >-
        Request, response or retained-resource size exceeds this operation’s
        enforced bound.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    UnsupportedMediaType:
      description: Send the documented JSON or exact artifact media type.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    InvalidInput:
      description: >-
        Input failed canonical validation. Inspect error.validation and repair
        the indicated fields.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Capacity:
      description: >-
        Bounded capacity or resource admission rejected the operation. Inspect
        retained work before retrying.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Internal:
      description: >-
        The service could not complete the request. Inspect retained state
        before exact-key recovery.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Unavailable:
      description: >-
        A required service, provider or authority check is unavailable. Existing
        evidence remains separate from this failure.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  securitySchemes:
    FiredrillCredential:
      type: http
      scheme: bearer
      description: >-
        Opaque Firedrill interactive or scoped machine credential. The CLI
        handles human-approved login; CI stores its scoped credential as
        FIREDRILL_TOKEN. Capabilities and project/environment ownership are
        rechecked at use.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.