openapi: 3.0.1
info:
  title: Flightcontrol Management API
  description: >-
    Specification of the documented Flightcontrol HTTP API. Flightcontrol deploys
    applications to your own AWS account. This API lets you integrate Flightcontrol
    with CI/CD and automation - trigger deployments via deploy hooks, read deployment
    status, create and edit environments, list services, set environment variables,
    update service scaling, run scheduler jobs, and invalidate CloudFront caches.
  termsOfService: https://www.flightcontrol.dev/legal/terms
  contact:
    name: Flightcontrol Support
    url: https://www.flightcontrol.dev/docs
  version: '1.0'
servers:
  - url: https://api.flightcontrol.dev
    description: Authenticated management API (Bearer API key).
  - url: https://app.flightcontrol.dev
    description: Deploy hook endpoints (secret embedded in path).
security:
  - bearerAuth: []
paths:
  /v1/deployments/{deploymentId}:
    get:
      operationId: getDeployment
      tags:
        - Deployments
      summary: Get deployment
      description: >-
        Retrieve information and status for a deployment, including per-service
        deployment details. The deploymentId is returned when a deployment is
        triggered (for example via a deploy hook).
      parameters:
        - name: deploymentId
          in: path
          required: true
          description: The deployment identifier.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deployment'
        '401':
          description: Unauthorized
        '404':
          description: Deployment not found
  /v1/projects/{projectId}/environments:
    post:
      operationId: createEnvironment
      tags:
        - Environments
      summary: Create environment
      description: Create a new environment in a project.
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEnvironmentRequest'
      responses:
        '200':
          description: OK
        '401':
          description: Unauthorized
    patch:
      operationId: editEnvironment
      tags:
        - Environments
      summary: Edit environment
      description: Edit an existing environment in a project.
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEnvironmentRequest'
      responses:
        '200':
          description: OK
        '401':
          description: Unauthorized
  /v1/services:
    get:
      operationId: getServices
      tags:
        - Services
      summary: Get services
      description: List services with pagination and optional project/environment filters.
      parameters:
        - name: skip
          in: query
          schema:
            type: integer
            default: 0
        - name: take
          in: query
          schema:
            type: integer
            default: 25
            maximum: 100
        - name: projectId
          in: query
          schema:
            type: string
        - name: environmentId
          in: query
          schema:
            type: string
        - name: previewEnvironmentId
          in: query
          schema:
            type: string
        - name: type
          in: query
          schema:
            type: string
        - name: environmentType
          in: query
          schema:
            type: string
            enum:
              - standard
              - preview
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceList'
        '401':
          description: Unauthorized
  /v1/services/{serviceId}/scaling:
    post:
      operationId: updateScaling
      tags:
        - Services
      summary: Update service scaling
      description: >-
        Set, add, or remove the desired instance count for a service. Supported
        for web, private web, worker, and network server services.
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScalingRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScalingResponse'
        '401':
          description: Unauthorized
  /v1/environments/{environmentId}/env-variables:
    post:
      operationId: createEnvironmentEnvVariables
      tags:
        - Environment Variables
      summary: Create environment variables
      description: >-
        Set environment variables for an environment. Supports plain text values,
        FC-managed Parameter Store / Secrets Manager secrets, references to your
        existing Parameter Store / Secrets Manager entries, and values linked from
        other services.
      parameters:
        - name: environmentId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnvVariablesRequest'
      responses:
        '200':
          description: Completed synchronously
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvVariablesSyncResponse'
        '202':
          description: Accepted - FC-managed secrets are processing asynchronously
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvVariablesAsyncResponse'
        '401':
          description: Unauthorized
  /v1/services/{serviceId}/cloudfront/invalidation:
    post:
      operationId: createCloudFrontInvalidation
      tags:
        - CloudFront
      summary: Create CloudFront cache invalidation
      description: Invalidate one or more paths in a service's CloudFront distribution.
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvalidationRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidationResponse'
        '401':
          description: Unauthorized
  /v1/cloudfront/invalidation/{invalidationId}:
    get:
      operationId: getCloudFrontInvalidationStatus
      tags:
        - CloudFront
      summary: Get CloudFront invalidation status
      description: Check the status of a previously created CloudFront cache invalidation.
      parameters:
        - name: invalidationId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
        '401':
          description: Unauthorized
        '404':
          description: Invalidation not found
  /api/deploy-hook/{envId}/{secret}:
    get:
      operationId: triggerDeployHook
      tags:
        - Deploy Hooks
      summary: Trigger deployment (deploy hook)
      description: >-
        Trigger a deployment for a normal environment. Authentication is provided
        by the secret embedded in the path; no Authorization header is used. Returns
        the new deploymentId.
      security: []
      servers:
        - url: https://app.flightcontrol.dev
      parameters:
        - name: envId
          in: path
          required: true
          schema:
            type: integer
        - name: secret
          in: path
          required: true
          schema:
            type: string
        - name: commit
          in: query
          description: Specific git commit SHA to deploy.
          schema:
            type: string
        - name: branch
          in: query
          description: Repository branch (required if commit is specified).
          schema:
            type: string
        - name: force
          in: query
          description: Deploy all services, ignoring watchPaths.
          schema:
            type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeployHookResponse'
  /api/deploy-hook/{previewEnvId}/{secret}/{prNumber}/{commitSHA}:
    get:
      operationId: triggerPreviewDeployHook
      tags:
        - Deploy Hooks
      summary: Trigger preview deployment (deploy hook)
      description: >-
        Trigger a deployment for a preview environment. Authentication is provided
        by the secret embedded in the path. Returns the new deploymentId.
      security: []
      servers:
        - url: https://app.flightcontrol.dev
      parameters:
        - name: previewEnvId
          in: path
          required: true
          schema:
            type: integer
        - name: secret
          in: path
          required: true
          schema:
            type: string
        - name: prNumber
          in: path
          required: true
          schema:
            type: integer
        - name: commitSHA
          in: path
          required: true
          schema:
            type: string
        - name: force
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeployHookResponse'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Flightcontrol API key passed as a Bearer token in the Authorization header.
  schemas:
    Deployment:
      type: object
      properties:
        deploymentId:
          type: string
        projectId:
          type: string
        environmentId:
          type: string
        environmentGivenId:
          type: string
        isPreviewEnvironment:
          type: boolean
        createdAt:
          type: string
          format: date-time
        repoUrl:
          type: string
        gitCommit:
          type: string
        gitBranch:
          type: string
        status:
          type: string
          description: >-
            Stage or final status, e.g. PENDING, INPROGRESS, BUILDING, DEPLOYING,
            SUCCESS, ERROR, BUILD_ERROR.
        serviceDeployments:
          type: array
          items:
            type: object
    CreateEnvironmentRequest:
      type: object
      required:
        - name
        - region
      properties:
        name:
          type: string
        region:
          type: string
        source:
          type: object
          properties:
            branch:
              type: string
            trigger:
              type: string
              enum:
                - push
                - manual
        services:
          type: array
          items:
            type: object
        vpc:
          type: object
          properties:
            id:
              type: string
            cidr:
              type: string
            private:
              type: boolean
        envVariables:
          type: object
          additionalProperties:
            type: string
    ServiceList:
      type: object
      properties:
        count:
          type: integer
        hasMore:
          type: boolean
        hasPrevious:
          type: boolean
        nextPage:
          type: integer
        previousPage:
          type: integer
        pageCount:
          type: integer
        pageSize:
          type: integer
        services:
          type: array
          items:
            $ref: '#/components/schemas/Service'
    Service:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        givenId:
          type: string
        type:
          type: string
        environmentId:
          type: string
        projectId:
          type: string
        previewEnvironmentId:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ScalingRequest:
      type: object
      required:
        - operation
        - count
      properties:
        operation:
          type: string
          enum:
            - set
            - add
            - remove
        count:
          type: integer
    ScalingResponse:
      type: object
      properties:
        serviceId:
          type: string
        previousDesiredCount:
          type: integer
        newDesiredCount:
          type: integer
        autoscalingEnabled:
          type: boolean
    EnvVariablesRequest:
      type: object
      properties:
        plainText:
          type: object
          additionalProperties:
            type: string
        parameterStore:
          type: object
          additionalProperties:
            type: string
        secretsManager:
          type: object
          additionalProperties:
            type: string
        fromParameterStore:
          type: object
          additionalProperties:
            type: string
        fromSecretsManager:
          type: object
          additionalProperties:
            type: string
        fromService:
          type: object
          additionalProperties:
            type: string
    EnvVariablesSyncResponse:
      type: object
      properties:
        status:
          type: string
          example: completed
        savedCount:
          type: integer
    EnvVariablesAsyncResponse:
      type: object
      properties:
        status:
          type: string
          example: processing
        runId:
          type: string
        savedCount:
          type: integer
        processingCount:
          type: integer
    InvalidationRequest:
      type: object
      required:
        - paths
      properties:
        paths:
          type: array
          items:
            type: string
          example:
            - /*
    InvalidationResponse:
      type: object
      properties:
        message:
          type: string
        invalidationId:
          type: string
    DeployHookResponse:
      type: object
      properties:
        success:
          type: string
          example: 'true'
        deploymentId:
          type: string
          example: clcpcxekt000lc9ojqtgtc26y