> ## Documentation Index
> Fetch the complete documentation index at: https://getfloo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Preflight

> Compute the preflight plan for declared state against deployed state.

Read-only. Returns a PreflightPlan describing every action deploy would
take (provision) and every orphan that would remain (destruction requires
explicit CLI command).



## OpenAPI

````yaml https://api.getfloo.com/openapi.json post /v1/apps/{app_id}/preflight
openapi: 3.1.0
info:
  title: floo API
  version: 0.1.0
servers:
  - url: https://api.getfloo.com
security: []
paths:
  /v1/apps/{app_id}/preflight:
    post:
      tags:
        - preflight
      summary: Run Preflight
      description: >-
        Compute the preflight plan for declared state against deployed state.


        Read-only. Returns a PreflightPlan describing every action deploy would

        take (provision) and every orphan that would remain (destruction
        requires

        explicit CLI command).
      operationId: preflight_run_preflight
      parameters:
        - name: app_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: App Id
        - $ref: '#/components/parameters/X-Floo-Org-Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeclaredState'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreflightPlan'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  parameters:
    X-Floo-Org-Id:
      name: X-Floo-Org-Id
      in: header
      required: false
      schema:
        type: string
        format: uuid
      description: Organization to act in; defaults to the one joined most recently.
  schemas:
    DeclaredState:
      properties:
        managed_services:
          items:
            $ref: '#/components/schemas/DeclaredManagedService'
          type: array
          title: Managed Services
        env:
          $ref: '#/components/schemas/EnvironmentName'
          default: dev
        services:
          items:
            $ref: '#/components/schemas/DeclaredRuntimeService'
          type: array
          title: Services
      additionalProperties: false
      type: object
      title: DeclaredState
      description: >-
        Payload the CLI sends to POST /v1/apps/{app_id}/preflight.


        Strict field validation: a misspelled field from a CLI/API version skew

        must fail loud (422) rather than silently route the user into a bad
        plan.
    PreflightPlan:
      properties:
        managed_services:
          $ref: '#/components/schemas/ManagedServicesPlan'
        runtime_services:
          items:
            $ref: '#/components/schemas/PreflightRuntimeService'
          type: array
          title: Runtime Services
        scheduled_deprovisions:
          items:
            $ref: '#/components/schemas/ScheduledDeprovisionItem'
          type: array
          title: Scheduled Deprovisions
        summary:
          $ref: '#/components/schemas/PlanSummary'
        destructive:
          type: boolean
          title: Destructive
          default: false
        data_loss:
          type: boolean
          title: Data Loss
          default: false
      additionalProperties: false
      type: object
      title: PreflightPlan
      description: |-
        Top-level preflight plan.

        Additional domain plans (services, env vars, routes, crons, domains) are
        added as the planner grows. The shape is deliberately additive, with new
        fields defaulting to empty plans so existing consumers keep working.

        `destructive` is true iff acting on this plan would modify or destroy
        existing state. Pure provisioning is additive and not destructive.
        `scheduled_deprovisions` is a sibling status readout, not an action bin.
    ErrorResponse:
      properties:
        detail:
          $ref: '#/components/schemas/ErrorDetail'
      type: object
      required:
        - detail
      title: ErrorResponse
      description: Body of every error response except request validation (422).
    DeclaredManagedService:
      properties:
        type:
          $ref: '#/components/schemas/ManagedServiceType'
        name:
          type: string
          pattern: ^[a-z][a-z0-9_]{0,62}$
          title: Name
          default: default
        tier:
          anyOf:
            - type: string
              maxLength: 20
            - type: 'null'
          title: Tier
      additionalProperties: false
      type: object
      required:
        - type
      title: DeclaredManagedService
      description: >-
        Managed service as declared by the caller.


        Sourced from either the legacy floo.app.toml sections (during the
        deprecation

        window) or from explicit managed-service add/migrate records (the
        canonical

        surface going forward).
    EnvironmentName:
      type: string
      enum:
        - dev
        - prod
        - preview
      title: EnvironmentName
      description: >-
        Enumerate the persisted development, production, and preview environment
        names.
    DeclaredRuntimeService:
      properties:
        name:
          type: string
          maxLength: 63
          minLength: 1
          title: Name
        type:
          type: string
          enum:
            - web
            - api
            - worker
          title: Type
        cpu:
          anyOf:
            - type: string
            - type: 'null'
          title: Cpu
        memory:
          anyOf:
            - type: string
            - type: 'null'
          title: Memory
        min_instances:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Min Instances
        max_instances:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Max Instances
        instances:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Instances
        env_managed:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Env Managed
      additionalProperties: false
      type: object
      required:
        - name
        - type
      title: DeclaredRuntimeService
      description: >-
        Runtime intent needed for authoritative server-side preflight
        resolution.
    ManagedServicesPlan:
      properties:
        to_provision:
          items:
            $ref: '#/components/schemas/ManagedServicePlanItem'
          type: array
          title: To Provision
        to_retry:
          items:
            $ref: '#/components/schemas/ManagedServicePlanItem'
          type: array
          title: To Retry
        to_retain:
          items:
            $ref: '#/components/schemas/ManagedServicePlanItem'
          type: array
          title: To Retain
        to_orphan:
          items:
            $ref: '#/components/schemas/ManagedServicePlanItem'
          type: array
          title: To Orphan
        to_deprovision:
          items:
            $ref: '#/components/schemas/ManagedServicePlanItem'
          type: array
          title: To Deprovision
        in_flight_deprovisioning:
          items:
            $ref: '#/components/schemas/ManagedServicePlanItem'
          type: array
          title: In Flight Deprovisioning
      additionalProperties: false
      type: object
      title: ManagedServicesPlan
      description: >-
        Reconciliation plan for managed services (postgres, redis, storage).


        Managed services are stateful and CLI-canonical. Deploy creates
        to_provision,

        retries to_retry (FAILED rows that the user has redeclared), retains

        to_retain, and NEVER acts on to_orphan — orphans require explicit

        removal. Rows currently being deprovisioned surface in

        in_flight_deprovisioning so they remain visible to operators instead of

        silently disappearing from the plan.
    PreflightRuntimeService:
      properties:
        name:
          type: string
          title: Name
        runtime_plan:
          $ref: '#/components/schemas/PreflightRuntimePlan'
        generated_env_keys:
          items:
            type: string
          type: array
          title: Generated Env Keys
      additionalProperties: false
      type: object
      required:
        - name
        - runtime_plan
      title: PreflightRuntimeService
      description: >-
        Pair a strictly shaped service runtime plan with generated environment
        key names.
    ScheduledDeprovisionItem:
      properties:
        type:
          $ref: '#/components/schemas/ManagedServiceType'
        name:
          type: string
          maxLength: 63
          title: Name
        managed_service_id:
          type: string
          format: uuid
          title: Managed Service Id
        dev_deprovision_after:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Dev Deprovision After
        prod_deprovision_after:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Prod Deprovision After
      additionalProperties: false
      type: object
      required:
        - type
        - name
        - managed_service_id
      title: ScheduledDeprovisionItem
      description: >-
        A managed service with a live teardown clock (epic #817/#824).


        A status readout, not a reconciliation action: it surfaces every pending

        auto-teardown and its per-env deadline so operators and agents can see a

        countdown that is already running — independent of whether the service
        is

        re-declared in this deploy. The gating decision already happened when
        the

        removal was first declared (an undeclared row also appears in

        ``managed_services.to_deprovision``); this view adds only the *when*. A

        teardown is rescinded by re-declaring the service in floo.app.toml
        before

        the clock elapses.
    PlanSummary:
      properties:
        action_count:
          type: integer
          title: Action Count
          default: 0
        destructive_count:
          type: integer
          title: Destructive Count
          default: 0
        estimated_duration_seconds:
          anyOf:
            - type: integer
            - type: 'null'
          title: Estimated Duration Seconds
      additionalProperties: false
      type: object
      title: PlanSummary
      description: Aggregate counts and risk flags for a preflight plan.
    ErrorDetail:
      properties:
        code:
          type: string
          title: Code
        message:
          type: string
          title: Message
      additionalProperties: true
      type: object
      required:
        - code
        - message
      title: ErrorDetail
      description: Standard error envelope with operation-specific JSON context.
    ManagedServiceType:
      type: string
      enum:
        - postgres
        - redis
        - storage
      title: ManagedServiceType
      description: Type of managed infrastructure service.
    ManagedServicePlanItem:
      properties:
        type:
          $ref: '#/components/schemas/ManagedServiceType'
        name:
          type: string
          maxLength: 63
          title: Name
        tier:
          anyOf:
            - type: string
              maxLength: 20
            - type: 'null'
          title: Tier
        managed_service_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Managed Service Id
        risk:
          $ref: '#/components/schemas/OpRisk'
          description: Machine-readable risk of the action this plan item represents.
        data_impact:
          anyOf:
            - type: string
            - type: 'null'
          title: Data Impact
          description: >-
            Human-readable description of what would be destroyed if this item
            were deprovisioned. Populated for to_orphan items only.
      additionalProperties: false
      type: object
      required:
        - type
        - name
        - risk
      title: ManagedServicePlanItem
      description: One managed-service row in a preflight plan.
    PreflightRuntimePlan:
      properties:
        env:
          anyOf:
            - type: string
            - type: 'null'
          title: Env
        service_type:
          type: string
          title: Service Type
        availability:
          type: string
          title: Availability
        declared:
          $ref: '#/components/schemas/PreflightRuntimeValues'
        effective:
          $ref: '#/components/schemas/PreflightRuntimeValues'
        sources:
          $ref: '#/components/schemas/PreflightRuntimeSources'
        components:
          items:
            $ref: '#/components/schemas/PreflightRuntimeComponent'
          type: array
          title: Components
        instance_total:
          $ref: '#/components/schemas/PreflightRuntimeInstanceTotal'
        cpu_allocation:
          type: string
          title: Cpu Allocation
        cpu_allocation_reason:
          type: string
          title: Cpu Allocation Reason
        warnings:
          items:
            type: string
          type: array
          title: Warnings
      type: object
      required:
        - env
        - service_type
        - availability
        - declared
        - effective
        - sources
        - components
        - instance_total
        - cpu_allocation
        - cpu_allocation_reason
        - warnings
      title: PreflightRuntimePlan
      description: Server-resolved runtime posture for a declared service.
    OpRisk:
      properties:
        tier:
          $ref: '#/components/schemas/RiskTier'
        destructive:
          type: boolean
          title: Destructive
          description: Report whether the risk tier is at least recoverably destructive.
          readOnly: true
        data_loss:
          type: boolean
          title: Data Loss
          description: Report whether the risk tier reaches the data-loss threshold.
          readOnly: true
      type: object
      required:
        - tier
        - destructive
        - data_loss
      title: OpRisk
      description: >-
        Machine-readable risk of one plan operation.


        Only ``tier`` is stored; ``destructive`` and ``data_loss`` are computed
        from

        it, so the three can never drift. The computed fields still serialize,
        so

        consumers — the guardrail policy and the approval gates — read one
        source of

        truth on the wire.


        ``extra="ignore"`` (not "forbid"): the emitted JSON carries the computed

        destructive/data_loss keys, so the model must accept its own output on
        input

        — those keys are ignored and recomputed from ``tier``, never stored, so
        an

        inconsistent risk still cannot survive a round-trip.
    PreflightRuntimeValues:
      properties:
        cpu:
          anyOf:
            - type: string
            - type: 'null'
          title: Cpu
        memory:
          anyOf:
            - type: string
            - type: 'null'
          title: Memory
        min_instances:
          anyOf:
            - type: integer
            - type: 'null'
          title: Min Instances
        max_instances:
          anyOf:
            - type: integer
            - type: 'null'
          title: Max Instances
        instances:
          anyOf:
            - type: integer
            - type: 'null'
          title: Instances
      type: object
      required:
        - cpu
        - memory
        - min_instances
        - max_instances
        - instances
      title: PreflightRuntimeValues
      description: >-
        Expose nullable requested or resolved runtime resource values during
        preflight.
    PreflightRuntimeSources:
      properties:
        cpu:
          anyOf:
            - type: string
            - type: 'null'
          title: Cpu
        memory:
          anyOf:
            - type: string
            - type: 'null'
          title: Memory
        min_instances:
          anyOf:
            - type: string
            - type: 'null'
          title: Min Instances
        max_instances:
          anyOf:
            - type: string
            - type: 'null'
          title: Max Instances
        instances:
          anyOf:
            - type: string
            - type: 'null'
          title: Instances
      type: object
      required:
        - cpu
        - memory
        - min_instances
        - max_instances
        - instances
      title: PreflightRuntimeSources
      description: Record the origin of each nullable preflight runtime setting.
    PreflightRuntimeComponent:
      properties:
        name:
          type: string
          title: Name
        cpu:
          type: string
          title: Cpu
        memory:
          type: string
          title: Memory
        source:
          type: string
          title: Source
      type: object
      required:
        - name
        - cpu
        - memory
        - source
      title: PreflightRuntimeComponent
      description: >-
        Describe one preflight runtime component's resource allocation and
        origin.
    PreflightRuntimeInstanceTotal:
      properties:
        cpu:
          type: string
          title: Cpu
        memory:
          type: string
          title: Memory
      type: object
      required:
        - cpu
        - memory
      title: PreflightRuntimeInstanceTotal
      description: Expose aggregate CPU and memory for one preflight instance.
    RiskTier:
      type: integer
      enum:
        - 1
        - 2
        - 3
      title: RiskTier
      description: >-
        Risk tier of a single plan operation.


        Mirrors the CLI destructive-command tier contract
        (floo-cli/src/confirm.rs)

        and the State and Audit Doctrine confirmation tiers. The tier is the
        single

        source of truth — destructive/data_loss are computed from it

        (see OpRisk.destructive / OpRisk.data_loss).
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: A `floo_` API key.

````

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