# The FlyWP Public API, described.
#
# Hand-written, and kept honest by `OpenApiDriftTest`: every path and method in
# here has to resolve to a registered `api.v1.*` route, and every one of those
# routes has to appear in here. Adding an endpoint without documenting it fails
# the suite, and so does documenting one that does not exist.
#
# Path parameters are spelled the way the router spells them — `{server}`, not
# `{server_id}` — so the two can be compared as plain strings. A translation
# table between the document and the router is exactly the sort of place drift
# hides.
#
# This file is the source the `flywp-api-doc` site renders (phase 015). It is not
# generated: adding a generator would mean a new dependency, and the drift test
# buys the same guarantee for none.
openapi: 3.1.0

info:
  title: FlyWP API
  description: |
    Manage servers and WordPress sites on FlyWP.

    ## Authentication

    Send a personal access token as a bearer token:

    ```
    Authorization: Bearer <token>
    ```

    Tokens are minted in the dashboard under Team settings → API Tokens. Minting
    one requires two-factor authentication and a fresh password or passkey
    confirmation. An expiry date is optional; without one, the token does not
    expire. A passkey alone
    does not qualify: it satisfies the confirmation but not the two-factor
    requirement. A token can never hold a permission its minter does not, on
    any team it names.

    ## Permissions

    A token carries a list of permissions chosen when it was minted, and every
    endpoint asks for one of them. Asking for a permission the token does not
    hold is a `403`.

    | Permission | What it reaches |
    | --- | --- |
    | `server:list` | `GET /v1/servers`, `GET /v1/servers/{server}` |
    | `server:create` | `POST /v1/servers` |
    | `server:update` | `PUT`/`PATCH /v1/servers/{server}`, `POST /v1/servers/{server}/monitoring-agent`, `PUT`/`DELETE /v1/servers/{server}/alert-thresholds` |
    | `server:delete` | `DELETE /v1/servers/{server}` |
    | `server:scale` | `GET /v1/servers/{server}/scale-options`, `POST /v1/servers/{server}/scales`, `GET /v1/servers/{server}/scales/{scale}` |
    | `server:status` | `GET /v1/servers/{server}/metrics`, `GET /v1/servers/{server}/alert-thresholds` |
    | `server:keys:list` | `GET /v1/servers/{server}/ssh-keys` |
    | `server:keys:create` | `POST /v1/servers/{server}/ssh-keys` |
    | `server:keys:delete` | `DELETE /v1/servers/{server}/ssh-keys/{sshKey}` — your own keys |
    | `server:keys:delete-others` | the same, for a key somebody else added |
    | `site:list` | `GET /v1/sites`, `GET /v1/sites/{site}`, `GET /v1/sites/{site}/static-site`, `GET /v1/sites/{site}/static-site/deployments` and one deployment |
    | `site:create` | `POST /v1/sites` |
    | `site:delete` | `DELETE /v1/sites/{site}` |
    | `site:update` | everything else under a site |
    | `team:manage` | `include=team` and `include=creator`, `GET`/`PUT /v1/team/alert-thresholds` |

    `site:update` is worth reading twice. Every nested resource — domains,
    backups, certificates, nginx, OpenLiteSpeed, wp-config — is behind it,
    **including the reads**, and cloning a site is behind it too. That matches
    the dashboard, where the same pages ask the same permission. A read-only
    token holding `site:list` reaches the site itself and, as in the dashboard,
    the static site and its deploy history, without the deploy log.

    The mint page offers permissions the dashboard uses that no endpoint here
    reads yet — cron, daemons, firewall rules, supervisor and DNS. Ticking them
    changes nothing about this API.

    ## Choosing a team

    Every authenticated request must carry an `X-Team-Id` header naming the team
    it acts on. There is no default: a request that omits the header is a 422
    rather than acting on whichever team the token's owner last visited in the
    dashboard.

    ## Asynchronous work

    Anything that has to reach a server — creating a site, adding an SSH key,
    restoring a backup — answers `202 Accepted` with the record as it stands
    now. The work itself is queued. Poll the resource to see it finish.

    ## Rate limits

    Every request is metered against the token that made it: 60 a minute by
    default. `X-RateLimit-Limit` and `X-RateLimit-Remaining` come back on every
    response, and going over is a `429` with `Retry-After`.

    Creating a server or a site is capped by your plan, not by a second limit
    here. A create that answers `202` and is then lost on the wire is not
    replayable — poll the collection before retrying.

    ## Reading one record

    Servers and sites have a single-record endpoint. Domains, backups and
    certificates do not: list the collection and pick the record out of it. A
    write answers with the record it wrote, so a create does not need a follow-up
    read.

    ## Narrowing a listing

    `filter[...]`, `sort`, `fields[...]`, `per_page` and `cursor` are parameters
    of a **listing**. A single-record endpoint does not take them and ignores
    them if they are sent: it returns the whole record, every time.

    `include` is the exception and works on both.

    ## Browsers

    There is no CORS handling, deliberately. A request needs a bearer token, and
    a bearer token does not belong in a page anyone can view source on. Call this
    API from a server. A browser preflight answers `404` with no
    `Access-Control-Allow-Origin`.

    ## Errors

    Every failure is JSON, on every path, whatever the `Accept` header says:

    ```json
    { "message": "…" }
    ```

    A validation failure adds a field-keyed `errors` object and nothing else
    does.
  version: 1.0.0
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  contact:
    name: FlyWP Support
    url: https://flywp.com/support
    email: support@flywp.com

servers:
  - url: https://api.flywp.com
    description: Production

security:
  - bearerAuth: []

tags:
  - name: Getting Started
  - name: Authentication
  - name: Servers
  - name: Server SSH Keys
  - name: Server Scale
    description: |
      Change the plan of a server at its provider: more CPU and RAM, or more
      CPU, RAM and disk. A disk cannot shrink, so the disk mode cannot be
      undone. FlyWP scales servers on DigitalOcean, Vultr, Akamai and Hetzner
      only. Vultr offers only the disk mode, because a Vultr plan always brings
      its own disk. A team that holds White Label cannot scale its servers.

      The server is off while the provider changes the plan, usually for some
      minutes. While a scale runs, every change to the server and its sites is
      refused with `409`; reads still work.

      A managed server pays the difference for the rest of the current month
      when the scale starts (`charge_now_cents`). A scale that fails gives the
      charge back to the team wallet.
  - name: Server Monitoring
    description: |
      CPU, memory, disk and bandwidth, measured each minute by the FlyWP agent
      on the server, and what the agent reports about the server now: a
      pending reboot and the waiting updates. The same values as the Status
      page in the dashboard.

      A server shows nothing until the agent is installed on it.

      The alert limits decide when a value that stays high raises an alert:
      the server's own limits, else the team's. FlyWP sets no limits, so a
      server with no limit on raises no alert, also no "not reporting" alert.
  - name: Sites
  - name: Site Backups
  - name: Site Domains
  - name: Site Certificates
  - name: Site Deployments
    description: |
      Git deploys. A git site is built without its code: add the deploy key when GitHub refused
      it, set the `.env`, then start the first deploy.
  - name: Site Static Site
    description: |
      A static copy of a WordPress site on its own domain, for example
      `static.example.com`. WordPress stays on its own domain.

      - WordPress sites only. Any other application type answers `404`.
      - The reads need `site:list`. Every write, and the deploy log, need `site:update`.
      - A refusal because of the static site state is `409`, with a message you can show.
      - No response contains a credential.
  - name: Bulk Actions
  - name: White Label Plans
    description: |
      For a reseller's own billing system — WHMCS, WooCommerce, anything that
      already took the money. A White Label API key is minted in the dashboard
      under **White Label → API keys** and **names its own team**, so these
      endpoints take no `X-Team-Id` header.

      The key only answers while the reseller sells through their own billing
      system, which is a switch under **White Label → Channels**. Turned off,
      every endpoint here is a `403`.

      Once a reseller's own FlyWP subscription lapses, the writes here answer
      `409` and the reads stay open — and ending a customer or deleting a site
      keeps working, because stopping money must always work.

      Rate limit: 60 requests a minute per key.
  - name: White Label Customers
    description: |
      One customer of a reseller, as their billing system sees them: made active
      because the money was taken there, moved between plans, suspended when a
      renewal fails, and ended.
  - name: White Label Customer Sites
    description: |
      The WordPress sites a customer has. Creating one is accepted, not
      finished: poll until the site's `status` reaches `active`.
  - name: Compose Apps
    description: |
      Docker Compose Apps: an app from a compose file of the customer, or from a template of
      FlyWP. The id of an app is the id of its site.

      - The public API is off by default. Where it is off, each endpoint answers `503`.
      - Each endpoint needs a scope of the token: `compose:read`, `compose:deploy`,
        `compose:manage`, `compose:backups` or `compose:move` (a clone). The role of the person who made
        the token decides too: a token with the scope and no role for the action is refused.
      - No response contains the value of a secret setting: a refusal or a log hides each one.
      - A site of another type answers `404` here; a compose app answers `404` on the site endpoints, except `GET /v1/sites/{site_id}` (a token with the compose scopes alone gets `403` there).
      - A token can have the compose scopes alone, for example `compose:read` and `compose:deploy` for a CI pipeline.
      - The Free plan answers `402` to each change, except a stop, a backup and the delete.
      - A long action answers `202` with its reference: the number of the deploy (`GET .../deployments/{number}`), the `operation` of the app for a restart, stop or start, the backup row for a backup or a restore.
      - The limits for each hour count only the actions that started (`202`): a refusal does not use them.
  - name: White Label Fees
    description: |
      FlyWP's own fees on the reseller's sales, month by month, to reconcile.

  - name: Site Configuration
    description: |
      The nginx vhost, the OpenLiteSpeed files and the wp-config constants FlyWP
      manages. Each pair is gated on the site's own stack and answers `404` on
      the other one.

      All of these need the site to be awake. A sleeping site answers `409` to
      every one of them, reads included, which is what the dashboard does with
      the same pages — a sleeping site's containers are down, so a vhost written
      for it cannot be served.

      There is no endpoint that reads or writes `wp-config.php` itself, and there
      will not be: the file holds `FLYWP_API_KEY` and the database password.
      Seven named constants is what this surface offers.

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        A personal access token, minted under **Team settings → API Tokens**.
        Every endpoint using it also needs the `X-Team-Id` header.

    whiteLabelKey:
      type: http
      scheme: bearer
      description: |
        **A different key from the one above, and not interchangeable with it.**

        A White Label API key, minted under **White Label → API keys**. It is a
        bearer token like a personal access token, but:

        - It carries its own team, so `X-Team-Id` is neither needed nor read.
        - It opens the `/v1/white-label/*` endpoints and nothing else. On the
          rest of the API it is nobody.
        - A personal access token, conversely, is refused here with `403`.

  parameters:
    TeamId:
      name: X-Team-Id
      in: header
      required: true
      description: |
        The team this request acts on. Required on every authenticated endpoint.

        An integer, and checked as one: a value with anything else in it is a
        `422`. A well-formed id naming a team you do not belong to is a `404`,
        and a team your token was not minted for is a `403` — a token names
        exactly one team.
      schema:
        type: integer
      example: 123


    WhiteLabelClientId:
      name: client
      in: path
      required: true
      description: |
        FlyWP's own id for the customer, as returned on create. Another
        reseller's customer is a `404`, never a `403`: the id says nothing about
        anybody else.
      schema:
        type: integer
      example: 4821

    PerPage:
      name: per_page
      in: query
      required: false
      description: Page size. Values above 100 are clamped to 100.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10

    Cursor:
      name: cursor
      in: query
      required: false
      description: The `next_cursor` or `prev_cursor` from a previous page.
      schema:
        type: string

    Sort:
      name: sort
      in: query
      required: false
      description: |
        A comma-separated list of fields, each optionally prefixed with `-` for
        descending. Defaults to `-id`, newest first.
      schema:
        type: string
      example: -created_at

    Include:
      name: include
      in: query
      required: false
      description: |
        A comma-separated list of relationships to embed.

        On sites: `server`, `team`, `creator`. On servers: `team`, `sites`.

        Each one costs the permission that reads it, which is not always the
        permission that reads the endpoint. `server` and `sites` need
        `server:list` and `site:list`; `team` and `creator` need `team:manage`,
        because both carry a person's or a team's own details. An include a token
        may not have is left out of the response rather than refused, so the rest
        of the record still comes back.
      schema:
        type: string
      example: server

    ServerId:
      name: server
      in: path
      required: true
      schema:
        type: integer

    ServerScaleId:
      name: scale
      in: path
      required: true
      schema:
        type: integer

    SshKeyId:
      name: sshKey
      in: path
      required: true
      schema:
        type: integer

    ComposeSettingId:
      name: composeSetting
      in: path
      required: true
      description: The id of a setting (from the list of the settings).
      schema:
        type: integer
    ComposeDomainId:
      name: composeDomain
      in: path
      required: true
      description: The id of a domain (from the list of the domains).
      schema:
        type: integer
    ComposeDeploymentNumber:
      name: number
      in: path
      required: true
      description: The number of a deploy of the app (1, 2, 3 ...).
      schema:
        type: integer

    SiteId:
      name: site
      in: path
      required: true
      schema:
        type: integer

    BackupId:
      name: backup
      in: path
      required: true
      schema:
        type: integer

    DomainId:
      name: domain
      in: path
      required: true
      schema:
        type: integer

    CertificateId:
      name: certificate
      in: path
      required: true
      schema:
        type: integer

    StaticSiteDeploymentId:
      name: deployment
      in: path
      required: true
      schema:
        type: integer

    BulkActionId:
      name: bulkAction
      in: path
      required: true
      schema: { type: integer }

  schemas:
    Message:
      type: object
      description: A bare acknowledgement. Used where there is no resource to return.
      properties:
        message:
          type: string
      required: [message]

    Error:
      type: object
      properties:
        message:
          type: string
          description: Written for a person to read in a log. May be reworded; do not match on it.
          example: Your White Label subscription has ended, so nothing new can be created here.
        code:
          type: string
          description: |
            A stable token for the failure, on every error from the
            `/v1/white-label/*` endpoints. Branch on this rather than on
            `message`.

            Named refusals: `subscription_lapsed`, `byos_unpaid`, `fee_unpaid`,
            `fee_terms_not_accepted`, `plan_sold_out`,
            `customer_cap_reached`, `no_plans_published`, `pool_closed`,
            `site_already_deleting`, `site_in_progress`,
            `external_id_taken`, `customer_cancelled`, `wrong_key_type`,
            `key_orphaned`, `billing_role_required`, `no_white_label_access`,
            `channel_closed`.
            Everything else falls back to its status: `unauthenticated`,
            `forbidden`, `not_found`, `validation_failed`, `rate_limited`, and
            so on.
          example: subscription_lapsed
      required: [message]
      example:
        message: Your White Label subscription has ended, so nothing new can be created here.
        code: subscription_lapsed

    ValidationError:
      type: object
      properties:
        message:
          type: string
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
      required: [message, errors]

    CursorLinks:
      type: object
      properties:
        first:
          type: ['null', string]
        last:
          type: ['null', string]
        prev:
          type: ['null', string]
        next:
          type: ['null', string]

    CursorMeta:
      type: object
      properties:
        path:
          type: string
        per_page:
          type: integer
        next_cursor:
          type: ['null', string]
        prev_cursor:
          type: ['null', string]

    SiteTypeValue:
      type: string
      description: |
        The application type. This is every case of the `SiteType` enum, and a
        test asserts it stays that way — the endpoint accepted `wp` and
        `bedrock` alone for its whole life because the rules were written twice.

        `nextjs`, `nuxtjs` and `astro` are git-only, and each needs
        `package_manager`, `build_command` and `node_runtime` as well; a
        `server` runtime also needs `start_command`.

        `compose` is a Docker Compose App. A site of this type shows in the
        lists, but `POST /sites` does not make one and the site endpoints answer
        404 for it.
      enum:
        - wp
        - bedrock
        - php
        - laravel
        - symfony
        - nextjs
        - nuxtjs
        - astro
        - html
        - phpmyadmin
        - n8n
        - nextcloud
        - openwebui
        - mautic
        - vaultwarden
        - wireguard
        - umami
        - compose

    Server:
      type: object
      description: |
        On `GET /v1/servers`, a field is omitted rather than nulled when
        `fields[servers]` did not ask for it, so a client can tell "you did not
        request this" from "this is empty". `GET /v1/servers/{server}` always
        returns the whole record — see "Narrowing a listing". Provisioning
        credentials — the sudo, MySQL and Redis passwords — are never returned by
        any endpoint.

        What is here is what this surface can act on: an identifier, a field
        `PUT /v1/servers/{server}` writes, or the status a caller polls while a
        create finishes. The provider's own instance handle and the phpMyAdmin
        state are neither, and were removed in 008 — v1 has no endpoint for
        either, and the dashboard shows the second only behind `server:database`.
      properties:
        id: { type: integer }
        team_id: { type: integer }
        name: { type: string }
        os: { type: string }
        size: { type: string }
        ram: { type: ['null', integer], description: The RAM in MB. }
        cpu: { type: ['null', integer] }
        storage: { type: ['null', integer], description: The disk in GB. }
        architecture: { type: ['null', string] }
        region: { type: string }
        ip_address: { type: string }
        private_ip: { type: ['null', string] }
        ssh_port: { type: integer }
        docker_version: { type: ['null', string] }
        username: { type: string }
        status: { type: string }
        white_label_plan_id:
          type: ['null', integer]
          description: The White Label plan whose pool grew this server; null for the team's own.
        is_trial:
          type: boolean
          description: A free 48-hour FlyWP Managed trial server, not kept yet. Started and kept in the dashboard only.
        trial_ends_at:
          type: ['null', string]
          format: date-time
          description: When the trial ends; null unless is_trial. The server is removed 24 hours later unless it is kept.
        trial_removes_at:
          type: ['null', string]
          format: date-time
          description: |
            When FlyWP removes the server unless it is kept; null unless is_trial. FlyWP checks
            a trial server every 2 hours from the start. While the server has no site (a site
            that is still being created, or that failed, does not count), this is the next
            check, and the check removes the server. With a site, it is the end of the 24-hour
            grace after `trial_ends_at`.
        trial_stage:
          type: ['null', string]
          enum: [active, ending_soon, grace, null]
          description: |
            Where the trial is; null unless is_trial. `ending_soon` is the last 24 hours. In
            `grace` the server and its sites take no writes (403 `trial_locked`) until the
            server is kept or removed.
        white_label_plan_ids:
          type: array
          items: { type: integer }
          description: |
            Every White Label plan this server serves: the one whose pool grew it, and
            each plan the team runs on it as one of its own servers. Empty when none.
            Listed and shown only; with `fields[servers]`, only when both `id` and
            `white_label_plan_id` are asked for.
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    ServerMetrics:
      type: object
      properties:
        agent:
          type: object
          properties:
            installed_at:
              type: ['null', string]
              format: date-time
              description: Null while the agent is not installed.
            version: { type: ['null', string] }
            last_seen_at:
              type: ['null', string]
              format: date-time
              description: |
                The minute of the newest measurement. An old value means the
                agent stopped reporting.
        status:
          description: What the agent reported most recently. Null until the first report.
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/AgentStatus'
        series:
          description: Null while the agent is not installed.
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/MetricSeries'
        sites:
          description: |
            The use of each site, from the latest report. Only the sites that the
            token's user may see, and only with a key that has `site:list`. The
            shared services (MySQL, Redis, the proxy) come last, with `site_id`
            null. Null while the agent is not installed.
          type: ['null', array]
          items: { $ref: '#/components/schemas/SiteUsage' }

    AgentStatus:
      type: object
      properties:
        reboot_required: { type: boolean }
        updates_total: { type: ['null', integer], description: 'Null when the agent could not count the updates.' }
        updates_security: { type: ['null', integer], description: 'Null when the agent could not count the updates.' }
        os: { type: ['null', string] }
        kernel: { type: ['null', string] }
        uptime_seconds: { type: ['null', integer] }
        arch: { type: ['null', string], description: 'The CPU architecture of the agent, for example `amd64` or `arm64`.' }
        cpu_count: { type: ['null', integer], description: 'The CPUs that are online. Null for an agent before contract v0.5.0.' }
        docker_status: { type: ['null', string], description: '`running`, `not_running` or `not_installed`. Null when the agent cannot tell.' }
        docker_version: { type: ['null', string] }

    MetricSeries:
      type: object
      description: |
        `1h`, `6h` and `24h` come from the minute measurements, in steps of 1, 5
        and 15 minutes. `7d` comes from hourly summaries; its newest point can
        be up to 65 minutes old. A missing step is a gap, not a zero.
      properties:
        range: { type: string, enum: ['1h', '6h', '24h', '7d'] }
        step_seconds: { type: integer }
        latest:
          description: The newest measurement. Null before the first one.
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/MetricLatestSample'
        points:
          type: array
          items: { $ref: '#/components/schemas/MetricPoint' }

    SiteUsage:
      type: object
      description: The values are null when the agent did not measure the site.
      properties:
        site_id: { type: ['null', integer], description: 'Null for the shared services.' }
        name: { type: string, description: 'The primary domain of the site, or `Shared services`.' }
        cpu_percent: { type: ['null', number], description: 'A share of all the CPUs of the server.' }
        memory_used_bytes: { type: ['null', integer] }
        measured_at: { type: ['null', string], format: date-time }
        disk_used_bytes: { type: ['null', integer], description: 'The space that the files of the site take on the disk. Measured once an hour.' }
        disk_measured_at: { type: ['null', string], format: date-time }

    MetricLatestSample:
      type: object
      properties:
        recorded_at: { type: string, format: date-time, description: 'The minute, in UTC.' }
        load_1: { type: number, description: 'The 1-minute load average. Divide by `status.cpu_count` for the load per CPU.' }
        memory_used_bytes: { type: integer }
        memory_total_bytes: { type: integer }
        swap_used_bytes: { type: integer }
        swap_total_bytes: { type: integer }
        disk_used_bytes: { type: integer }
        disk_total_bytes: { type: integer }

    MetricPoint:
      type: object
      description: |
        One step. The average and the peak of the step; bandwidth and disk
        activity are the totals of the step, in bytes or operations.
        A peak is the highest 10-second value of the step. For an agent that
        does not measure within the minute, it is the highest minute value.
        The pressure and disk activity fields are null when the agent does
        not send them (an older agent, or a kernel with no pressure data).
      properties:
        at:
          type: string
          format: date-time
          description: The start of the step, in UTC.
        cpu_avg: { type: number }
        cpu_peak: { type: number }
        memory_used_avg: { type: integer }
        memory_used_peak: { type: integer }
        disk_used_avg: { type: integer }
        disk_used_peak: { type: integer }
        net_in_total: { type: integer }
        net_out_total: { type: integer }
        load_avg:
          type: ['null', number]
          description: The 1-minute load average of the server, not divided by its CPUs.
        load_peak: { type: ['null', number] }
        swap_used_avg: { type: ['null', integer] }
        swap_used_peak: { type: ['null', integer] }
        net_in_peak_bytes_per_second: { type: ['null', integer] }
        net_out_peak_bytes_per_second: { type: ['null', integer] }
        cpu_pressure_avg:
          type: ['null', number]
          description: Percent of the time in which a task waited for a CPU.
        cpu_pressure_peak: { type: ['null', number] }
        memory_pressure_avg:
          type: ['null', number]
          description: Percent of the time in which a task waited for memory.
        memory_pressure_peak: { type: ['null', number] }
        io_pressure_avg:
          type: ['null', number]
          description: Percent of the time in which a task waited for disk I/O.
        io_pressure_peak: { type: ['null', number] }
        disk_read_bytes_total: { type: ['null', integer] }
        disk_write_bytes_total: { type: ['null', integer] }
        disk_read_ops_total: { type: ['null', integer] }
        disk_write_ops_total: { type: ['null', integer] }
        disk_read_peak_bytes_per_second: { type: ['null', integer] }
        disk_write_peak_bytes_per_second: { type: ['null', integer] }
        disk_read_peak_ops_per_second: { type: ['null', integer] }
        disk_write_peak_ops_per_second: { type: ['null', integer] }
        disk_measured_minutes:
          type: ['null', integer]
          description: |
            The minutes of the step with disk activity. The disk totals cover only
            these minutes: a rate is the total divided by this value × 60.

    AlertThresholds:
      type: object
      description: |
        Alert limits, in percent, from 1 to 99. A value that stays above its
        limit for 30 minutes raises an alert. `null` switches that alert off.
        With every limit `null`, the server raises no alert, also no "not
        reporting" alert. A set replaces the one before
        it whole, so send every key; only `disk_critical_percent` may be absent.
      required: [cpu_percent, memory_percent, disk_percent]
      properties:
        cpu_percent: { type: ['null', integer], minimum: 1, maximum: 99 }
        memory_percent: { type: ['null', integer], minimum: 1, maximum: 99 }
        disk_percent:
          type: ['null', integer]
          minimum: 1
          maximum: 99
          description: The Disk Warning limit.
        disk_critical_percent:
          type: ['null', integer]
          minimum: 1
          maximum: 99
          description: |
            The Disk Critical limit. Must be higher than `disk_percent` when both
            are set. When the key is absent, it is 95, or `null` when
            `disk_percent` is 95 or more, or is `null`.

    AppliedAlertThresholds:
      description: The limits that apply now.
      allOf:
        - $ref: '#/components/schemas/AlertThresholds'
        - type: object
          properties:
            custom:
              type: boolean
              description: |
                For a server, true when it has its own limits; otherwise it
                uses the team's. For the team, true when it set its own limits;
                otherwise every limit is `null`.

    Site:
      type: object
      description: |
        `wp_config` and the site's own API key are deliberately absent. They hold
        `FLYWP_API_KEY`, and no endpoint on this surface returns them.
      properties:
        id: { type: integer }
        team_id: { type: integer }
        server_id: { type: integer }
        username: { type: string }
        domain: { type: string }
        status: { type: string }
        awaiting_first_deploy:
          type: boolean
          description: A git site is built without its code. True until its first deploy finishes.
        type: { $ref: '#/components/schemas/SiteTypeValue' }
        stack: { type: string }
        ssl_enabled: { type: boolean }
        php_version: { type: string }
        php_outdated:
          type: boolean
          description: True when the site runs a PHP version that gets no security fixes upstream (end-of-life). Always false for a site type that has no PHP. Present only when `php_version` and `type` are both in the response; it is not a `fields[sites]` value of its own.
        wp_version: { type: ['null', string] }
        white_label_client_id:
          type: ['null', integer]
          description: The customer the site belongs to on the White Label API (`/v1/white-label/customers/{id}`); null for the team's own. Filterable with `filter[white_label_client_id]`.
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        team: { type: object }
        creator: { type: object }
        server: { $ref: '#/components/schemas/Server' }

    SiteDeployment:
      type: object
      description: |
        One git deploy. `log` is only in the single read.
      properties:
        id: { type: integer }
        type: { type: string, enum: [manual, quick, custom, initial] }
        status: { type: string, enum: [deploying, finished, failed] }
        commit_branch: { type: ['null', string] }
        commit_hash: { type: ['null', string] }
        failed_step: { type: ['null', string] }
        total_time_taken: { type: ['null', integer] }
        deployer_id: { type: ['null', integer] }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        log: { type: ['null', string] }

    ServerScale:
      type: object
      properties:
        id: { type: integer }
        server_id: { type: integer }
        status:
          type: string
          enum: [pending, powering_off, resizing, powering_on, syncing, succeeded, failed, needs_attention]
          description: |
            `succeeded`, `failed` and `needs_attention` are final. `failed`: the
            server is on its old plan and on. `needs_attention`: FlyWP could not
            finish; the server can be off. Contact support.
        mode: { type: string, enum: [cpu_ram, cpu_ram_disk] }
        from_size: { type: string }
        to_size: { type: string }
        message: { type: ['null', string], description: 'Why the scale failed or needs attention.' }
        started_at: { type: string, format: date-time }
        completed_at: { type: ['null', string], format: date-time }

    ServerScaleOption:
      type: object
      properties:
        mode: { type: string, enum: [cpu_ram, cpu_ram_disk] }
        label: { type: string }
        grows_disk: { type: boolean }
        plans:
          type: array
          items:
            type: object
            properties:
              size: { type: string, description: 'The provider slug. Send it as `to_size`.' }
              cpu: { type: integer }
              memory: { type: string }
              disk: { type: string, description: 'The disk of the plan. In `cpu_ram` mode the server keeps its current disk.' }
              monthly: { type: number }
              hourly: { type: number }
              charge_now_cents:
                type: ['null', integer]
                description: 'Managed server: what FlyWP charges when the scale starts. Null for a server on your own provider account.'

    SshKey:
      type: object
      properties:
        id: { type: integer }
        server_id: { type: integer }
        name: { type: string }
        user: { type: string }
        status:
          type: string
          enum: [pending, active, deleting, failed]
          description: '`failed` means the key could not be added to the server. Delete it and add it again.'
        created_by: { type: ['null', integer] }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        server: { $ref: '#/components/schemas/Server' }

    Backup:
      type: object
      properties:
        id: { type: integer }
        site_id: { type: integer }
        server_id: { type: integer }
        integration_id: { type: ['null', integer] }
        type: { type: string }
        status: { type: string }
        is_restoring: { type: boolean }
        db_size: { type: ['null', integer] }
        file_size: { type: ['null', integer] }
        duration: { type: ['null', integer] }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        site: { $ref: '#/components/schemas/Site' }

    Domain:
      type: object
      properties:
        id: { type: integer }
        team_id: { type: integer }
        site_id: { type: integer }
        fqdn: { type: string }
        type: { type: string }
        is_wildcard: { type: boolean }
        status: { type: string }
        dns_provider_id: { type: ['null', integer] }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        site: { $ref: '#/components/schemas/Site' }

    ServerUpdate:
      type: object
      description: |
        The connection details of a server, and nothing else. `status`,
        `team_id`, `is_managed`, `provider_id` and the provisioning passwords are
        not writable through any endpoint; naming one here changes nothing rather
        than failing, because only the fields below are read out of the body.

        Every field is optional, so `PUT` and `PATCH` behave identically: an
        omitted field is left alone rather than cleared. `region` may not be
        cleared on a server that has a cloud provider behind it.

        These are the dashboard's own rules — the same class, with one line
        overridden for the partial-body behaviour above. It used to be a second
        copy, which allowed a two-character name and an 80-character `region`
        into a 30-character column.
      properties:
        name:
          type: string
          minLength: 5
          maxLength: 80
          description: Letters, digits, dashes and underscores.
        ip_address:
          type: string
          format: ipv4
          description: |
            Must be publicly routable — private, loopback, link-local, multicast
            and reserved ranges are refused.
        private_ip:
          type: ['null', string]
          format: ipv4
          description: The machine's address on its private network. May be cleared.
        ssh_port:
          type: integer
          minimum: 1
          maximum: 65535
        region:
          type: ['null', string]
          maxLength: 30

    DomainWrite:
      type: object
      properties:
        fqdn:
          type: string
          description: The domain name. Must not be a reserved or FlyWP test domain.
          example: example.com
        type:
          type: string
          enum: [primary, redirect, alias]
          description: |
            What role the domain plays for the site. A site has exactly one
            `primary`; making another domain primary demotes the old one.
        is_wildcard:
          type: boolean
        dns_provider_id:
          type: ['null', integer]
          description: A DNS integration to write the records through.
      required: [fqdn, type]

    Certificate:
      type: object
      properties:
        id: { type: integer }
        team_id: { type: integer }
        site_id: { type: integer }
        domain: { type: string }
        is_existing: { type: boolean }
        folder_name: { type: string }
        key_type: { type: string }
        preferred_chain: { type: ['null', string] }
        type: { type: string }
        status: { type: string }
        activation_status: { type: ['null', string] }

    StaticSite:
      type: object
      description: The static site of a WordPress site. It contains no credentials.
      properties:
        id: { type: integer }
        site_id: { type: integer }
        destination: { type: string, enum: [flywp-html, s3, cloudflare-workers, cloudflare-pages] }
        destination_label: { type: string }
        status: { type: string, enum: [provisioning, active, failed] }
        public_domain: { type: string }
        public_url: { type: string }
        setup_error: { type: ['null', string] }
        temporary_url: { type: ['null', string] }
        dns_records:
          type: array
          description: The DNS records to add for the static domain. Empty until the status is `active`.
          items: { type: object }
        dns_note: { type: ['null', string] }
        latest_deployment:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/StaticSiteDeployment'
        settings:
          type: object
          properties:
            integration_id: { type: ['null', integer] }
            integration_name: { type: ['null', string] }
            bucket: { type: ['null', string] }
            region: { type: ['null', string] }
            needs_region: { type: boolean }
            worker_name: { type: ['null', string] }
            pages_project_name: { type: ['null', string] }
            html_site_id: { type: ['null', integer] }
            html_site_domain: { type: ['null', string] }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    StaticSiteWrite:
      type: object
      required: [destination]
      properties:
        destination: { type: string, enum: [flywp-html, s3, cloudflare-workers, cloudflare-pages] }
        domain:
          type: string
          description: The static domain. Required, except for `flywp-html`, which uses the domain of the HTML site.
          example: static.example.com
        integration_id:
          type: integer
          description: A team integration that can hold the credentials. Required, except for `flywp-html`.
        bucket: { type: string, description: Required for `s3`. }
        region: { type: string, description: For `s3` only. Some providers require it. }
        html_site_id: { type: integer, description: Required for `flywp-html`. An HTML site on the same server. }
        pages_project_name: { type: string, description: For `cloudflare-pages` only. }

    ComposeApp:
      type: object
      properties:
        id: { type: integer, description: 'The id of the site of the app.' }
        name: { type: string }
        server_id: { type: integer }
        domain: { type: string, description: 'The internal name of the app (its folder on the server). It is the free test domain of an app that was made with the test domain, until the test domain is removed.' }
        status: { type: string, enum: [deploying, running, degraded, down, stopped, deploy_failed, deleting] }
        source: { type: string, enum: [paste, url, template, git] }
        version: { type: [integer, 'null'], description: 'The number of the version that runs.' }
        lock_version: { type: integer, description: 'Send it with a change of the file. A change made since is refused.' }
        memory_limit_mb: { type: integer }
        advanced_mode: { type: boolean, description: 'Advanced mode: the app can use more of the server (an own server only).' }
        deploy_timeout_minutes: { type: integer, description: 'From 30 to 60.' }
        health:
          type: object
          description: 'Automatic rollback, and the health window of a deploy.'
          properties:
            auto_rollback: { type: boolean }
            window_minutes: { type: integer }
        template: { type: [string, 'null'], description: 'The slug of its template.' }
        template_version: { type: [string, 'null'] }
        template_update:
          type: [object, 'null']
          properties:
            from: { type: string }
            to: { type: string }
            security: { type: boolean }
            whats_new: { type: string }
            file_changed: { type: boolean }
        operation: { oneOf: [{ $ref: '#/components/schemas/ComposeOperation' }, { type: 'null' }], description: 'The last restart, stop, start, backup copy or restore of the app.' }
        clone:
          type: [object, 'null']
          description: 'This app is a clone: how far it is. A failed clone removes the new app.'
          properties:
            step: { type: string, enum: [deploy, copy, fetch, restore, start, done, failed] }
            source_site_id: { type: integer, description: 'The app that the clone copies.' }
            source_name: { type: [string, 'null'], description: 'Null when the source app is gone.' }
            failure: { type: [string, 'null'] }
        transfer:
          type: [object, 'null']
          description: 'The last transfer of this app to another server: how far it is. `kept`: the app runs on the new server and its stopped copy stays on the old one until `kept_until`. `back`: the app went back to its old server. A failed transfer leaves the app on its old server.'
          properties:
            step: { type: string, enum: [copy, certificates, deploy, fetch, restore, start, kept, done, back, failed] }
            from_server_id: { type: integer }
            to_server_id: { type: integer }
            from: { type: string, description: 'The name of the old server.' }
            to: { type: string, description: 'The name of the new server.' }
            from_ip: { type: [string, 'null'], description: 'The address of the old server. At `back`, point each domain of `point_domains` to it.' }
            to_ip: { type: [string, 'null'], description: 'The address of the new server. At `kept`, point each domain of `point_domains` to it.' }
            runs_on: { type: string, description: 'The name of the server that the app runs on now.' }
            failure: { type: [string, 'null'] }
            finished_at: { type: [string, 'null'], format: date-time }
            kept_until: { type: [string, 'null'], format: date-time }
            downtime_minutes: { type: [integer, 'null'], description: 'At `kept`: how long the app was down, from the start of the copy to its start on the new server.' }
            point_domains: { type: array, items: { type: string }, description: 'At `kept` and `back`: the domains that you point to the server of the app (FlyWP moves the test domain).' }
        created_at: { type: string, format: date-time }
    ComposeOperation:
      type: object
      properties:
        action: { type: string, enum: [restart, stop, start, backup, restore, copy] }
        service: { type: [string, 'null'], description: 'Null: the whole app.' }
        status: { type: string, enum: [running, done, failed] }
        started_at: { type: string, format: date-time }
        finished_at: { type: [string, 'null'], format: date-time }
        reason: { type: [string, 'null'], description: 'Why it failed.' }
        id: { type: [string, 'null'] }
        cause: { type: [string, 'null'], enum: [memory, disk, transfer, null], description: 'Set when FlyWP started it, not a person: why.' }
    ComposeDeployment:
      type: object
      properties:
        number: { type: integer }
        trigger: { type: string }
        status: { type: string, enum: [queued, running, success, failed, blocked, skipped], description: '`blocked`: a push that waits for a person; `skipped`: a push that a newer one replaced.' }
        stage: { type: [string, 'null'] }
        reason: { type: [string, 'null'] }
        commit: { type: [string, 'null'] }
        rollback_of: { type: [integer, 'null'] }
        restore_of: { type: [integer, 'null'], description: 'The id of the backup whose restore this deploy ends.' }
        template_version: { type: [string, 'null'] }
        created_by: { type: [string, 'null'] }
        created_at: { type: string, format: date-time }
        started_at: { type: [string, 'null'], format: date-time }
        finished_at: { type: [string, 'null'], format: date-time }
    ComposeBackup:
      type: object
      properties:
        id: { type: integer }
        created_at: { type: string, format: date-time }
        status: { type: string, enum: [creating, success, failed, delayed] }
        reason: { type: [string, 'null'], enum: [scheduled, manual, before_deploy, before_rollback, before_restore, null] }
        version: { type: [integer, 'null'], description: 'The number of the version of the app that the backup is of.' }
        size: { type: [integer, 'null'], description: 'Bytes.' }
        destination: { type: [string, 'null'] }
        paused_seconds: { type: [integer, 'null'], description: 'How long the services that the copy needs were stopped.' }
        copied: { type: boolean }
        failure: { type: [string, 'null'] }
        restorable: { type: boolean, description: 'Its file and its checksum are in the destination of the app.' }
        downloadable: { type: boolean, description: 'The file is in the destination: the dashboard gives a link to it.' }
        destination_removed: { type: boolean, description: 'The destination of the backup is gone.' }
        missing: { type: boolean, description: 'The file is not in the destination any more.' }
        runs: { type: boolean, description: 'The app runs the compose file, the environment variables and the images of the version of the backup. A restore needs `restorable` and `runs`; else roll back to that version first.' }
        restore:
          type: [object, 'null']
          description: The newest restore of the backup.
          properties:
            status: { type: string, enum: [waiting, running, done, failed] }
            step: { type: [string, 'null'], enum: [download, check, stop, restore, import, deploy, null] }
            failure: { type: [string, 'null'] }
            safety_backup_id: { type: [integer, 'null'] }

    StaticSiteDeployment:
      type: object
      description: One static deploy. It contains the user id and name, not the email.
      properties:
        id: { type: integer }
        trigger: { type: string, enum: [manual, api, setup] }
        status: { type: string }
        started_at: { type: ['null', string], format: date-time }
        finished_at: { type: ['null', string], format: date-time }
        created_at: { type: string, format: date-time }
        user:
          type: ['null', object]
          properties:
            id: { type: integer }
            name: { type: string }
        extra:
          type: object
          description: The mode, the stage, the counts and the error of the deploy.
        log_tail:
          type: ['null', string]
          description: Only on the single deployment read, and only for a caller with `site:update`.

    WpConfig:
      type: object
      description: |
        The seven constants FlyWP manages in `wp-config.php`. Not the file, and
        not everything in it — see the endpoint description.
      properties:
        wp_debug: { type: boolean }
        wp_debug_log: { type: boolean }
        wp_debug_display: { type: boolean }
        script_debug: { type: boolean }
        concatenate_scripts: { type: boolean }
        savequeries: { type: boolean }
        wp_auto_update_core:
          description: |
            `true` for every core release, `false` for none, `minor` for security
            and minor releases only.

            The strings `"true"` and `"false"` are accepted as well as the JSON
            booleans, because the dashboard's own form sends them. A read returns
            the boolean, so the document this endpoint gives you is the document it
            takes back.
          oneOf:
            - { type: boolean }
            - { type: string, enum: ['true', 'false', minor] }
      required:
        - wp_debug
        - wp_debug_log
        - wp_debug_display
        - script_debug
        - concatenate_scripts
        - savequeries
        - wp_auto_update_core

    BulkActionWrite:
      type: object
      required: [operation, site_ids]
      properties:
        operation:
          type: string
          description: |
            A registered operation key. The keys this build knows are listed in the
            `label` of a preview; an unknown key is a `422`. Each operation declares its
            own `options`, validated against that operation's option types.
        site_ids:
          type: array
          minItems: 1
          maxItems: 500
          items: { type: integer }
          description: |
            The sites to act on. An id the token's user cannot see is dropped without a
            trace; a site the user may not change, or that the operation cannot use, is
            recorded as `skipped` with a reason and the run goes on without it.
        options:
          type: object
          additionalProperties: true
        confirm:
          type: ['null', integer]
          description: |
            Required when the preview says `sensitive: true`. Send the preview's
            `eligible_count`. A missing or different number is a `422`, and nothing runs.

    BulkActionPreview:
      type: object
      description: What a confirm step shows before a run is started. The same resolver as the start, so the count agrees.
      properties:
        operation: { type: string }
        label: { type: string }
        eligible_count: { type: integer }
        excluded:
          type: object
          description: Domains left out, grouped by reason.
          additionalProperties:
            type: array
            items: { type: string }
        sensitive:
          type: boolean
          description: The run needs `confirm` with the eligible count. The dashboard asks the user to type it.
        preview:
          type: ['null', object]
          description: The operation's own estimate (a monthly cost, a size), when it has one.

    BulkActionItem:
      type: object
      properties:
        site_id: { type: integer }
        domain: { type: ['null', string] }
        status:
          type: string
          enum: [queued, running, succeeded, skipped, failed, cancelled]
        reason:
          type: ['null', string]
          description: Why the item was skipped or failed. A note on a succeeded item where the operation left one.
        started_at: { type: ['null', string], format: date-time }
        finished_at: { type: ['null', string], format: date-time }

    BulkAction:
      type: object
      properties:
        id: { type: integer }
        operation: { type: string }
        label: { type: string }
        status:
          type: string
          enum: [processing, completed, completed_with_failures, failed, cancelled]
        total: { type: integer }
        counts:
          type: object
          properties:
            queued: { type: integer }
            running: { type: integer }
            succeeded: { type: integer }
            skipped: { type: integer }
            failed: { type: integer }
            cancelled: { type: integer }
        items:
          type: array
          items: { $ref: '#/components/schemas/BulkActionItem' }
        created_at: { type: string, format: date-time }
        finished_at: { type: ['null', string], format: date-time }
        can_cancel:
          type: boolean
          description: The token's user may cancel this run now. True only while sites are queued, for the starter or a member who can manage the team.
        can_retry:
          type: boolean
          description: The token's user may retry this run now. True only for a finished run with failed sites that was not retried before. A billing operation still needs the owner when the retry starts.

    WhiteLabelPlan:
      type: object
      properties:
        id:
          type: integer
          description: FlyWP's own id. Map your products on `sku`, not on this.
          example: 17
        sku:
          type: string
          description: The product code the reseller chose. Stable, and the only identifier to store.
          example: ACME-STARTER
        name:
          type: string
          example: Starter
        price:
          type: integer
          description: The reseller's own reference price, in cents. Your system charges whatever it charges.
          example: 2900
        regular_price:
          type: integer
          nullable: true
          description: |
            The monthly price before a sale, in cents, to show crossed out beside
            `price`; `price` is then the sale price. Null when the plan has no sale,
            and never less than or equal to `price`.
          example: 3900
        site_limit:
          type: integer
          description: How many sites a customer on this plan may have.
          example: 3
        limits:
          $ref: '#/components/schemas/WhiteLabelLimits'
        stacks:
          type: array
          description: The web servers a site on this plan may use.
          items:
            type: string
            enum: [nginx, openlitespeed]
          example: [nginx]
        php_versions:
          type: array
          description: The PHP versions a site on this plan may use.
          items:
            type: string
          example: ['8.2', '8.3']
        php_default:
          type: string
          example: '8.3'
        server_kind:
          type: string
          enum: [managed, own, mixed]
          description: |
            What the plan's customers are placed on: servers FlyWP manages, the
            reseller's own servers, or the reseller's own first and managed after.
        sold_out:
          type: boolean
          description: |
            Nobody new can buy the plan now. Its pool has no room for a new customer
            or site (a create answers `409 plan_sold_out`), or a create on it is
            refused for another reason, such as FlyWP's fee not accepted or a bill
            unpaid (a create answers that reason's code). A reseller may hide a
            sold-out plan, and then it is not listed at all.
        fee:
          type: object
          nullable: true
          description: |
            FlyWP's fee on a sale of the plan through the reseller's own website:
            the percent or the minimum, whichever is greater. A customer this API
            creates is billed on the reseller's FlyWP invoice, by the method FlyWP
            set for the reseller. Null while FlyWP shows no fee.
          properties:
            percent:
              type: number
              example: 20
            minimum_cents:
              type: integer
              example: 300
      example:
        id: 17
        sku: ACME-STARTER
        name: Starter
        price: 2900
        site_limit: 3
        limits: { site_cpu_millis: 1000, site_memory_mb: 1024, disk_gb: 30, bandwidth_gb: 300, bandwidth_action: notify }
        stacks: [nginx]
        php_versions: ['8.2', '8.3']
        php_default: '8.3'
        server_kind: managed
        sold_out: false
        fee: null

    WhiteLabelLimits:
      type: object
      description: |
        What a customer gets: CPU and memory for each site, disk and bandwidth
        for all of the customer's sites together. A customer takes a copy of
        the plan's figures when they buy and when they move to another plan.
      properties:
        site_cpu_millis:
          type: integer
          description: CPU for each site, in thousandths of a core (1000 is one core).
          example: 1000
        site_memory_mb:
          type: integer
          description: Memory for each site, in MB.
          example: 1024
        disk_gb:
          type: integer
          description: Disk for all of the customer's sites, in GB.
          example: 30
        bandwidth_gb:
          type: ['null', integer]
          description: Bandwidth a month for all of the customer's sites, in GB. Null is no limit.
          example: 300
        bandwidth_action:
          type: string
          enum: [notify, slow, pause]
          description: What happens when the customer uses all the bandwidth.
          example: notify

    WhiteLabelCustomerStatus:
      type: string
      description: |
        A customer this API creates starts `active`, so `pending` only appears
        for somebody who started a signup on the reseller's own website and
        never paid. `past_due` is a renewal FlyWP itself could not
        collect, and reaches only customers who pay through the reseller's own
        website rather than through your system.
      enum: [pending, active, past_due, suspended, cancelled]
      example: active

    WhiteLabelCustomer:
      type: object
      properties:
        id:
          type: integer
          description: FlyWP's own id, used in every path here.
          example: 4821
        external_id:
          type: ['null', string]
          description: Your own identifier for them, exactly as you sent it.
          example: wc-1042
        name:
          type: string
          example: Ada Lovelace
        email:
          type: string
          format: email
          example: ada@example.com
        status:
          $ref: '#/components/schemas/WhiteLabelCustomerStatus'
        billing_paused_by:
          type: ['null', string]
          enum: [flywp, dashboard, null]
          description: |
            Who paused a website customer's billing: `flywp` with a suspend,
            `dashboard` in the reseller's own Stripe dashboard. Null when it is
            not paused, and always null for a customer billed by your own system.
        plan:
          type: ['null', object]
          properties:
            id:
              type: integer
              example: 17
            sku:
              type: string
              example: ACME-STARTER
            name:
              type: string
              example: Starter
        price:
          type: ['null', integer]
          description: What this customer is on, in cents, as at the moment they were put on it.
          example: 2900
        site_limit:
          type: integer
          example: 3
        limits:
          $ref: '#/components/schemas/WhiteLabelLimits'
        limits_overridden:
          type: boolean
          description: |
            The reseller set `limits` for this customer, apart from their plan.
            A plan move gives them the new plan's.
          example: false
        sites_used:
          type: integer
          description: How many of `site_limit` they have used.
          example: 1
        login_url:
          type: ['null', string]
          description: |
            Where this customer signs in, for your own welcome mail. Null until
            the reseller has fixed their address, so no billing system ever
            stores one that is about to change.
          example: https://acme.flywp.xyz/login
        activated_at:
          type: ['null', string]
          format: date-time
          example: '2026-09-17T09:14:22+00:00'
        cancelled_at:
          type: ['null', string]
          format: date-time
          example: null
        created_at:
          type: string
          format: date-time
          example: '2026-09-17T09:14:22+00:00'
        sites:
          type: array
          description: Included on `GET /v1/white-label/customers/{client}` only.
          items:
            $ref: '#/components/schemas/WhiteLabelCustomerSite'
        usage:
          type: object
          description: |
            Included on `GET /v1/white-label/customers/{client}` only, with
            `sites`. The disk all their sites use, against `limits.disk_gb`, and
            the bandwidth they sent this month (UTC), against
            `limits.bandwidth_gb`. Sites with no disk figure yet are
            `unmeasured`, so the real use can be higher, never lower. At 80 %,
            90 % and 100 % of each, FlyWP mails the customer, in your brand, and
            you.
          properties:
            disk_bytes:
              type: integer
              description: |
                Each site's own files (without cache, backups and logs) and its
                database when `files_only`; else its whole folder, without the
                database (the folder can hold database dumps in its backups).
              example: 9663676416
            disk_percent:
              type: ['null', number]
              description: Of `limits.disk_gb`. Null with no disk total.
              example: 30.0
            unmeasured: { type: integer, example: 0 }
            files_only:
              type: boolean
              description: Every disk figure is the sites' own files. False while a server has an older monitoring agent.
            databases_counted:
              type: boolean
              description: Every disk figure has the site's database in it (a site with no database has none to count). Database sizes are measured each hour, and count only with the sites' own files.
            bandwidth_bytes:
              type: integer
              description: What all their sites sent to visitors this month (UTC). Meaningful only when `bandwidth_measured`.
              example: 3221225472
            bandwidth_percent:
              type: ['null', number]
              description: Of `limits.bandwidth_gb`. Null with no bandwidth limit, or while it is not measured.
              example: 10.7
            bandwidth_measured:
              type: boolean
              description: False while no ready server of their sites counts bandwidth yet (no traffic log, or an older monitoring agent).
            bandwidth_unmeasured:
              type: integer
              description: Sites on a server that does not count bandwidth yet, so the real figure can be higher.
              example: 0
            bandwidth_action:
              type: ['null', string]
              enum: [notify, slow, pause, null]
              description: What happens at 100 % of `limits.bandwidth_gb`, as `limits.bandwidth_action`.
            bandwidth_limited_at:
              type: ['null', string]
              format: date-time
              description: |
                Their sites are slowed down (`slow`) or show a "Bandwidth limit
                reached" page (`pause`) since then, until the month starts again.
                Null: no limit on this month.
      example:
        id: 4821
        external_id: wc-1042
        name: Ada Lovelace
        email: ada@example.com
        status: active
        plan:
          id: 17
          sku: ACME-STARTER
          name: Starter
        price: 2900
        site_limit: 3
        limits: { site_cpu_millis: 1000, site_memory_mb: 1024, disk_gb: 30, bandwidth_gb: 300, bandwidth_action: notify }
        sites_used: 1
        login_url: https://acme.flywp.xyz/login
        activated_at: '2026-09-17T09:14:22+00:00'
        cancelled_at: null
        created_at: '2026-09-17T09:14:22+00:00'

    WhiteLabelCustomerUpdate:
      type: object
      description: Send any of these. Anything left out is unchanged.
      properties:
        name:
          type: string
          maxLength: 255
          example: Ada Lovelace
        email:
          type: string
          format: email
          maxLength: 255
          description: |
            Lowercased before it is stored, and unique among this reseller's
            customers only. Sending the address they already have changes
            nothing.
          example: ada@example.com
        plan_sku:
          type: string
          description: |
            The product code of a published plan. Sending the one the customer is
            already on changes nothing and answers `200`, so a billing system
            that re-sends the package on every change is safe to point here.
          example: ACME-GROWTH
        limits:
          description: |
            The customer's own resources, apart from their plan, with all five
            fields. `null` gives them their plan's again. Their sites get them
            in a few minutes. A later plan move gives them the new plan's.
          oneOf:
            - $ref: '#/components/schemas/WhiteLabelLimits'
            - type: 'null'
      example:
        plan_sku: ACME-GROWTH

    WhiteLabelCustomerSite:
      type: object
      properties:
        id:
          type: integer
          example: 9310
        external_id:
          type: ['null', string]
          description: Your own reference, exactly as you sent it. Null for a site made elsewhere.
          example: wc-order-1042
        domain:
          type: string
          example: shop.example.com
        status:
          type: string
          description: The site's own state, as the dashboard shows it.
          example: active
        limits:
          type: ['null', object]
          description: |
            What the site runs with on its server: CPU in thousandths of a core
            and memory in MB. They are the customer's, unless the reseller set
            the site apart. Null: no limits.
          properties:
            cpu_millis: { type: integer, example: 1000 }
            memory_mb: { type: integer, example: 1024 }
        usage:
          type: ['null', object]
          description: |
            What the site used on its last day with figures (UTC): the highest
            CPU (thousandths of a core) and memory (MB) read every 5 minutes, and
            the last disk figure. A sleeping site keeps its last day. Null:
            never measured.
          properties:
            day: { type: string, format: date, example: '2026-10-16' }
            peak_cpu_millis: { type: ['null', integer], example: 420 }
            peak_memory_mb: { type: ['null', integer], example: 610 }
            disk_bytes:
              type: ['null', integer]
              description: What counts toward the customer's disk total, `files_bytes` plus `db_bytes`; from an older monitoring agent, the whole folder without the database.
              example: 2147483648
            disk_measured_at: { type: ['null', string], format: date-time, example: '2026-10-16T09:00:00.000000Z' }
            files_bytes:
              type: ['null', integer]
              description: The site's own files, without cache, backups and logs. Null from an older monitoring agent.
              example: 1610612736
            db_bytes:
              type: ['null', integer]
              description: The size of the site's database, measured each hour. Null before the first measure.
              example: 536870912
        progress:
          type: string
          description: |
            What to poll. `waiting_for_server` is a machine being launched for
            this site, which is minutes; `provisioning` is the site itself being
            built, which is faster; `ready` means it is serving. `failed` means
            it will not finish, and `failure_reason` says why.
            Any other value is the site's own state passed through, for a site
            that is not being built — `deleting`, `sleeping` and so on.
          example: ready
        failure_reason:
          type: ['null', string]
          description: Set only when `progress` is `failed`.
          example: null
        dns_target:
          type: ['null', string]
          description: |
            Where to point a domain the customer owns. Null until the site has a
            server, which is exactly while there is nothing true to tell them.
          example: 198.51.100.9
        updated_at:
          type: string
          format: date-time
          description: When this site last changed, so a poller can tell what moved.
          example: '2026-09-17T09:18:41+00:00'
        stack:
          type: string
          enum: [nginx, openlitespeed]
          example: nginx
        php_version:
          type: string
          example: '8.3'
        php_outdated:
          type: boolean
          description: True when the site runs a PHP version that gets no security fixes upstream (end-of-life).
          example: false
        ssl_enabled:
          type: boolean
          example: true
        created_at:
          type: string
          format: date-time
          example: '2026-09-17T09:16:04+00:00'
      example:
        id: 9310
        external_id: wc-order-1042
        domain: shop.example.com
        status: active
        progress: ready
        failure_reason: null
        dns_target: 198.51.100.9
        stack: nginx
        php_version: '8.3'
        php_outdated: false
        ssl_enabled: true
        created_at: '2026-09-17T09:16:04+00:00'

  responses:
    BadRequest:
      description: An unknown `filter`, `sort`, `include` or `fields` was requested.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }

    Unauthorized:
      description: No token, or a token that has expired or been revoked.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }

    PaymentRequired:
      description: |
        The plan has no room for this, or the team could not be billed. The
        message says which.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }

    WhiteLabelForbidden:
      description: |
        The key is not a White Label key, no longer belongs to a team, the team
        is not in White Label, or the team does not sell through its own billing
        system. The message says which.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }

    WhiteLabelRefused:
      description: |
        The request was understood and refused, and nothing was changed. Read
        `code` to tell which, and whether waiting will help.

        Waiting helps: `subscription_lapsed` once the reseller pays again, and
        `byos_unpaid` once the reseller pays their FlyWP bill for their own
        servers, `fee_unpaid` once the reseller pays their FlyWP bill for White
        Label fees, and `plan_sold_out` once the reseller adds a server or more room.
        `fee_terms_not_accepted` once the reseller's owner accepts FlyWP's fee in
        the dashboard: a key never accepts it. Only a new customer waits for it.

        Waiting does not help: `customer_cap_reached`, `no_plans_published` and
        `pool_closed` need the reseller to act. `external_id_taken`,
        `customer_cancelled` and `site_already_deleting` need you to do
        something different.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }

    Forbidden:
      description: |
        The token, or its owner, may not do this to a resource they can see.

        `code: trial_locked`: the server is a free trial server, and the free
        trial does not include this (SSH keys, the nginx or OLS config and its
        restore to default, the environment, a deploy, a second server or site,
        a clone of the trial site, a site type other than WordPress). A bulk action leaves the trial server's sites out (reason
        `trial`). Keeping the server unlocks it.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }

    NotFound:
      description: |
        No such resource in this team. A resource that belongs to another team
        answers this too — existence is not a public fact.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }

    Conflict:
      description: The resource is busy, or already in the state that was asked for.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }

    ValidationFailed:
      description: The request body, or the `X-Team-Id` header, did not validate.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ValidationError' }

    TooManyRequests:
      description: |
        Rate limited: the token is over its requests per minute.
        `Retry-After` says how many seconds to wait.
      headers:
        Retry-After:
          schema: { type: integer }
        X-RateLimit-Limit:
          schema: { type: integer }
        X-RateLimit-Remaining:
          schema: { type: integer }
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }

    ServiceUnavailable:
      description: The Public API is switched off.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }

paths:
  /v1/ping:
    get:
      tags: [Getting Started]
      summary: Ping
      description: |
        Answers even while the API is switched off and without a token, so a DNS
        or vhost problem stays distinguishable from a 503.
      operationId: ping
      security: []
      responses:
        '200':
          description: Awake.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string, example: pong }
                  timestamp: { type: string, format: date-time }

  /v1/verify-api-key:
    get:
      tags: [Authentication]
      summary: Verify a token
      operationId: verifyApiKey
      parameters:
        - $ref: '#/components/parameters/TeamId'
      responses:
        '200':
          description: The token is valid and may act on this team.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Message' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/servers:
    get:
      tags: [Servers]
      summary: List servers
      description: The servers this token can see in this team, not every server the team owns.
      operationId: listServers
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/PerPage'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Include'
      responses:
        '200':
          description: One page of servers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/Server' }
                  links: { $ref: '#/components/schemas/CursorLinks' }
                  meta: { $ref: '#/components/schemas/CursorMeta' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

    post:
      tags: [Servers]
      summary: Create a server
      description: |
        Provisions a machine at the named provider, or registers one you already
        own when `type` is `custom`. Billing happens here, exactly as it does in
        the dashboard, because both doors run one action.

        The body is the dashboard's, field for field, because both doors run one
        FormRequest — the earlier `provider` / `credential_id` / `ip_address` /
        `ssh_port` spellings are gone.

        Which fields are required depends on `type`:

        - **`custom`** needs `ip` and `port`, and cannot be managed: there is no
          machine for FlyWP to provision and no provider to price it through.
        - **Every other provider** needs `region` and `size`, and needs
          `credential` unless FlyWP is managing the server.
        - **`aws`** additionally needs `disk`.

        `is_managed` defaults to false when omitted, which is what the dashboard
        sends with the switch off.
      operationId: createServer
      parameters:
        - $ref: '#/components/parameters/TeamId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 2
                  maxLength: 80
                  pattern: '^[a-zA-Z0-9-]+$'
                  example: web-01
                type:
                  type: string
                  enum: [do, vultr, custom, aws, akamai, hetzner]
                  description: A cloud provider, or `custom` for a machine you already own.
                  example: do
                os:
                  type: string
                  enum: [ubuntu-22, ubuntu-24, ubuntu-26]
                  example: ubuntu-24
                is_managed:
                  type: boolean
                  default: false
                  description: |
                    Provisioned, hosted and billed by FlyWP rather than on your
                    own cloud account. Not available with `type: custom`.
                credential:
                  type: integer
                  description: |
                    One of *this team's* stored provider credentials. Required
                    unless `is_managed`. A credential belonging to another team
                    is a 422, not a 404.
                region:
                  type: string
                  maxLength: 30
                  description: Required for every provider except `custom`.
                  example: sgp1
                size:
                  type: string
                  description: Required for every provider except `custom`.
                  example: s-1vcpu-1gb
                disk:
                  type: integer
                  minimum: 20
                  description: EBS volume size in GB. AWS only; ignored elsewhere.
                ip:
                  type: string
                  format: ipv4
                  description: |
                    Required when `type` is `custom`. Must be publicly routable —
                    private, loopback, link-local, multicast and reserved ranges
                    are refused.
                private_ip:
                  type: ['null', string]
                  format: ipv4
                  description: The machine's address on its private network, if it has one.
                port:
                  type: integer
                  minimum: 1
                  maximum: 65535
                  description: SSH port. Required when `type` is `custom`.
              # Only the three that are required whatever `type` is. Everything
              # else is conditional on it, and a flat list cannot say so — the
              # rules above the properties are the contract. `is_managed` is not
              # here because this door defaults it to false; the dashboard's form
              # requires it because its form always sends it.
              required: [name, type, os]
      responses:
        '202':
          description: The server record exists; the machine is being provisioned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/Server' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '502':
          description: The cloud provider refused to create the machine. The message is theirs.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/servers/{server}:
    get:
      tags: [Servers]
      summary: Show a server
      operationId: showServer
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/ServerId'
      responses:
        '200':
          description: The server.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/Server' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

    put:
      tags: [Servers]
      summary: Update a server
      description: |
        Every field is optional, so `PUT` and `PATCH` behave identically and both
        are registered. An omitted field is left alone, not cleared.

        The body must still name at least one of them. An empty body — or one
        that is not valid JSON, which parses to the same thing — is a `422`
        rather than a `200` reporting a change that did not happen. Setting a
        nullable field to `null` is a real update and is accepted.
      operationId: updateServer
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/ServerId'
      requestBody:
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ServerUpdate' }
      responses:
        '200':
          description: The updated server.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/Server' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

    patch:
      tags: [Servers]
      summary: Update a server
      operationId: patchServer
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/ServerId'
      requestBody:
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ServerUpdate' }
      responses:
        '200':
          description: The updated server.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/Server' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

    delete:
      tags: [Servers]
      summary: Delete a server
      description: |
        Destroys the machine at the provider and settles the billing. If the
        refund or the provider call fails the record is kept on purpose, so the
        deletion can be retried rather than the server disappearing while still
        running and still billing.

        A free trial server that is being kept right now answers 422 (`server`).
        Retry in a minute.
      operationId: deleteServer
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/ServerId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                force:
                  type: boolean
                  description: Delete the record even if the provider call or the refund fails.
                cancellation_reason:
                  type: string
      responses:
        '200':
          description: Deleted.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Message' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409':
          description: |
            A White Label plan or a customer still needs the server, so nothing was
            deleted. A server stays while a plan's pool uses it: one the pool grew on
            FlyWP's cloud, a plan's starting server, or one of your own servers put in
            a plan. One a plan grew on your own cloud account can go once no customer
            site is on it.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '500':
          description: |
            The provider refused, or the refund failed. The server was kept so
            you can retry.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/servers/{server}/ssh-keys:
    get:
      tags: [Server SSH Keys]
      summary: List SSH keys
      operationId: listSshKeys
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/ServerId'
        - $ref: '#/components/parameters/PerPage'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Include'
      responses:
        '200':
          description: One page of SSH keys.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/SshKey' }
                  links: { $ref: '#/components/schemas/CursorLinks' }
                  meta: { $ref: '#/components/schemas/CursorMeta' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

    post:
      tags: [Server SSH Keys]
      summary: Add an SSH key
      description: |
        Appends the key to the named unix user's `authorized_keys`. The key is
        live on the machine as soon as the queued job finishes, so treat this as
        granting shell access.
      operationId: addSshKey
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/ServerId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  maxLength: 100
                  example: Deploy key
                user:
                  type: string
                  maxLength: 20
                  description: The unix user on the server whose `authorized_keys` the key is added to.
                  example: fly
                key:
                  type: string
                  description: An OpenSSH public key.
                  example: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl you@example.com
              required: [name, user, key]
      responses:
        '202':
          description: The key is being installed on the server.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/SshKey' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/servers/{server}/ssh-keys/{sshKey}:
    delete:
      tags: [Server SSH Keys]
      summary: Remove an SSH key
      description: |
        Removes the key from the server's `authorized_keys` and then deletes the
        record. A failed removal leaves the key listed and retryable rather than
        invisible and still live.
      operationId: deleteSshKey
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/ServerId'
        - $ref: '#/components/parameters/SshKeyId'
      responses:
        '202':
          description: The key is being removed from the server.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Message' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/servers/{server}/scale-options:
    get:
      tags: [Server Scale]
      summary: List the plans a server can scale to
      description: |
        The modes the provider supports, and the larger plans of each mode,
        read from the provider now. `meta` gives the current plan and its
        monthly price: FlyWP's price for a managed server, the provider's
        list price for a server on your own account.

        `409` when FlyWP cannot scale the server, or the team holds White
        Label. `502` when the provider
        refuses the read (the message says why), `504` when it does not answer.
      operationId: listServerScaleOptions
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/ServerId'
      responses:
        '200':
          description: The modes and their plans.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/ServerScaleOption' }
                  meta:
                    type: object
                    properties:
                      current_size: { type: string, description: 'The current plan of the server.' }
                      current_monthly:
                        type: number
                        nullable: true
                        description: 'The monthly price of the current plan, in the currency of the plan prices: EUR for Hetzner, USD for the other providers. Null when the provider does not list the plan.'
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '502':
          description: The provider refused the read. The message is theirs.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '504':
          description: The provider did not answer. Try again in a few minutes.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/servers/{server}/scales:
    post:
      tags: [Server Scale]
      summary: Start a scale
      description: |
        Starts a scale to a plan from `scale-options`. The provider work runs
        in the background: read the scale until its `status` is final.

        `402` when a managed server's payment fails; nothing was changed.
        `409` when the server cannot scale now: the team holds White Label, a
        scale or another change runs, the plan is not available, the server is
        not Ready, or a managed
        server has an unpaid invoice or is in the last day of its billing
        period. The message says which. `502` when the provider refuses the
        read of the plans, `504` when it does not answer.
      operationId: startServerScale
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/ServerId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [mode, to_size]
              properties:
                mode: { type: string, enum: [cpu_ram, cpu_ram_disk] }
                to_size: { type: string, description: 'A `plans[].size` of the mode.' }
      responses:
        '202':
          description: The scale started.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/ServerScale' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '502':
          description: The provider refused the request. The message is theirs; nothing was changed.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '504':
          description: The provider did not answer. Nothing was started; try again in a few minutes.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/servers/{server}/scales/{scale}:
    get:
      tags: [Server Scale]
      summary: Get a scale
      description: The step of a scale, and its result when it is final.
      operationId: getServerScale
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/ServerId'
        - $ref: '#/components/parameters/ServerScaleId'
      responses:
        '200':
          description: The scale.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/ServerScale' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/servers/{server}/metrics:
    get:
      tags: [Server Monitoring]
      summary: Read the monitoring of a server
      operationId: getServerMetrics
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/ServerId'
        - name: range
          in: query
          required: false
          schema: { type: string, enum: ['1h', '6h', '24h', '7d'], default: '1h' }
      responses:
        '200':
          description: The agent, its latest report, and the charts of one range.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/ServerMetrics' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/servers/{server}/monitoring-agent:
    post:
      tags: [Server Monitoring]
      summary: Install the monitoring agent
      description: |
        Installs the FlyWP agent on the server and starts it. The install is
        queued and can take several minutes; `agent.installed_at` on
        `GET /v1/servers/{server}/metrics` is set when it is complete.

        `409` when the server already has the agent, or while monitoring is not
        available yet.
      operationId: installMonitoringAgent
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/ServerId'
      responses:
        '202':
          description: |
            The install is queued, or an install for this server is already
            running.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Message' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/servers/{server}/alert-thresholds:
    get:
      tags: [Server Monitoring]
      summary: Read the alert limits of a server
      description: |
        The server's own limits, or the team's limits when it has none.
      operationId: getServerAlertThresholds
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/ServerId'
      responses:
        '200':
          description: The limits that apply to the server.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/AppliedAlertThresholds' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    put:
      tags: [Server Monitoring]
      summary: Set the alert limits of a server
      description: The server then uses these limits, not the team's.
      operationId: updateServerAlertThresholds
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/ServerId'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/AlertThresholds' }
      responses:
        '200':
          description: The limits that apply to the server.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/AppliedAlertThresholds' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    delete:
      tags: [Server Monitoring]
      summary: Remove the alert limits of a server
      description: The server then uses the team's limits.
      operationId: deleteServerAlertThresholds
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/ServerId'
      responses:
        '200':
          description: The limits that apply to the server now, which are the team's.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/AppliedAlertThresholds' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/team/alert-thresholds:
    get:
      tags: [Server Monitoring]
      summary: Read the team's alert limits
      description: |
        The default limits for the servers of the team in `X-Team-Id`. Every
        limit is `null` (off) until the team sets its own.
      operationId: getTeamAlertThresholds
      parameters:
        - $ref: '#/components/parameters/TeamId'
      responses:
        '200':
          description: The team's limits.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/AppliedAlertThresholds' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    put:
      tags: [Server Monitoring]
      summary: Set the team's alert limits
      description: A server with its own limits keeps them.
      operationId: updateTeamAlertThresholds
      parameters:
        - $ref: '#/components/parameters/TeamId'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/AlertThresholds' }
      responses:
        '200':
          description: The team's limits.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/AppliedAlertThresholds' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/sites:
    get:
      tags: [Sites]
      summary: List sites
      description: The sites this token can see in this team, not every site the team owns.
      operationId: listSites
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/PerPage'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Include'
      responses:
        '200':
          description: One page of sites.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/Site' }
                  links: { $ref: '#/components/schemas/CursorLinks' }
                  meta: { $ref: '#/components/schemas/CursorMeta' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

    post:
      tags: [Sites]
      summary: Create a site
      description: |
        Every application type the dashboard can create. The body is the
        dashboard's own, field for field, because both doors run one FormRequest
        — the earlier `php_version` / `use_test_domain` / `ssl_enabled` /
        `wp_version` spellings are gone, and were what let this endpoint stay
        WordPress-only while the dashboard grew fourteen more types.

        Which fields are required depends on `type`:

        - **WordPress (`wp`, `bedrock`)** also need `admin_email`,
          `admin_username` and `admin_password`.
        - **`bedrock`, `php`, `laravel`, `symfony`** have no provisioning path
          that is not a git clone, so `use_git` must be true and the four git
          fields are required with it. `bedrock` additionally requires `php` 8.1
          or newer, and refuses `multisite`.
        - **One-click apps** need only `server_id`, `type`, `stack` and a
          domain. `php` does not apply — the container image decides the
          runtime — and is not required for them.
        - **`openlitespeed`** is only available for `wp` and `bedrock`.
        - **Asking for `multisite`** means also sending `multisite_subdomain`:
          it is the one flag with no default, because the two answers need
          different DNS.

        Every other flag defaults to false when omitted, which is what the
        dashboard's form sends with the switch off. `cloudflare` is the
        exception: naming a `cloudflare_integration_id` is the request to use
        one.
      operationId: createSite
      parameters:
        - $ref: '#/components/parameters/TeamId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                server_id:
                  type: integer
                  description: A server in this team. An id outside it is a 422, not a 404.
                type:
                  $ref: '#/components/schemas/SiteTypeValue'
                stack:
                  type: string
                  enum: [nginx, openlitespeed]
                php:
                  type: string
                  example: '8.3'
                  description: |
                    A version the chosen stack offers. Required for every type
                    except a one-click app, whose runtime comes from its
                    container image. Some offered versions are end-of-life: they
                    get no security fixes upstream. The site's `php_outdated`
                    tells you when it runs one.
                cache:
                  type: boolean
                site_title:
                  type: string
                  maxLength: 255
                  description: Required except for `html` and one-click apps on a custom domain.
                admin_email:
                  type: string
                  format: email
                admin_username:
                  type: string
                admin_password:
                  type: string
                  pattern: '^[a-zA-Z0-9\-_!@#%&]+$'
                wp_version_to_install:
                  type: string
                  default: latest
                table_prefix:
                  type: string
                  maxLength: 10
                  pattern: '^[a-zA-Z0-9_]+_$'
                  default: wp_
                multisite:
                  type: boolean
                  description: Prohibited for `bedrock` — its starter cannot declare DOMAIN_CURRENT_SITE.
                multisite_subdomain:
                  type: boolean
                  description: |
                    Required when `multisite` is true, and the only flag here
                    with no default: a subdomain network needs a wildcard DNS
                    record and a subdirectory one does not, so there is no
                    answer that is safe to assume.
                testdomain:
                  type: boolean
                  description: Take a generated `*.flywp.xyz` name. When false, `domain` is required.
                domain:
                  type: string
                  description: |
                    Must not already be served on this server, as either a
                    site's primary domain or any site's alias or redirect. The
                    same domain on a *different* server is allowed: that is how
                    a move is staged before the DNS cutover.
                use_letsencrypt:
                  type: boolean
                  description: Issue a Let's Encrypt certificate once the site is up.
                cloudflare:
                  type: boolean
                  description: Write the site's DNS records. Defaults to true when `cloudflare_integration_id` is given.
                cloudflare_integration_id:
                  type: integer
                  description: A Cloudflare integration belonging to this team.
                use_git:
                  type: boolean
                  description: Required to be true for `bedrock`, `php`, `laravel` and `symfony`.
                git_provider:
                  type: string
                  description: |
                    The type of one of *your own* connected git accounts. The
                    connection is resolved from the authenticated user; a
                    provider id in the body is not read.
                repository:
                  type: string
                  pattern: '^[A-Za-z0-9._-]+/[A-Za-z0-9._-]+$'
                  description: Shape-checked — it is interpolated into a provisioning script that runs as root.
                branch:
                  type: string
                  pattern: '^[A-Za-z0-9._/-]+$'
                push_to_deploy:
                  type: boolean
                public_path:
                  type: string
                  pattern: '^/[A-Za-z0-9._/-]*$'
                  description: |
                    Defaults to the document root the type is normally given —
                    `/web` is conventional for Bedrock, `/` for a static site,
                    `/public` otherwise.
                package_manager:
                  type: string
                  enum: [none, npm, yarn, pnpm]
                  description: Node build for `php`, `laravel` and `symfony`.
                build_command:
                  type: string
                use_external_database:
                  type: boolean
                database_host:
                  type: string
                database_port:
                  type: integer
                database_name:
                  type: string
                database_username:
                  type: string
                database_password:
                  type: string
                blueprint_id:
                  type: string
              required:
                - server_id
                - type
                - stack
                - php
      responses:
        '202':
          description: The site record exists; it is being installed on the server.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/Site' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  # No PUT/PATCH. There is no general "update a site" on the dashboard either:
  # everything it can change about an existing site is a named surface of its own
  # — PHP settings, nginx and cache, cron, wp-config (011), and domains (010) —
  # and the only field a bare update could honestly carry is the site title,
  # which lives inside `settings` and is read by the provisioning script rather
  # than by anything running. 003 removed the empty method that used to be
  # registered here; 007 looked for a real one and found there is none to write.
  /v1/sites/{site}:
    get:
      tags: [Sites]
      summary: Show a site
      operationId: showSite
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '200':
          description: The site.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/Site' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

    delete:
      tags: [Sites]
      summary: Delete a site
      description: |
        The record is kept until the server confirms the files and the database
        are gone. A failure returns the site to service rather than stranding it.
      operationId: deleteSite
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '202':
          description: The site is being deleted.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Message' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/sites/{site}/deployments:
    get:
      tags: [Site Deployments]
      summary: List the git deploys of a site
      description: |
        Newest first, cursor paginated. `404` for a site without git.
      operationId: listSiteDeployments
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '200':
          description: The deploys.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/SiteDeployment' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
    post:
      tags: [Site Deployments]
      summary: Deploy the site now
      description: |
        The dashboard's Deploy Now. A git site is built without its code, and this starts its first
        deploy too.

        - `409` while a deploy runs, or while the site is being built or failed to build.
        - `422` when the deploy key cannot read the repository. The message says what to do and
          can carry the key to add.
      operationId: deploySite
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '202':
          description: The deploy started.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/SiteDeployment' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }

  /v1/sites/{site}/deployments/{deployment}:
    get:
      tags: [Site Deployments]
      summary: Read one git deploy, with its log
      operationId: showSiteDeployment
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - name: deployment
          in: path
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: The deploy.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/SiteDeployment' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }

  /v1/sites/{site}/deploy-key:
    get:
      tags: [Site Deployments]
      summary: Read the deploy key of a private git site
      description: |
        - `ready`: GitHub took the key, or the repository is public.
        - `refused`: GitHub refused it, because the connected account has no admin access to the
          repository. A repository admin adds `public_key` under the repository's Settings → Deploy keys.
        - `verified`: GitHub refused it, a person added it, and the server read the repository with it.
        - `pending`: FlyWP could not register it yet. The next deploy asks GitHub again.
      operationId: showSiteDeployKey
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '200':
          description: The deploy key.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      public_key: { type: string }
                      status: { type: string, enum: [ready, refused, verified, pending] }
                      verified_at: { type: ['null', string], format: date-time }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }

  /v1/sites/{site}/deploy-key/check:
    post:
      tags: [Site Deployments]
      summary: Test the deploy key from the server
      description: |
        Runs `git ls-remote` with the key on the site's server. A key that cannot read the branch
        is `200` with `verified` false and the reason in `message`.
      operationId: checkSiteDeployKey
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '200':
          description: The result of the test.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      verified: { type: boolean }
                      message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }

  /v1/sites/{site}/environment:
    get:
      tags: [Site Deployments]
      summary: Read the .env file of the site
      description: |
        An empty string when the file does not exist yet. `404` for a site type without a `.env`.
      operationId: showSiteEnvironment
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '200':
          description: The file.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      environment: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    put:
      tags: [Site Deployments]
      summary: Replace the .env file of the site
      description: |
        Takes the dashboard editor's switches: `refresh_config_cache` and `restart_queue` for
        Laravel, `rebuild_app` for Node. A Node server app is restarted. Before the first deploy
        only the file is written. `502` when the file is saved but a switch failed; `message`
        says which.
      operationId: updateSiteEnvironment
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [environment]
              properties:
                environment: { type: ['null', string] }
                refresh_config_cache: { type: boolean }
                restart_queue: { type: boolean }
                rebuild_app: { type: boolean }
      responses:
        '200':
          description: The file is saved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      environment: { type: string }
                      applied:
                        type: array
                        items: { type: string }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '502':
          description: The file is saved, but a switch that follows it failed.
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/sites/{site}/clone:
    post:
      tags: [Sites]
      summary: Clone a site
      description: |
        Copies the site onto a server in this team, running the dashboard's own
        clone. The body is the dashboard's, field for field — the earlier
        `use_test_domain` / `ssl_enabled` spellings are gone.

        Only `wp` sites can be cloned: the clone scripts understand one layout,
        and a git-deployed type is reproduced by pointing a new site at the same
        repository. Any other type is a **404**, matching the dashboard, where
        an unsupported application simply has no clone page. A multisite network
        is a 403, and so is a sleeping site. A site on a free trial server is a
        403 `trial_locked`.
      operationId: cloneSite
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                server_id:
                  type: integer
                  description: |
                    The destination server, in the source site's team. It may be
                    the site's current server or another one; the domain check
                    below is made against whichever is named here.
                stack:
                  type: string
                  enum: [nginx, openlitespeed]
                testdomain:
                  type: boolean
                  description: Take a generated `*.flywp.xyz` name. When false, `domain` is required.
                domain:
                  type: string
                  description: Must not already be served on the destination server.
                use_letsencrypt:
                  type: boolean
                cloudflare:
                  type: boolean
                  description: Defaults to true when `cloudflare_integration_id` is given.
                cloudflare_integration_id:
                  type: integer
                migrate_email_settings:
                  type: boolean
                migrate_backup_settings:
                  type: boolean
                copy_scope:
                  type: string
                  enum: [standard, full]
                  default: standard
                  description: |
                    `standard` copies `wp-content`; `full` copies the whole
                    docroot, excluding a `wp-config.php` that would point the
                    clone at the source database.
              required: [server_id, stack]
      responses:
        '202':
          description: The clone is being created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/Site' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/sites/{site}/sleep:
    post:
      tags: [Sites]
      summary: Put a site to sleep
      operationId: sleepSite
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '202':
          description: The site is being put to sleep.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Message' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/sites/{site}/wake:
    post:
      tags: [Sites]
      summary: Wake a site
      operationId: wakeSite
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '202':
          description: The site is being woken up.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Message' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/sites/{site}/maintenance-mode:
    post:
      tags: [Sites]
      summary: Toggle maintenance mode
      description: |
        A toggle, not a setter: it moves the site into maintenance if it is not
        already there, and back into service if it is. The body is ignored.

        WordPress only (`wp`, `bedrock`) — it writes a `maintenance.php` into
        `wp-content`, so it means nothing on any other application type, and a
        Laravel site has its own switch. Anything else is a 403, as it is on the
        dashboard. A sleeping site is also a 403: the container is not up.
      operationId: toggleMaintenanceMode
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '202':
          description: The site is being moved.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Message' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/sites/{site}/backups:
    get:
      tags: [Site Backups]
      summary: List backups
      description: |
        Backups are a database dump plus an archive of a WordPress tree, so this
        endpoint exists only for `wp`, `bedrock`, `php`, `laravel` and `symfony`.
        On any other application type it answers **404**, which is what the
        dashboard answers for the same site.
      operationId: listBackups
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/PerPage'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Include'
      responses:
        '200':
          description: One page of backups.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/Backup' }
                  links: { $ref: '#/components/schemas/CursorLinks' }
                  meta: { $ref: '#/components/schemas/CursorMeta' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

    post:
      tags: [Site Backups]
      summary: Start a manual backup
      description: |
        Backups are a database dump plus an archive of a WordPress tree, so this
        endpoint exists only for `wp`, `bedrock`, `php`, `laravel` and `symfony`.
        On any other application type it answers **404**, which is what the
        dashboard answers for the same site.

        Requires the site to have a backup destination configured; without one
        the answer is 403. Configuring a destination is a dashboard operation —
        backup settings, provider profiles and schedules are not on this surface
        and are not planned for v1.

        Backups are a paid feature. A team on the Free plan answers **402**;
        its existing backups stay listable, restorable and deletable.

        A sleeping site is a 409: its container is down, so the job would be
        dispatched at a machine that cannot answer it. Wake the site first.

        The files half of a backup is taken only for `wp`. A `laravel` or `php`
        site is backed up database-only however its stored settings read, because
        the archive the backup scripts build only understands the WordPress
        layout.
      operationId: createManualBackup
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '202':
          description: The backup is being taken.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/Backup' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403':
          description: |
            The caller may not do this, or the site has no backup destination
            configured.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/sites/{site}/backups/{backup}:
    delete:
      tags: [Site Backups]
      summary: Delete a backup
      description: |
        Removes the archive from the destination as well as the record. The
        provider call is synchronous, so by the time this answers the file is
        gone.

        This is also how a backup stuck in `creating` is cleared. Only one backup
        may be in flight per site, so a run that never finished makes every later
        create and restore a **409** — deleting the row releases it. A watchdog
        sweeps such rows after fifteen minutes if you would rather wait.

        Backups are a database dump plus an archive of a WordPress tree, so this
        endpoint exists only for `wp`, `bedrock`, `php`, `laravel` and `symfony`.
        On any other application type it answers **404**, which is what the
        dashboard answers for the same site.
      operationId: deleteBackup
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/BackupId'
      responses:
        '200':
          description: Deleted.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Message' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/sites/{site}/backups/{backup}/restore:
    post:
      tags: [Site Backups]
      summary: Restore a backup
      description: |
        Puts the site into maintenance mode for the duration and overwrites its
        files and database.

        409 while something is holding the backup — another restore is running, a
        backup is being taken, or **this** backup is still being written. 422 only
        for a backup that finished unsuccessfully, which no amount of waiting will
        change. A sleeping site is also a 409.

        Backups are a database dump plus an archive of a WordPress tree, so this
        endpoint exists only for `wp`, `bedrock`, `php`, `laravel` and `symfony`.
        On any other application type it answers **404**, which is what the
        dashboard answers for the same site.
      operationId: restoreBackup
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/BackupId'
      responses:
        '202':
          description: The restore is queued.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Message' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: |
            The caller may not do this, or the site has no backup destination
            configured.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422':
          description: This backup did not complete successfully and cannot be restored.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/sites/{site}/domains:
    get:
      tags: [Site Domains]
      summary: List domains
      operationId: listDomains
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/PerPage'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Include'
      responses:
        '200':
          description: One page of domains.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/Domain' }
                  links: { $ref: '#/components/schemas/CursorLinks' }
                  meta: { $ref: '#/components/schemas/CursorMeta' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

    post:
      tags: [Site Domains]
      summary: Add a domain
      description: |
        Rewrites the site's vhost, so only one domain write may be in flight at a
        time. A second write while one is running is a `409`.

        **A new domain is promoted when the current primary is a test domain.**
        A site starts life on a `*.flywp.xyz` name, and the first real domain
        added replaces it as the primary whatever `type` the request asked for —
        the old test domain is then removed. Once the site has a real primary,
        `type` is honoured as sent. This is the same rule the dashboard follows.

        **An existing A record at the name is a `422`.** When the domain uses a
        Cloudflare integration (`dns_provider_id`, or the site's own integration
        when the field is not sent) and the zone already has an A record for the
        name (or for `*.name` on a wildcard), the request fails with an error on
        `delete_existing_dns`. Duplicate A records cannot be created. Send it again
        with `delete_existing_dns: true` to delete those records first; FlyWP then
        creates its own. If a delete fails, the request fails with an error on
        `fqdn` that names the records already deleted, and no domain is added. If
        FlyWP manages the record for another site, the request fails with an
        error on `fqdn`: remove the domain from that site first.
      operationId: addDomain
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/DomainWrite'
                - type: object
                  properties:
                    delete_existing_dns:
                      type: boolean
                      description: Delete the existing A records at the name before FlyWP creates its own.
                      default: false
      responses:
        '202':
          description: The domain is being added.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/Domain' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/sites/{site}/domains/{domain}:
    put:
      tags: [Site Domains]
      summary: Update a domain
      description: |
        A replace, not a patch: `fqdn` and `type` are both required, and `PATCH`
        is registered as an alias that behaves identically. A field you omit
        keeps the value it already had — omitting `is_wildcard` does not turn a
        wildcard domain into an ordinary one.

        Sending `type: primary` with a new `fqdn` is how a site is renamed. The
        swap is committed only once the server confirms it, so the current
        primary keeps serving until then.

        A site must always have a primary. Demoting the only one to an alias is a
        **409**, as deleting it is.
      operationId: updateDomain
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/DomainId'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/DomainWrite' }
      responses:
        '202':
          description: The domain is being updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/Domain' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

    patch:
      tags: [Site Domains]
      summary: Update a domain
      description: |
        Identical to `PUT`, including that `fqdn` and `type` are both required.
      operationId: patchDomain
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/DomainId'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/DomainWrite' }
      responses:
        '202':
          description: The domain is being updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/Domain' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

    delete:
      tags: [Site Domains]
      summary: Delete a domain
      description: |
        The primary domain cannot be deleted, and neither can the last remaining
        domain. Both are a **409** naming which rule refused: make another domain
        primary first, and delete this one after.
      operationId: deleteDomain
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/DomainId'
      responses:
        '202':
          description: The domain is being removed.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Message' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/sites/{site}/certificates:
    get:
      tags: [Site Certificates]
      summary: List certificates
      operationId: listCertificates
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/PerPage'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Include'
      responses:
        '200':
          description: One page of certificates.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/Certificate' }
                  links: { $ref: '#/components/schemas/CursorLinks' }
                  meta: { $ref: '#/components/schemas/CursorMeta' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

    post:
      tags: [Site Certificates]
      summary: Request a certificate
      description: |
        Issues a Let's Encrypt certificate for domains already attached to the
        site. Issuing does not activate it — see the activate endpoint.

        Let's Encrypt only. The dashboard can also install a certificate you
        already hold and issue a Cloudflare origin certificate; neither is on
        this surface, and both paths answer 404 here. Uploading a private key
        through an API token and naming an account-wide Cloudflare integration
        are decisions of their own, not a matter of exposing an existing action.
      operationId: addCertificate
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                domain:
                  type: string
                  maxLength: 2048
                  description: |
                    One domain, or several separated by commas. Every one must
                    already be attached to the site.

                    The server asks each domain for a Let's Encrypt challenge
                    token over HTTP before the certificate is created. If a
                    domain does not answer, the request fails with 422, the
                    error names the domain, and no certificate is created. A
                    test domain and a list with a wildcard are not checked.
                    Set `skip_domain_check` to skip this check.
                  example: example.com,www.example.com
                skip_domain_check:
                  type: boolean
                  default: false
                  description: |
                    Skips the check that asks each domain over HTTP. Use it when
                    a firewall blocks the check but lets Let's Encrypt through.

                    If a domain cannot answer the Let's Encrypt challenge, the
                    whole order fails and no domain gets a certificate. Let's
                    Encrypt allows 5 failed validations for each domain in each
                    hour.
                dns_provider:
                  type: ['null', object]
                  description: |
                    Required for a wildcard domain, which can only be validated
                    over DNS.
                  properties:
                    provider:
                      type: string
                      example: cloudflare
                    cloudflare_api_token:
                      type: string
              required: [domain]
      responses:
        '202':
          description: The certificate is being issued and installed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/Certificate' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/sites/{site}/certificates/{certificate}:
    delete:
      tags: [Site Certificates]
      summary: Delete a certificate
      description: |
        Deactivates it first if it is active — synchronously, so the vhost stops
        pointing at files that are about to go — and turns SSL off for the site
        if this was the last active certificate.
      operationId: deleteCertificate
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/CertificateId'
      responses:
        '200':
          description: Deleted.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Message' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/sites/{site}/certificates/{certificate}/activate:
    post:
      tags: [Site Certificates]
      summary: Activate a certificate
      description: |
        Points the site's vhost at this certificate.

        Two refusals, both 409 and both the caller's answer rather than a fault:
        the certificate is already active, or it is not installed yet. The second
        reads `status`, not the activation state — a certificate can be on its
        way in and have no files on the box.
      operationId: activateCertificate
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/CertificateId'
      responses:
        '202':
          description: The certificate is being activated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/Certificate' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409':
          description: Already active, or not installed yet.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/sites/{site}/nginx-config:
    get:
      tags: [Site Configuration]
      summary: Read the nginx vhost
      description: |
        The site's nginx configuration file, as it is on the server.

        nginx sites only. An OpenLiteSpeed site answers 404, because it has no
        nginx vhost — the same answer the dashboard gives. The stack is checked
        after the permission check, so the refusal does not tell a caller which
        web server a site they cannot read is running.
      operationId: showNginxConfig
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '200':
          description: The current configuration.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      config: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

    put:
      tags: [Site Configuration]
      summary: Replace the nginx vhost
      description: |
        Writes the configuration and reloads nginx.

        200, not 202: the reload happens before this answers. If nginx refuses
        the configuration, the answer is 422 and the message is nginx's own
        complaint, which names the line it could not parse. Nothing is left
        half-applied — the script restores the previous file when the reload
        fails.
      operationId: updateNginxConfig
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                config:
                  type: string
                  description: The whole file. This is a replace, not a patch.
              required: [config]
      responses:
        '200':
          description: Written and reloaded.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Message' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/sites/{site}/nginx-config/restore-default:
    post:
      tags: [Site Configuration]
      summary: Restore the nginx vhost to default
      description: |
        Rebuilds the configuration from the same template FlyWP uses when it
        creates a site, then reloads nginx. The body is ignored.
      operationId: restoreNginxConfig
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '200':
          description: Restored and reloaded.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Message' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/sites/{site}/ols-config:
    get:
      tags: [Site Configuration]
      summary: Read an OpenLiteSpeed config file
      description: |
        One of three files, named by `file`.

        OpenLiteSpeed sites only. An nginx site answers 404.

        `exists` is false when the file is not on the server. That is an ordinary
        answer, not an error: `.htaccess` is written by WordPress and by the
        site's own plugins, so a site can be healthy without one.
      operationId: showOlsConfig
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - name: file
          in: query
          required: true
          schema:
            type: string
            enum: [htaccess, vhost, httpd]
      responses:
        '200':
          description: The current contents.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      file: { type: string, enum: [htaccess, vhost, httpd] }
                      content: { type: string }
                      exists: { type: boolean }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

    put:
      tags: [Site Configuration]
      summary: Replace an OpenLiteSpeed config file
      description: |
        Writes the file and restarts OpenLiteSpeed.

        The file must already be on the server. FlyWP changes these files but
        never creates them, because provisioning owns them — a write against a
        file that is not there answers 409 rather than planting one.
      operationId: updateOlsConfig
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                file: { type: string, enum: [htaccess, vhost, httpd] }
                content:
                  type: string
                  description: The whole file. This is a replace, not a patch.
              required: [file, content]
      responses:
        '200':
          description: Written and restarted.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Message' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409':
          description: The file is not on the server. FlyWP will not create it.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/sites/{site}/ols-config/restore-default:
    post:
      tags: [Site Configuration]
      summary: Restore an OpenLiteSpeed config file to default
      description: |
        Rebuilds the file from the same template FlyWP uses when it creates a
        site, then restarts OpenLiteSpeed.

        `vhost` and `httpd` only. `.htaccess` answers 422, because FlyWP has no
        default for it: WordPress and the site's own plugins write that file, so
        a "default" would be an invention that deletes rules the application
        needs.
      operationId: restoreOlsConfig
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                file: { type: string, enum: [vhost, httpd] }
              required: [file]
      responses:
        '200':
          description: Restored and restarted.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Message' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409':
          description: The file is not on the server. FlyWP will not create it.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/sites/{site}/wp-config:
    get:
      tags: [Site Configuration]
      summary: Read the managed wp-config constants
      description: |
        The seven constants FlyWP manages, and nothing else.

        **This endpoint does not return `wp-config.php`.** That file holds
        `FLYWP_API_KEY` and the database password, and there is no endpoint on
        this API that reads or writes it whole. Anything else in the file belongs
        to the site and FlyWP leaves it alone.

        WordPress sites only. Any other application type answers 403.
      operationId: showWpConfig
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '200':
          description: The managed constants.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/WpConfig' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

    put:
      tags: [Site Configuration]
      summary: Change the managed wp-config constants
      description: |
        All seven fields are required. FlyWP stores them, then writes those lines
        into `wp-config.php` on the server.

        202, because the write to the file is queued. The values in the answer
        are what FlyWP now holds.
      operationId: updateWpConfig
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/WpConfig' }
      responses:
        '202':
          description: Stored, and being written to the server.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/WpConfig' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/sites/{site}/static-site:
    get:
      tags: [Site Static Site]
      summary: Read the static site
      description: |
        `404` when the site has no static site, or is not a WordPress site.
      operationId: showStaticSite
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '200':
          description: The static site.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/StaticSite' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

    post:
      tags: [Site Static Site]
      summary: Set up the static site
      description: |
        Checks the destination, then starts the setup. The setup runs the first
        deploy. Poll the static site until its status is `active` or `failed`.

        `409` when the site cannot have a static site now: the site is not
        active, it already has a static site, WooCommerce is active, or the
        destination check fails.
      operationId: createStaticSite
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/StaticSiteWrite' }
      responses:
        '202':
          description: The setup has started.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/StaticSite' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

    delete:
      tags: [Site Static Site]
      summary: Remove the static site
      description: |
        Disconnects the static domain, deletes the DNS record that FlyWP or
        Cloudflare added for it, and deletes the static site. The files at the
        destination and your other DNS records stay. WordPress does not change.

        `409` while the setup or a deploy runs.
      operationId: deleteStaticSite
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '200':
          description: Removed.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Message' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/sites/{site}/static-site/retry:
    post:
      tags: [Site Static Site]
      summary: Retry a failed setup
      description: |
        `409` when the setup did not fail, or while a deploy runs.
      operationId: retryStaticSiteSetup
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '202':
          description: The setup runs again.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/StaticSite' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/sites/{site}/static-site/destination-check:
    post:
      tags: [Site Static Site]
      summary: Check a destination before the setup
      description: |
        Runs the same destination checks as the setup, and changes nothing. A
        failed check is `200` with `passed` false and the reason in `message`.
      operationId: checkStaticSiteDestination
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/StaticSiteWrite' }
      responses:
        '200':
          description: The result of the check.
          content:
            application/json:
              schema:
                type: object
                properties:
                  passed: { type: boolean }
                  message: { type: ['null', string] }
                required: [passed, message]
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/sites/{site}/static-site/settings:
    put:
      tags: [Site Static Site]
      summary: Change the S3 bucket and region
      description: |
        Only an `s3` destination has settings to change. Any other destination
        answers `409`. `409` also while the setup or a deploy runs, and for an
        Amazon S3 region change.
      operationId: updateStaticSiteSettings
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [bucket]
              properties:
                bucket: { type: string }
                region: { type: string, description: 'Required for providers that need a region.' }
      responses:
        '200':
          description: The settings are saved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/StaticSite' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/sites/{site}/static-site/deployments:
    get:
      tags: [Site Static Site]
      summary: List static deploys
      description: |
        Newest first. This listing takes `per_page` and `cursor` only. It never
        contains the deploy log.
      operationId: listStaticSiteDeployments
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/PerPage'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: One page of deploys.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/StaticSiteDeployment' }
                  links: { $ref: '#/components/schemas/CursorLinks' }
                  meta: { $ref: '#/components/schemas/CursorMeta' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

    post:
      tags: [Site Static Site]
      summary: Start a static deploy
      description: |
        `409` until the static site is `active`, and while a deploy runs.
      operationId: createStaticSiteDeployment
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                mode:
                  type: string
                  enum: [full, incremental]
                  default: incremental
      responses:
        '202':
          description: The deploy has started.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/StaticSiteDeployment' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/sites/{site}/static-site/deployments/{deployment}:
    get:
      tags: [Site Static Site]
      summary: Read one static deploy
      description: |
        `log_tail` is only in the answer for a caller with `site:update`. The
        log shows server paths and command output.
      operationId: showStaticSiteDeployment
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/StaticSiteDeploymentId'
      responses:
        '200':
          description: The deploy.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/StaticSiteDeployment' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/bulk-actions/preview:
    post:
      tags: [Bulk Actions]
      summary: Preview a bulk action
      description: |
        Resolves the selection the way a start would — visibility, the per-site gate and
        the operation's eligibility — and reports the count that would run and the sites
        left out, with a reason each. Writes nothing.
      operationId: previewBulkAction
      parameters:
        - $ref: '#/components/parameters/TeamId'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/BulkActionWrite' }
      responses:
        '200':
          description: The preview.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BulkActionPreview' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/bulk-actions:
    post:
      tags: [Bulk Actions]
      summary: Start a bulk action
      description: |
        One operation on many sites. The run is created with one item per site and
        answered at once; the work happens on the queue. Poll the run until `status`
        is final. A site the user may not change, or that the operation cannot use, is
        an item `skipped` with a reason — the request does not fail as a whole.

        An operation that changes the bill asks for `manage-billing`. With an API key, only
        a full-access key of the team owner holds it: a key with selected abilities, or a
        member's key, is a `403`.

        One run per operation per team at a time: a second start while one is
        `processing` is a `409`.
      operationId: startBulkAction
      parameters:
        - $ref: '#/components/parameters/TeamId'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/BulkActionWrite' }
      responses:
        '201':
          description: The run, with its items.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BulkAction' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/bulk-actions/{bulkAction}:
    get:
      tags: [Bulk Actions]
      summary: Show a bulk action
      operationId: showBulkAction
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/BulkActionId'
      responses:
        '200':
          description: The run, with its items and live counts.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BulkAction' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/bulk-actions/{bulkAction}/cancel:
    post:
      tags: [Bulk Actions]
      summary: Cancel a bulk action
      description: |
        Stops the sites that did not start: their items become `cancelled`. A site that
        is running finishes; its work is not undone. When no site is still running, the
        run is `cancelled` at once. Otherwise it becomes `cancelled` when the last running
        site ends. A run that already finished is answered as it is.

        The member who started the run, or a member who can manage the team.
      operationId: cancelBulkAction
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/BulkActionId'
      responses:
        '200':
          description: The run, with its items and live counts.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BulkAction' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/bulk-actions/{bulkAction}/retry/preview:
    post:
      tags: [Bulk Actions]
      summary: Preview a retry
      description: |
        What a retry would run: the `failed` sites of a finished run, with the same
        operation and options, checked again. A sensitive retry needs its
        `eligible_count` as `confirm`. Writes nothing.
      operationId: previewRetryBulkAction
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/BulkActionId'
      responses:
        '200':
          description: The preview.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BulkActionPreview' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/bulk-actions/{bulkAction}/retry:
    post:
      tags: [Bulk Actions]
      summary: Retry the failed sites of a bulk action
      description: |
        Starts a new run from the `failed` sites of a finished run, with the same
        operation and options. The server picks the sites. Each one is checked again; a
        site that is no longer eligible is `skipped` with a reason.

        The member who started the run, or a member who can manage the team. An
        operation that changes the bill still needs `manage-billing`. A run that is still
        `processing` is a `409`. A run with no failed site, or a run that was already
        retried, is a `422`: retry the newer run instead.
      operationId: retryBulkAction
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/BulkActionId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                confirm:
                  type: ['null', integer]
                  description: |
                    Required when the retry preview says `sensitive: true`. Send its `eligible_count`.
      responses:
        '201':
          description: The new run, with its items.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BulkAction' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/white-label/plans:
    get:
      tags: [White Label Plans]
      security:
        - whiteLabelKey: []
      summary: List the published plans
      description: |
        The plans a customer may be put on, cheapest first. Map each of your own
        products to a `sku`: it is the stable identifier, chosen by the reseller,
        and the only one to store. Numeric ids are FlyWP's own and may not be
        meaningful to your system.

        Only published plans appear. A plan the reseller pauses stops appearing
        here and stops being accepted on a create, so a product mapped to it
        starts answering `422` rather than selling something that cannot be built.
      operationId: whiteLabelListPlans
      responses:
        '200':
          description: Every published plan.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/WhiteLabelPlan' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/WhiteLabelForbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }

  /v1/white-label/customers:
    get:
      tags: [White Label Customers]
      security:
        - whiteLabelKey: []
      summary: List customers
      description: |
        Your customers, newest first, 25 to a page. Send `per_page` for a different page size: below 1
        counts as 1, above 100 as 100. `links.next` keeps the same `per_page`.

        Filter by `external_id` to find the one your own system knows about.
      operationId: whiteLabelListCustomers
      parameters:
        - name: external_id
          in: query
          required: false
          description: Your own identifier for the customer, matched exactly.
          schema: { type: string }
        - name: status
          in: query
          required: false
          schema: { $ref: '#/components/schemas/WhiteLabelCustomerStatus' }
        - name: page
          in: query
          required: false
          schema: { type: integer, minimum: 1, default: 1 }
        - name: per_page
          in: query
          required: false
          description: Customers on each page. Clamped to 1 to 100.
          schema: { type: integer, minimum: 1, maximum: 100, default: 25 }
      responses:
        '200':
          description: A page of customers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/WhiteLabelCustomer' }
                  links: { type: object }
                  meta: { type: object }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/WhiteLabelForbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }

    post:
      tags: [White Label Customers]
      security:
        - whiteLabelKey: []
      summary: Create a customer
      description: |
        Makes a customer active because your system already took the money.
        FlyWP charges nobody on this path.

        **Safe to retry.** `external_id` is your idempotency key: repeat the same
        request and you get `200` with the customer the first attempt made,
        never a second customer. Only the same `external_id` under a *different*
        email is a clash, and that answers `409` with code `external_id_taken`.

        No site is created here. Create one separately once you have the
        customer, so a failure to build a site never costs you the account.
      operationId: whiteLabelCreateCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [external_id, name, email, password, plan_sku]
              properties:
                external_id:
                  type: string
                  maxLength: 120
                  description: Your own identifier. Unique among your customers.
                name: { type: string, maxLength: 255 }
                email:
                  type: string
                  format: email
                  maxLength: 255
                  description: |
                    Lowercased before it is stored. Unique among your customers
                    only: the same address may belong to another reseller's
                    customer, and to a direct FlyWP account.
                password:
                  type: string
                  minLength: 8
                  maxLength: 64
                  description: What the customer signs in with at `login_url`.
                plan_sku:
                  type: string
                  description: The product code of a published plan.
              example:
                external_id: 'wc-1042'
                name: 'Ada Lovelace'
                email: 'ada@example.com'
                password: 'correct-horse-battery'
                plan_sku: 'ACME-STARTER'
      responses:
        '200':
          description: |
            This `external_id` already names this customer. The first attempt
            worked; nothing was created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/WhiteLabelCustomer'
        '201':
          description: The customer, active.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/WhiteLabelCustomer'
              example:
                data:
                  id: 4821
                  external_id: wc-1042
                  name: Ada Lovelace
                  email: ada@example.com
                  status: active
                  plan:
                    id: 17
                    sku: ACME-STARTER
                    name: Starter
                  price: 2900
                  site_limit: 3
                  sites_used: 0
                  login_url: https://acme.flywp.xyz/login
                  activated_at: '2026-09-17T09:14:22+00:00'
                  cancelled_at: null
                  created_at: '2026-09-17T09:14:22+00:00'
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/WhiteLabelForbidden' }
        '409': { $ref: '#/components/responses/WhiteLabelRefused' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }

  /v1/white-label/customers/{client}:
    parameters:
      - $ref: '#/components/parameters/WhiteLabelClientId'
    get:
      tags: [White Label Customers]
      security:
        - whiteLabelKey: []
      summary: Get a customer
      description: The customer and their sites. A customer of another reseller is a `404`.
      operationId: whiteLabelGetCustomer
      responses:
        '200':
          description: The customer, with `sites` included.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/WhiteLabelCustomer' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/WhiteLabelForbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
    put:
      tags: [White Label Customers]
      security:
        - whiteLabelKey: []
      summary: Change a customer's plan, name or email
      description: |
        Send `plan_sku` to move the customer to another plan, and `name` or
        `email` to correct their details. All are optional; sending the plan they are on already
        changes nothing, so a billing system that re-sends the package on every
        change is safe to point here.

        A customer who pays through the reseller's own website is refused with
        `422`: their subscription lives in Stripe, and moving them is the
        reseller's call from the dashboard, where proration is chosen.

        A move is also refused with `422` on `plan_sku` when their sites run on
        another kind of server than the new plan (`server_kind`; sites never
        move), or when the new plan is `sold_out` and they have no site yet.
      operationId: whiteLabelUpdateCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/WhiteLabelCustomerUpdate' }
      responses:
        '200':
          description: The customer as they now are.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/WhiteLabelCustomer' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/WhiteLabelForbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/WhiteLabelRefused' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
    patch:
      tags: [White Label Customers]
      security:
        - whiteLabelKey: []
      summary: Change a customer's plan, name or email
      description: Identical to `PUT`.
      operationId: whiteLabelPatchCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/WhiteLabelCustomerUpdate' }
      responses:
        '200':
          description: The customer as they now are.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/WhiteLabelCustomer' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/WhiteLabelForbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/WhiteLabelRefused' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
    delete:
      tags: [White Label Customers]
      security:
        - whiteLabelKey: []
      summary: End a customer
      description: |
        Ends the customer. With no body this means now, and deletes every site
        of theirs.

        `sites` chooses what happens to their sites.

        **`timing: period_end` is refused for a customer created through this
        API**, with `422` on `timing`. It works by moving a Stripe subscription,
        and a customer your system billed has none. Implement "cancel at period
        end" by holding this call until the period ends.

        No money is refunded either way; that is the reseller's call.

        This endpoint answers even after the reseller's own subscription has
        lapsed. Stopping money must always work.
      operationId: whiteLabelTerminateCustomer
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                timing:
                  type: string
                  enum: [now, period_end]
                  default: now
                  description: |
                    `period_end` is refused for customers created through this
                    API. See above.
                sites:
                  type: string
                  enum: [delete, sleep]
                  default: delete
                  description: |
                    `sleep` keeps the sites for the grace period an admin
                    configures, in case the customer comes back.
      responses:
        '200':
          description: The customer, ended.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/WhiteLabelCustomer' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/WhiteLabelForbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }

  /v1/white-label/customers/{client}/suspend:
    parameters:
      - $ref: '#/components/parameters/WhiteLabelClientId'
    post:
      tags: [White Label Customers]
      security:
        - whiteLabelKey: []
      summary: Suspend a customer
      description: |
        For a renewal your system could not collect. Their sites stop serving and
        they cannot sign in; nothing is deleted.

        Safe to call on a customer who is already suspended. A customer who was
        never activated, or who has been ended, is refused with `422`.

        `billing` is for a customer who pays on the reseller's website: `keep`
        (the default) keeps charging them, `pause` stops charging them until they
        are unsuspended, and their invoices in between are voided. A customer
        billed by your own system ignores it. A pause the reseller made in their
        own Stripe dashboard stays as it is, and `keep` never lifts a pause.
        Unsuspend starts billing paused here again.
      operationId: whiteLabelSuspendCustomer
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                billing:
                  type: string
                  enum: [keep, pause]
                  default: keep
      responses:
        '200':
          description: The customer, suspended.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/WhiteLabelCustomer' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/WhiteLabelForbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/WhiteLabelRefused' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }

  /v1/white-label/customers/{client}/unsuspend:
    parameters:
      - $ref: '#/components/parameters/WhiteLabelClientId'
    post:
      tags: [White Label Customers]
      security:
        - whiteLabelKey: []
      summary: Unsuspend a customer
      description: |
        Puts a suspended customer back, and is safe to call on one who is
        already active. A customer who is past due, never activated or ended is
        refused with `422`: there is no suspension to lift.

        Billing paused with the suspend starts again. If Stripe refuses that,
        the customer stays suspended and the answer is `422`. If the reseller's
        Stripe account is not connected, the pause stays on Stripe:
        `billing_paused_by` then reads `dashboard`, and only the reseller can
        lift it, in their Stripe dashboard.
      operationId: whiteLabelUnsuspendCustomer
      responses:
        '200':
          description: The customer, active again.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/WhiteLabelCustomer' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/WhiteLabelForbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/WhiteLabelRefused' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }

  /v1/white-label/customers/{client}/sites:
    parameters:
      - $ref: '#/components/parameters/WhiteLabelClientId'
    get:
      tags: [White Label Customer Sites]
      security:
        - whiteLabelKey: []
      summary: List a customer's sites
      description: Every site this customer has, newest first. Not paged.
      operationId: whiteLabelListCustomerSites
      responses:
        '200':
          description: The customer's sites.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/WhiteLabelCustomerSite' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/WhiteLabelForbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
    post:
      tags: [White Label Customer Sites]
      security:
        - whiteLabelKey: []
      summary: Create a site for a customer
      description: |
        The same site the customer could ask for themselves, asked for on their
        behalf, on their plan's pool of servers.

        **A `201` is not a finished site.** Building one takes minutes. The site
        comes back with a `status` and a `progress`, and it is ready when
        `progress` reads `ready`. There is no callback, so poll this customer's
        sites until it does, on a schedule of your own rather than inside the
        request that sold it.

        **Send an `external_id` and this call becomes safe to retry.** It is your
        own reference for the site, unique among that customer's sites. Repeat a
        request carrying one and you get `200` with the site the first attempt
        made. Without one, a retry after a timeout
        makes a second site at a second address and takes another slot from the
        customer's limit, and nothing tells you.

        **A `202` means nothing is wrong and nothing exists yet.** The plan's
        pool had no room, so a server is being prepared. Send the same request
        again after `Retry-After` seconds; it will answer `201` once there is
        somewhere to put the site. This call never waits for a machine to be
        launched.

        It does check the DNS of a `domain` you supply, which is a network call
        of a second or two. Run it from a background job either way.

        `stack` and `php_version` must be ones the plan offers — read them from
        `GET /v1/white-label/plans`. Leave them out to take the plan's own.

        The plan's `site_limit` is enforced here: a customer who has used every
        site their plan includes is refused with `422`.

        A customer gets one new site at a time. A create that arrives while
        another create or a site move for the same customer runs waits up to
        30 seconds, then is refused with `409 site_in_progress`. Send it again
        shortly. With the same `external_id`, you get the first site back.

        A plan on the reseller's own servers never adds a server. When they are
        full, a further site is refused with `409 plan_sold_out`. A customer's
        first site always has a place kept for it.
      operationId: whiteLabelCreateCustomerSite
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [site_title, admin_username, admin_password]
              properties:
                external_id:
                  type: string
                  maxLength: 120
                  description: |
                    Your own reference for this site, unique among this
                    customer's sites. Optional, and the only way to retry
                    safely — send one from anything automated.
                  example: wc-order-1042
                site_title: { type: string, maxLength: 255 }
                domain:
                  type: string
                  maxLength: 253
                  description: |
                    The customer's own domain. Leave it out and FlyWP gives the
                    site an address under the reseller's own.
                admin_username:
                  type: string
                  maxLength: 60
                  description: The WordPress administrator. Letters, numbers, dashes and underscores.
                admin_password:
                  type: string
                  minLength: 12
                  description: 'Letters, numbers and any of: - _ ! @ # % &'
                stack: { type: string, enum: [nginx, openlitespeed] }
                php_version: { type: string, maxLength: 3, example: '8.3' }
              example:
                external_id: 'wc-order-1042'
                site_title: "Ada's Shop"
                domain: 'shop.example.com'
                admin_username: 'ada'
                admin_password: 'correct-horse-8'
      responses:
        '200':
          description: |
            This `external_id` already names a site for this customer. The first
            attempt worked; nothing was created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/WhiteLabelCustomerSite'
        '202':
          description: |
            Accepted, and nothing created yet: a server is being prepared for
            this site. Send the same request again after `Retry-After` seconds.
          headers:
            Retry-After:
              description: Seconds to wait before sending the request again.
              schema:
                type: integer
                example: 60
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  code:
                    type: string
                    example: pool_growing
                  retry_after:
                    type: integer
                    example: 60
              example:
                message: Accepted. A server is being prepared for this site; send this request again shortly.
                code: pool_growing
                retry_after: 60
        '201':
          description: |
            Created and being built. `progress` is `provisioning` or
            `waiting_for_server`, not `ready`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/WhiteLabelCustomerSite'
              example:
                data:
                  id: 9310
                  external_id: wc-order-1042
                  domain: shop.example.com
                  status: creating
                  progress: waiting_for_server
                  failure_reason: null
                  dns_target: null
                  stack: nginx
                  php_version: '8.3'
                  ssl_enabled: false
                  created_at: '2026-09-17T09:16:04+00:00'
                  updated_at: '2026-09-17T09:16:04+00:00'
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/WhiteLabelForbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/WhiteLabelRefused' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }

  /v1/white-label/customers/{client}/sites/{site}:
    parameters:
      - $ref: '#/components/parameters/WhiteLabelClientId'
      - name: site
        in: path
        required: true
        schema: { type: integer }
    delete:
      tags: [White Label Customer Sites]
      security:
        - whiteLabelKey: []
      summary: Delete a customer's site
      description: |
        Deletes the site and everything on it. Answers `200` with the site at
        `deleting`, and `409` if it is already on its way out.

        This endpoint answers even after the reseller's own subscription has
        lapsed: a removal is not new work.
      operationId: whiteLabelDeleteCustomerSite
      responses:
        '200':
          description: The site, being deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/WhiteLabelCustomerSite' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/WhiteLabelForbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/WhiteLabelRefused' }
        '429': { $ref: '#/components/responses/TooManyRequests' }

  /v1/white-label/customers/{client}/site-moves:
    parameters:
      - $ref: '#/components/parameters/WhiteLabelClientId'
    post:
      tags: [White Label Customer Sites]
      security:
        - whiteLabelKey: []
      summary: Move one of the team's sites to a customer
      description: |
        One of the team's own sites becomes this customer's, the same as a site
        they made: it counts toward their plan's `site_limit`, they can manage
        it, it has the reseller's brand, and it sleeps and is deleted with their
        other sites if they are cancelled. The customer gets an email.

        - Only an active WordPress site that is no customer's can move, and only
          to a customer who is active or behind on payment and not leaving.
        - A move past the plan's `site_limit` is refused with `422`.
        - A site that deploys from Git cannot move: its Git connection belongs to
          a person on the team.
        - The person who made the key must be able to change the site in the
          dashboard; otherwise `403`.
        - The team's backup storage and email relay come off the site.
        - A site on a FlyWP test address gets a free address under the reseller's
          own domain. The site moves at once, and the new address follows in a
          few minutes. A team with no free addresses set up is refused with `422`.

        Answers `200` with the site, now the customer's.
      operationId: whiteLabelMoveSiteToCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [site_id]
              properties:
                site_id:
                  type: integer
                  description: The site's id, as the Public API's `GET /v1/sites` gives it.
                  example: 9310
                external_id:
                  type: string
                  maxLength: 120
                  description: Your own reference for this site, unique among this customer's sites. Optional.
                  example: wc-order-1042
      responses:
        '200':
          description: The site, now the customer's.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/WhiteLabelCustomerSite' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/WhiteLabelForbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }

  /v1/white-label/customers/{client}/site-moves/{site}:
    parameters:
      - $ref: '#/components/parameters/WhiteLabelClientId'
      - name: site
        in: path
        required: true
        schema: { type: integer }
    delete:
      tags: [White Label Customer Sites]
      security:
        - whiteLabelKey: []
      summary: Move a customer's site back to the team
      description: |
        The site becomes the team's own again. The customer can no longer manage
        it, it no longer counts toward their plan, and the reseller's brand comes
        off it. Their backup storage and email relay come off it too. A site that
        sleeps wakes up.

        Refused with `422` while the site is being made, changed or deleted, and
        while it sleeps for the reseller's unpaid FlyWP bill. The person who made
        the key must be able to change the site in the dashboard; otherwise `403`.
      operationId: whiteLabelMoveSiteToTeam
      responses:
        '200':
          description: The site, now the team's own.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/WhiteLabelCustomerSite' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/WhiteLabelForbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }

  /v1/white-label/fees:
    get:
      tags: [White Label Fees]
      security:
        - whiteLabelKey: []
      summary: FlyWP's fees for a month
      description: |
        Every fee FlyWP charged the reseller in one month, to reconcile it: the
        statement, summed by how each fee was collected (`connect`: taken by
        Stripe from a sale on the reseller's website; `invoice`: billed on the
        reseller's FlyWP invoice), kind and currency, and every fee in it, 100 at
        a time. A credit is negative. Open to a reseller whose subscription
        lapsed: they still pay fees.
      operationId: whiteLabelFees
      parameters:
        - name: month
          in: query
          required: false
          description: The month, as `YYYY-MM`. The current month when left out.
          schema: { type: string, example: '2026-09' }
        - name: page
          in: query
          required: false
          description: The page of `rows`, from 1.
          schema: { type: integer, minimum: 1 }
      responses:
        '200':
          description: The month's statement and a page of its fees.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      month: { type: string, example: '2026-09' }
                      lines:
                        type: array
                        items:
                          type: object
                          properties:
                            collection: { type: string, enum: [connect, invoice] }
                            kind:
                              type: string
                              enum: [sale, refund, dispute, dispute_retake, api_customer, shortfall, bypass, server_credit, disconnect_credit, manual]
                              description: |
                                What happened: one kind per event. `sale` is FlyWP's fee on a website
                                sale; `refund` and `dispute` give a fee back; `dispute_retake` takes
                                it again after a won dispute. Where the fee was collected is
                                `collection`.
                              example: sale
                            label: { type: string, example: 'FlyWP fee: website sales' }
                            count: { type: integer }
                            amount: { type: integer, description: Cents; a credit is negative. }
                            currency: { type: string, example: USD }
                      totals:
                        type: object
                        description: Cents by currency. What the reseller owes FlyWP when positive.
                        additionalProperties: { type: integer }
                      rows:
                        type: array
                        items:
                          type: object
                          properties:
                            id: { type: integer }
                            occurred_at: { type: string, format: date-time }
                            kind: { type: string, enum: [sale, refund, dispute, dispute_retake, api_customer, shortfall, bypass, server_credit, disconnect_credit, manual] }
                            label: { type: string }
                            collection: { type: string, enum: [connect, invoice] }
                            amount: { type: integer }
                            currency: { type: string }
                            customer:
                              type: ['null', object]
                              properties:
                                id: { type: integer }
                                name: { type: ['null', string] }
                            reference:
                              type: string
                              description: |
                                The Stripe id of a fee Stripe took or refunded; FlyWP's own
                                reference for a fee billed on the invoice.
                            note:
                              type: ['null', string]
                              description: Why, for a fee FlyWP adjusted by hand.
                            invoiced_at: { type: ['null', string], format: date-time }
                            settled_at: { type: ['null', string], format: date-time }
                  links:
                    type: object
                    properties:
                      next: { type: ['null', string], description: The next page of rows. }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/WhiteLabelForbidden' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }

  /v1/white-label/health:
    get:
      tags: [White Label Plans]
      security:
        - whiteLabelKey: []
      summary: Would a sale right now be provisioned?
      description: |
        Use this for a "test connection" check. It answers whether a sale placed
        this minute would actually be provisioned, not merely whether the key is
        valid.

        `200` means yes, with what a module needs to warn on: how many plans are
        published, how close the reseller is to their customer limit, and when this
        key expires. Any other status means a sale would not be provisioned right
        now, and its `code` says why.
      operationId: whiteLabelHealth
      responses:
        '200':
          description: This key can provision right now.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      business_name:
                        type: ['null', string]
                        example: Acme Hosting
                      plans_on_sale:
                        type: integer
                        example: 3
                      customers_allowed:
                        type: ['null', integer]
                        description: Null means no cap. Warn before it, not after.
                        example: 50
                      customers_live:
                        type: integer
                        example: 12
                      plans_sold_out:
                        type: array
                        items: { type: string }
                        description: |
                          The product codes of the plans `GET /plans` marks `sold_out`:
                          a create on one is refused. The plan has no room (`409
                          plan_sold_out`), or a create on it is refused for another reason
                          (that reason's code). The plans in `plans_fee_not_accepted` are
                          here too.
                        example: []
                      plans_fee_not_accepted:
                        type: array
                        items: { type: string }
                        description: |
                          The product codes of plans whose FlyWP fee the reseller's owner
                          has not accepted yet. A create on one answers
                          `409 fee_terms_not_accepted`. When every plan is here, the
                          check itself answers that code.
                        example: []
                      key_expires_at:
                        type: ['null', string]
                        format: date-time
                        description: |
                          When this key stops working. A key is minted for at
                          most a year and there is no rotate endpoint, so warn
                          the reseller well before this date.
                        example: '2027-09-17T00:00:00+00:00'
                      temporary_addresses:
                        type: boolean
                        description: |
                          Whether a site can be made with no `domain`: the reseller
                          turned on free addresses under their own domain. When false,
                          `POST /customers/{client}/sites` needs a `domain`, so ask the
                          buyer for one at checkout.
                        example: true
              example:
                data:
                  business_name: Acme Hosting
                  plans_on_sale: 3
                  customers_allowed: 50
                  customers_live: 12
                  plans_sold_out: []
                  plans_fee_not_accepted: []
                  key_expires_at: '2027-09-17T00:00:00+00:00'
                  temporary_addresses: true
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/WhiteLabelForbidden' }
        '409': { $ref: '#/components/responses/WhiteLabelRefused' }
        '429': { $ref: '#/components/responses/TooManyRequests' }

  /v1/white-label/customers/{client}/reactivate:
    parameters:
      - $ref: '#/components/parameters/WhiteLabelClientId'
    post:
      tags: [White Label Customers]
      security:
        - whiteLabelKey: []
      summary: Take a cancelled customer back
      description: |
        Use this when a customer you ended comes back. Their `external_id` and
        their email address stay theirs after they are ended, so put the same
        customer back rather than creating a new one. The reseller keeps their
        history that way too.

        They come back on today's terms: the plan you name, at its current price
        and site limit. Sites the cancellation deleted are gone; sites it left
        asleep are woken here. Nothing is rebuilt, because nothing here knows
        what they had.

        Safe to call twice: a customer who is already active is answered `200`
        and left alone.
      operationId: whiteLabelReactivateCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [plan_sku]
              properties:
                plan_sku:
                  type: string
                  description: The product code of a published plan.
                  example: ACME-STARTER
            example:
              plan_sku: ACME-STARTER
      responses:
        '200':
          description: The customer, active again.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/WhiteLabelCustomer'
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/WhiteLabelForbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/WhiteLabelRefused' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }

  /v1/white-label/customers/{client}/bandwidth-lift:
    parameters:
      - $ref: '#/components/parameters/WhiteLabelClientId'
    post:
      tags: [White Label Customers]
      security:
        - whiteLabelKey: []
      summary: Lift a customer's bandwidth limit for the month
      description: |
        Their sites run at full speed again until the month ends, also when
        they send more. It takes up to 5 minutes to reach the servers. The
        limit counts again on the 1st of the next month (UTC).

        Safe to call before the limit is reached: then no limit starts this
        month. The answer has the customer with `usage`, so
        `usage.bandwidth_limited_at` reads `null`.
      operationId: whiteLabelLiftCustomerBandwidth
      responses:
        '200':
          description: The customer, with no bandwidth limit for the rest of the month.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/WhiteLabelCustomer' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/WhiteLabelForbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/WhiteLabelRefused' }
        '429': { $ref: '#/components/responses/TooManyRequests' }

  /v1/white-label/customers/{client}/login-link:
    parameters:
      - $ref: '#/components/parameters/WhiteLabelClientId'
    post:
      tags: [White Label Customers]
      security:
        - whiteLabelKey: []
      summary: Mint a one-time sign-in link
      description: |
        A single-use URL that signs this customer into their own dashboard, for
        the client area of the system that sold them. It saves asking them for a
        password they set somewhere else.

        Treat the URL as a credential, and build the client area around three
        limits:

        - **One use.** It is spent the moment it is followed. Do not store it,
          and do not put it in a page a second person might reload.
        - **Five minutes.** Mint it when the customer clicks, not when the page
          renders.
        - **That customer's own account only.** It is not an administrator door.
          A suspended or cancelled customer is refused with `422`.

        A link minted for one reseller's customer does nothing on another
        reseller's address.
      operationId: whiteLabelMintLoginLink
      responses:
        '201':
          description: A link, and the moment it stops working.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      url:
                        type: string
                        example: https://acme.flywp.xyz/sso/0Zx9...
                      expires_at:
                        type: string
                        format: date-time
                        example: '2026-09-17T09:21:04+00:00'
              example:
                data:
                  url: https://acme.flywp.xyz/sso/0Zx9kQ2m
                  expires_at: '2026-09-17T09:21:04+00:00'
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/WhiteLabelForbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/WhiteLabelRefused' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }

  /v1/compose-templates:
    get:
      tags: [Compose Apps]
      summary: List the templates
      description: |
        The catalogue: each template with its settings, the secrets that FlyWP makes (by name), its minimum resources and its licence. Scope `compose:read`.
      operationId: listComposeTemplates
      parameters:
        - $ref: '#/components/parameters/TeamId'
      responses:
        '200':
          description: List the templates.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { type: object } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps:
    get:
      tags: [Compose Apps]
      summary: List the compose apps
      description: |
        The compose apps that the token can see, newest first. Takes `filter[server_id]`, `filter[status]`, `per_page` and `cursor`. Scope `compose:read`.
      operationId: listComposeApps
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/PerPage'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: List the compose apps.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/ComposeApp' } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps/{site}:
    get:
      tags: [Compose Apps]
      summary: Get a compose app
      description: |
        Its status, server, test domain, the version that runs, and its template. Scope `compose:read`.
      operationId: getComposeApp
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '200':
          description: Get a compose app.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/ComposeApp' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    delete:
      tags: [Compose Apps]
      summary: Delete the app
      description: |
        Removes the app and its data from the server. Send `name`, the name of the app, as in the dashboard. Also on the Free plan. Scope `compose:manage`; Owner or Admin.
      operationId: deleteComposeApp
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string }
      responses:
        '202':
          description: Delete the app.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps/{site}/clone:
    post:
      tags: [Compose Apps]
      summary: Clone the app
      description: |
        A second, independent copy of the app with its data, on a server of the team (the same server too): the version that runs, its settings and secrets, its limits and its exact images, with a new test domain. The app keeps running; the services that hold data stop for a moment while FlyWP copies it, and its deploys and actions wait for the copy. The answer is the new app: `clone.step` is the progress (`done` or `failed`; a failed clone removes the new app). The checks of a create run first (`409` with the reason). At most 10 creates and clones an hour for each team, one at a time. Scope `compose:move`; Owner or Admin.
      operationId: cloneComposeApp
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [server_id]
              properties:
                server_id: { type: integer }
                name: { type: string, maxLength: 60, description: 'Default: "<name> (copy)". A number is added when the name is taken on the server.' }
      responses:
        '202':
          description: Clone the app.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/ComposeApp' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps/{site}/clone/targets:
    get:
      tags: [Compose Apps]
      summary: List the servers for a clone
      description: |
        The servers of the team, and for each one the memory that it has for the app and why the clone cannot go there now (`blocked`). The same server is in the list (`same`). `refused` says why the app cannot be cloned at all. As the Clone page. Scope `compose:move`; Owner or Admin.
      operationId: listComposeCloneTargets
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '200':
          description: List the servers for a clone.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: object, properties: { name: { type: string, description: 'The name of the new app when the request gives none.' }, need_mb: { type: integer }, refused: { type: [string, 'null'] }, stops: { type: array, items: { type: string }, description: 'The services that stop while FlyWP copies their data.' }, last_pause_seconds: { type: [integer, 'null'] }, servers: { type: array, items: { type: object, properties: { id: { type: integer }, name: { type: string }, ip_address: { type: [string, 'null'] }, is_managed: { type: boolean }, same: { type: boolean }, room_mb: { type: [integer, 'null'] }, blocked: { type: [string, 'null'], description: 'Why the app cannot go to the server now. Null: it can.' }, provider: { type: [string, 'null'], description: 'The slug of the cloud of the server, for its logo.' } } } } } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }


  /v1/compose-apps/{site}/transfer:
    post:
      tags: [Compose Apps]
      summary: Transfer the app to another server
      description: |
        The same app moves to another server of the team, with its data, settings, domains, certificates, backups and history; its id stays. The app stops at the start of the copy and is down until it starts on the new server. FlyWP moves the record of its test domain, when it has one; point each other domain (`transfer.point_domains`) to the new server (`transfer.to_ip`) with an A record. After the transfer the stopped copy stays on the old server for 24 hours (`transfer.kept_until`): move the app back, or remove the copy. If a step fails, the app starts again on its old server (when the old server is gone, the app stays on the new one). The checks of the new server run first (`409` with the reason; `422` for a server that is not in the team). At most 3 transfers and moves back an hour for each app. Scope `compose:move`; Owner or Admin.
      operationId: transferComposeApp
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [server_id]
              properties:
                server_id: { type: integer, description: 'Another server of the team.' }
      responses:
        '202':
          description: The transfer started.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/ComposeApp' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    delete:
      tags: [Compose Apps]
      summary: Remove the copy on the old server
      description: |
        After a transfer (`transfer.step` is `kept`): the stopped copy of the app goes from its old server now, not after its 24 hours. The app cannot go back after this. Also on the Free plan. Scope `compose:move`; Owner or Admin.
      operationId: removeComposeTransferCopy
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '202':
          description: FlyWP removes the copy.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/ComposeApp' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps/{site}/transfer/restore:
    post:
      tags: [Compose Apps]
      summary: Move the app back to its original server
      description: |
        After a transfer (`transfer.step` is `kept`): the app goes back to its old server and starts there with its data of the transfer, and its certificates go back. Each change of the data on the new server since then is lost, and the copy there goes when the app runs on the old server. Point each domain (`transfer.point_domains`) back to the old server (`transfer.from_ip`): until then they do not answer. Refused (`409`) while a deploy, an action, a backup or a restore runs, after a deploy on the new server, and when the old server cannot take the app (the checks of a transfer). Scope `compose:move`; Owner or Admin.
      operationId: restoreComposeTransfer
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '202':
          description: The app goes back.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/ComposeApp' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps/{site}/transfer/targets:
    get:
      tags: [Compose Apps]
      summary: List the servers for a transfer
      description: |
        The other servers of the team, and for each one the memory that it has for the app and why the app cannot go there now (`blocked`). `refused` says why the app cannot move now; `downtime_minutes` is about how long the app is down, from the size of its last backup. As the Transfer page. Scope `compose:move`; Owner or Admin.
      operationId: listComposeTransferTargets
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '200':
          description: List the servers for a transfer.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: object, properties: { refused: { type: [string, 'null'] }, last_backup_bytes: { type: [integer, 'null'] }, downtime_minutes: { type: [integer, 'null'] }, point_domains: { type: array, items: { type: string }, description: 'The domains to point to the new server.' }, servers: { type: array, items: { type: object, properties: { id: { type: integer }, name: { type: string }, ip_address: { type: [string, 'null'] }, is_managed: { type: boolean }, same: { type: boolean }, room_mb: { type: [integer, 'null'] }, blocked: { type: [string, 'null'], description: 'Why the app cannot go to the server now. Null: it can.' }, provider: { type: [string, 'null'], description: 'The slug of the cloud of the server, for its logo.' } } } } } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }


  /v1/compose-apps/{site}/services:
    get:
      tags: [Compose Apps]
      summary: List the services
      description: |
        Each service with its state, image and memory limit, as FlyWP read them last (`seen_at`). Scope `compose:read`.
      operationId: listComposeServices
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '200':
          description: List the services.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { type: object } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps/{site}/deployments:
    get:
      tags: [Compose Apps]
      summary: List the deploys
      description: |
        Newest first. Takes `per_page` and `cursor`. A deploy that passed is a version. Scope `compose:read`.
      operationId: listComposeDeployments
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/PerPage'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: List the deploys.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/ComposeDeployment' } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    post:
      tags: [Compose Apps]
      summary: Deploy a new compose file
      description: |
        Checks the file as the panel does, saves it as a new version and deploys it. A file that FlyWP does not deploy is `422` with `check.blocked`, `check.advanced` and `check.missing`. Send `lock_version` from the app: a change made since is refused. A deploy that runs is `409` with `deployment`, its number. At most 30 deploys and rollbacks an hour for each app; `429` has `Retry-After`. Scope `compose:manage`; Owner or Admin.
      operationId: deployComposeFile
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [text, lock_version]
              properties:
                text: { type: string, description: 'The compose file.' }
                variables: { type: object, additionalProperties: { type: string }, description: 'Values of new settings of the file.' }
                lock_version: { type: integer }
      responses:
        '202':
          description: Deploy a new compose file.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/ComposeDeployment' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps/{site}/deployments/{number}:
    get:
      tags: [Compose Apps]
      summary: Get a deploy
      description: |
        The progress and the result of a deploy, a rollback, an update or the end of a restore: the reference that each of them gives. Scope `compose:read`.
      operationId: getComposeDeployment
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/ComposeDeploymentNumber'
      responses:
        '200':
          description: Get a deploy.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/ComposeDeployment' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps/{site}/deployments/{number}/rollback:
    post:
      tags: [Compose Apps]
      summary: Roll back to a version
      description: |
        Runs a kept version again: its file, its limits, its images and its settings. `secrets`: `keep` the secret values of now, or use the ones of that `version`. Send `lock_version` from the app. A deploy that runs is `409` with `deployment`, its number. At most 30 deploys and rollbacks an hour for each app; `429` has `Retry-After`. Scope `compose:deploy`; Owner or Admin.
      operationId: rollbackComposeApp
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/ComposeDeploymentNumber'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [secrets, lock_version]
              properties:
                secrets: { type: string, enum: [keep, version] }
                lock_version: { type: integer }
      responses:
        '202':
          description: Roll back to a version.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/ComposeDeployment' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps/{site}/deployments/{number}/backup:
    post:
      tags: [Compose Apps]
      summary: Choose for a deploy whose backup failed
      description: |
        A deploy waits when the backup before it failed. `choice`: `retry` (back up again; the deploy starts when it is done), `continue` (deploy with no backup) or `cancel`. A deploy that does not wait for a choice is `409`. A deploy that waits a day is cancelled. `202` when a backup or the deploy started (it counts in the 30 deploys an hour of the app), `200` for `cancel`. Scope `compose:deploy`; Owner or Admin.
      operationId: resolveHeldComposeDeployment
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/ComposeDeploymentNumber'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [choice]
              properties:
                choice: { type: string, enum: [retry, continue, cancel] }
      responses:
        '200':
          description: The deploy is cancelled.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/ComposeDeployment' }
                  message: { type: string }
        '202':
          description: A backup or the deploy started.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/ComposeDeployment' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }


  /v1/compose-apps/{site}/compare:
    get:
      tags: [Compose Apps]
      summary: Compare two versions
      description: |
        Two versions side by side, as the Compare page: what changed in the compose file (no line of it), the images, the names of the environment variables that changed (no value) and the limits. `from` and `to` are deploy numbers; with none, the version that runs and the one before it. A number that the app does not have: `404`. Scope `compose:read`.
      operationId: compareComposeVersions
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - { name: from, in: query, required: false, schema: { type: integer }, description: 'A deploy number.' }
        - { name: to, in: query, required: false, schema: { type: integer }, description: 'A deploy number.' }
      responses:
        '200':
          description: Compare two versions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      versions: { type: array, items: { type: object }, description: 'The newest deploys, with `id`, `number`, `status` and `live`.' }
                      from: { type: [object, 'null'], description: '`id`, `number` and `commit` of the older side.' }
                      to: { type: [object, 'null'], description: '`id`, `number` and `commit` of the newer side.' }
                      repository: { type: [string, 'null'] }
                      comparison: { type: [object, 'null'], description: '`changes`, `images`, `settings` (name and state: added, removed, changed) and `limits`; `lines` is null (the API gives no line of a compose file: it can hold values). Null with fewer than two versions.' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps/{site}/deploy:
    post:
      tags: [Compose Apps]
      summary: Deploy the app
      description: |
        A Git app deploys the newest commit of its branch. Another app deploys the version that runs again, with its exact images. With `update_images`, each image gets the newest image of its tag. With `deployment`, the number of a push that waits for approval, a Git app deploys that commit as a new deploy; a number that does not wait now is `404` (an older push never goes live over a newer one). A deploy that runs is `409` with `deployment`, its number. At most 30 deploys and rollbacks an hour for each app; `429` has `Retry-After`. Scope `compose:deploy`; Owner or Admin.
      operationId: deployComposeApp
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                update_images: { type: boolean, default: false }
                deployment: { type: integer, description: 'The number of a push that waits for approval.' }
      responses:
        '202':
          description: Deploy the app.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/ComposeDeployment' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps/{site}/template-update:
    post:
      tags: [Compose Apps]
      summary: Update the template of the app
      description: |
        Deploys the newer version of the template of the app, with the settings of the app. Send `version` from `template_update.to` of the app: a newer version that came out since is refused. A deploy that runs is `409` with `deployment`, its number. At most 30 deploys and rollbacks an hour for each app; `429` has `Retry-After`. Scope `compose:manage`; Owner or Admin.
      operationId: updateComposeTemplate
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [version]
              properties:
                version: { type: string }
                lock_version: { type: integer }
      responses:
        '202':
          description: Update the template of the app.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/ComposeDeployment' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps/{site}/operations:
    post:
      tags: [Compose Apps]
      summary: Restart, stop or start the app
      description: |
        For the whole app, or one `service` (a restart only). Get the app for the progress and the result in `operation`. A restart is for each role that can change the site; stop and start are for the Owner or an Admin. On the Free plan, only a stop. Scope `compose:deploy`.
      operationId: operateComposeApp
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [action]
              properties:
                action: { type: string, enum: [restart, stop, start] }
                service: { type: string }
      responses:
        '202':
          description: Restart, stop or start the app.
          content:
            application/json:
              schema:
                type: object
                properties:
                  operation: { $ref: '#/components/schemas/ComposeOperation' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps/{site}/settings:
    get:
      tags: [Compose Apps]
      summary: List the settings
      description: |
        Each setting by service ("" is the whole app). A setting is an environment variable of the app (the dashboard calls them "environment variables", on the Environment page; a message can say "variable"). A secret has its name only: `value` is null. `pending`: changed and not applied yet. Scope `compose:read`.
      operationId: listComposeSettings
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '200':
          description: List the settings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { type: object, properties: { id: { type: integer }, service: { type: string }, name: { type: string }, secret: { type: boolean }, value: { type: [string, 'null'] }, pending: { type: boolean } } } }
                  version: { type: integer, description: 'Send it with each change of the settings.' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    post:
      tags: [Compose Apps]
      summary: Add a setting
      description: |
        A new setting. It runs after an Apply. A secret is write-only: the answer has its name only. A setting of the whole app that the compose file puts where a page shows a value (an image, a port, a volume, a build, the network mode or a limit) cannot be a secret: `422` on `is_secret`. A change that another caller made since the `version` that the caller read is `409`: read the settings again and retry. Scope `compose:manage`; Owner or Admin.
      operationId: createComposeSetting
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, is_secret, version]
              properties:
                service: { type: string, description: 'Empty: the whole app.' }
                name: { type: string }
                value: { type: string, description: 'Each byte goes to the app.' }
                keep: { type: boolean, description: 'Update only: the value stays (no `value`).' }
                is_secret: { type: boolean }
                version: { type: integer, description: 'The `version` of the settings that the caller read.' }
      responses:
        '201':
          description: Add a setting.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: object, properties: { id: { type: integer }, service: { type: string }, name: { type: string }, secret: { type: boolean }, value: { type: [string, 'null'] }, pending: { type: boolean } } }
                  version: { type: integer, description: 'The new version of the settings.' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps/{site}/settings/{composeSetting}:
    put:
      tags: [Compose Apps]
      summary: Change a setting
      description: |
        A new value, or Secret on or off. A token cannot turn Secret off with no new value: that would show the value. A setting of the whole app that the compose file puts where a page shows a value (an image, a port, a volume, a build, the network mode or a limit) cannot be a secret: `422` on `is_secret`. A change that another caller made since the `version` that the caller read is `409`: read the settings again and retry. Scope `compose:manage`; Owner or Admin.
      operationId: updateComposeSetting
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/ComposeSettingId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [is_secret, version]
              properties:
                value: { type: string, description: 'Each byte goes to the app.' }
                keep: { type: boolean, description: 'Update only: the value stays (no `value`).' }
                is_secret: { type: boolean }
                version: { type: integer, description: 'The `version` of the settings that the caller read.' }
      responses:
        '200':
          description: Change a setting.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: object, properties: { id: { type: integer }, service: { type: string }, name: { type: string }, secret: { type: boolean }, value: { type: [string, 'null'] }, pending: { type: boolean } } }
                  version: { type: integer, description: 'The new version of the settings.' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

    delete:
      tags: [Compose Apps]
      summary: Remove a setting
      description: |
        The app has the setting until the next Apply. A change that another caller made since the `version` that the caller read is `409`: read the settings again and retry. Scope `compose:manage`; Owner or Admin.
      operationId: deleteComposeSetting
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/ComposeSettingId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [version]
              properties:
                version: { type: integer }
      responses:
        '200':
          description: Remove a setting.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
                  version: { type: integer, description: 'The new version of the settings.' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps/{site}/settings/apply:
    post:
      tags: [Compose Apps]
      summary: Apply the settings
      description: |
        A deploy of the version that runs with the new settings. With no change: `200` and nothing runs. A file that the check refuses with these settings is `422` with no reason (the reason can have a secret in it). A deploy that runs is `409` with `deployment`. At most 30 deploys an hour for each app; `429` has `Retry-After`. Scope `compose:manage`; Owner or Admin.
      operationId: applyComposeSettings
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [version]
              properties:
                version: { type: integer }
      responses:
        '202':
          description: Apply the settings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/ComposeDeployment' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps/{site}/settings/history:
    get:
      tags: [Compose Apps]
      summary: List the changes of the environment variables
      description: |
        Who changed which environment variable, and how, the newest first. No row has a value. FlyWP keeps the rows for 90 days. Takes `per_page` and `cursor`. Scope `compose:read`.
      operationId: listComposeSettingChanges
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/PerPage'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: List the changes of the environment variables.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: integer }
                        at: { type: string, format: date-time }
                        person: { type: string }
                        service: { type: string, description: 'Empty: the whole app.' }
                        name: { type: string }
                        action: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps/{site}/settings/export:
    get:
      tags: [Compose Apps]
      summary: Export the environment variables
      description: |
        The environment variables as the text of a `.env` file: of the whole app, or of one service (`service`). A secret has its name with no value. Scope `compose:read`.
      operationId: exportComposeSettings
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - { name: service, in: query, required: false, schema: { type: string }, description: 'A service; none: the whole app.' }
      responses:
        '200':
          description: Export the environment variables.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      service: { type: string }
                      text: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps/{site}/settings/import:
    post:
      tags: [Compose Apps]
      summary: Import a .env file
      description: |
        The text of a `.env` file into the environment of the whole app or of one service. A name that the app has stays, unless `replace` names it; `secrets` names the variables that are secret. The app gets the values at the next Apply. Send `version` from the list of the variables: a change that another caller made since is refused (`409`). Not on the Free plan. Scope `compose:manage`; Owner or Admin.
      operationId: importComposeSettings
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [env_text, version]
              properties:
                env_text: { type: string }
                service: { type: [string, 'null'], description: 'A service; none: the whole app.' }
                replace: { type: array, items: { type: string } }
                secrets: { type: array, items: { type: string } }
                version: { type: integer }
      responses:
        '200':
          description: Import a .env file.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      added: { type: array, items: { type: string } }
                      replaced: { type: array, items: { type: string } }
                      kept: { type: array, items: { type: string } }
                  version: { type: integer }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps/{site}/settings/discard:
    post:
      tags: [Compose Apps]
      summary: Discard the changes of the settings
      description: |
        A change that is not applied goes back to the value that the app runs with: one setting (`setting`, its id), or each setting. A setting that another caller removed, or a change since the `version` that the caller read, is `409`: read the settings again and retry. Scope `compose:manage`; Owner or Admin.
      operationId: discardComposeSettings
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [version]
              properties:
                setting: { type: [integer, 'null'], description: 'The id of one setting. Nothing: each setting.' }
                version: { type: integer, description: 'The `version` of the settings that the caller read.' }
      responses:
        '200':
          description: Discard the changes of the settings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { type: object } }
                  version: { type: integer, description: 'The new version of the settings.' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }


  /v1/compose-apps/{site}/settings/import/preview:
    post:
      tags: [Compose Apps]
      summary: Preview an import of settings
      description: |
        What an import of the text of a `.env` file adds and changes, for the whole app or for one `service`. It saves nothing; also on the Free plan. Scope `compose:manage`; Owner or Admin.
      operationId: previewComposeSettingsImport
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [env_text]
              properties:
                service: { type: [string, 'null'], maxLength: 63 }
                env_text: { type: string }
      responses:
        '200':
          description: Preview an import of settings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: object }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }


  /v1/compose-apps/{site}/limits:
    put:
      tags: [Compose Apps]
      summary: Set the limits
      description: |
        The limits of each service of the app (each service, and no other name). A deploy of the version that runs; the same limits: `200` and nothing runs. No room on the server: `409` with `fit` (`need_mb`, `room_mb`, `server_gb`: a server size with room). At most 30 deploys an hour for each app. Scope `compose:manage`; Owner or Admin.
      operationId: updateComposeLimits
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [lock_version, limits]
              properties:
                lock_version: { type: integer }
                limits: { type: object, additionalProperties: { type: object, required: [memory_mb, cpus, pids], properties: { memory_mb: { type: integer, description: 'Steps of 64.' }, cpus: { type: number, description: 'Steps of 0.25, up to the cores of the server.' }, pids: { type: integer, minimum: 64, maximum: 4096 } } } }
      responses:
        '202':
          description: Set the limits.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/ComposeDeployment' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps/{site}/advanced-mode:
    put:
      tags: [Compose Apps]
      summary: Turn advanced mode on or off
      description: |
        Advanced mode lets a container use more of the server (an own server only, never a FlyWP Managed server). To turn it on, send `server_name`, the name of the server, as the dashboard asks for it. "Off" is refused while the version that runs uses advanced mode (`422` with the lines to remove). Not on the Free plan. Scope `compose:manage`; the team Owner only.
      operationId: setComposeAdvancedMode
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [enabled]
              properties:
                enabled: { type: boolean }
                server_name: { type: string, description: 'Required when `enabled` is true: the name of the server.' }
      responses:
        '200':
          description: Turn advanced mode on or off.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/ComposeApp' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps/{site}/deploy-timeout:
    put:
      tags: [Compose Apps]
      summary: Set the deploy time limit
      description: |
        A deploy that runs longer stops and the version before runs again. From 30 to 60 minutes. Not on the Free plan. Scope `compose:manage`; the team Owner only.
      operationId: setComposeDeployTimeout
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [deploy_timeout_minutes]
              properties:
                deploy_timeout_minutes: { type: integer, minimum: 30, maximum: 60 }
      responses:
        '200':
          description: Set the deploy time limit.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/ComposeApp' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps/{site}/health:
    put:
      tags: [Compose Apps]
      summary: Change the automatic rollback
      description: |
        `auto_rollback`: a deploy that is not healthy in its health window goes back to the version before. `window_minutes`: 1 to 30, used from the next deploy. Off stops at once, also for the deploy that is checked now. The answer is the app, with `health`. Scope `compose:manage`; Owner or Admin.
      operationId: updateComposeHealth
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [auto_rollback, window_minutes]
              properties:
                auto_rollback: { type: boolean }
                window_minutes: { type: integer, minimum: 1, maximum: 30 }
      responses:
        '200':
          description: Change the automatic rollback.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/ComposeApp' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }


  /v1/compose-apps/{site}/registry-logins:
    get:
      tags: [Compose Apps]
      summary: List the registry logins
      description: |
        For each registry of the images of the app: the login of the team that its pulls use (`credential_id`: 0 = the person chose "No login"; null = no choice, and the team has no login for that registry that the registry did not refuse) and the logins of the team for that registry. With no choice, the app uses the oldest login that the registry did not refuse at its last test. Scope `compose:manage`; Owner or Admin.
      operationId: listComposeRegistryLogins
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '200':
          description: List the registry logins.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        address: { type: string }
                        credential_id: { type: [integer, 'null'] }
                        credentials: { type: array, items: { type: object, properties: { id: { type: integer }, name: { type: string }, username: { type: string }, refused: { type: boolean, description: 'The registry refused the user name or the token at the last test of the login. The app uses it only when it is chosen for the app; it is never the default. A test that could not reach the registry is not a refusal.' } } } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    put:
      tags: [Compose Apps]
      summary: Set the login of a registry
      description: |
        The login that the pulls of the app use for one registry: an id of `credentials`, or 0 for no login. Used from the next pull. Not on the Free plan. Scope `compose:manage`; Owner or Admin.
      operationId: setComposeRegistryLogin
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [address, credential]
              properties:
                address: { type: string }
                credential: { type: integer }
      responses:
        '200':
          description: Set the login of a registry.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { type: object } }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps/{site}/git:
    get:
      tags: [Compose Apps]
      summary: Show the repository settings
      description: |
        The repository, the branch, the path of the compose file and push to deploy of an app from GitHub. The address and the secret of push to deploy and the deploy key are only for a token with the `compose:manage` scope of an Owner or an Admin (else null). An app that is not from a repository: `404`. Scope `compose:read`.
      operationId: showComposeGit
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '200':
          description: Show the repository settings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      repository: { type: [string, 'null'] }
                      branch: { type: [string, 'null'] }
                      path: { type: [string, 'null'] }
                      private: { type: boolean }
                      push: { type: object, properties: { on: { type: boolean }, webhook: { type: boolean }, url: { type: [string, 'null'] }, secret: { type: [string, 'null'] } } }
                      deploy_key: { type: [object, 'null'], properties: { public: { type: string }, added: { type: boolean } } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    put:
      tags: [Compose Apps]
      summary: Change the repository settings
      description: |
        The branch, the path of the compose file and push to deploy (each one optional). A branch or a path that you send must have a value: an empty one is refused (`422`), and the saved one stays. Used from the next deploy. Not on the Free plan. Scope `compose:manage`; Owner or Admin.
      operationId: updateComposeGit
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                branch: { type: string, minLength: 1 }
                path: { type: string, minLength: 1 }
                push: { type: boolean }
      responses:
        '200':
          description: Change the repository settings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: object }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps/{site}/domains:
    get:
      tags: [Compose Apps]
      summary: List the domains
      description: |
        Each domain with the service and the port that it goes to, and the state of its certificate. Scope `compose:read`.
      operationId: listComposeDomains
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '200':
          description: List the domains.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { type: object } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    post:
      tags: [Compose Apps]
      summary: Add a domain
      description: |
        A domain to a service and its port. FlyWP asks for its certificate when its DNS points to the server. Only the web container of the server changes: no service of the app stops. Scope `compose:manage`; Owner or Admin.
      operationId: createComposeDomain
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [fqdn, timeout_seconds, upload_mb]
              properties:
                fqdn: { type: string, description: 'Add only. The name does not change after.' }
                aliases: { type: array, items: { type: string }, maxItems: 19 }
                service: { type: [string, 'null'], description: 'With `port`. Null: the domain goes to no service yet.' }
                port: { type: [integer, 'null'] }
                timeout_seconds: { type: integer }
                upload_mb: { type: integer }
      responses:
        '201':
          description: Add a domain.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: object }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps/{site}/domains/apply:
    post:
      tags: [Compose Apps]
      summary: Apply the domains again
      description: |
        "Check again": FlyWP writes the domains of the app on the server again. Each domain shows that it applies until the server reports. The answer is the list of the domains. At most 12 a minute. Scope `compose:manage`; Owner or Admin.
      operationId: applyComposeDomains
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '202':
          description: Apply the domains again.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { type: object } }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }


  /v1/compose-apps/{site}/domains/{composeDomain}:
    put:
      tags: [Compose Apps]
      summary: Change a domain
      description: |
        The service, the port, the aliases and the limits of a domain. Only the web container of the server changes: no service of the app stops. Scope `compose:manage`; Owner or Admin.
      operationId: updateComposeDomain
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/ComposeDomainId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [timeout_seconds, upload_mb]
              properties:
                aliases: { type: array, items: { type: string }, maxItems: 19 }
                service: { type: [string, 'null'], description: 'With `port`. Null: the domain goes to no service yet.' }
                port: { type: [integer, 'null'] }
                timeout_seconds: { type: integer }
                upload_mb: { type: integer }
      responses:
        '200':
          description: Change a domain.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: object }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

    delete:
      tags: [Compose Apps]
      summary: Remove a domain
      description: |
        The main domain stays. The test domain can go once another domain is main: FlyWP removes its DNS record, and it does not come back. Only the web container of the server changes: no service of the app stops. Scope `compose:manage`; Owner or Admin.
      operationId: deleteComposeDomain
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/ComposeDomainId'
      responses:
        '200':
          description: Remove a domain.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps/{site}/domains/{composeDomain}/certificate:
    post:
      tags: [Compose Apps]
      summary: Set the certificate of a domain
      description: |
        `kind`: `upload` (your certificate and its private key, in the PEM format, for each name of the domain), `cloudflare_origin` (a Cloudflare Origin certificate from a Cloudflare account of the team, `integration_id`) or `letsencrypt` (back to Let's Encrypt; FlyWP asks when the DNS of each name points to the server). The answer has the domain and what happens now: `202` when a certificate is on its way, `200` when nothing started yet (the DNS is not ready, too soon). Not on the Free plan. At most 12 started (`202`) an hour for each app; `429` has `Retry-After`. Scope `compose:manage`; Owner or Admin.
      operationId: setComposeDomainCertificate
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/ComposeDomainId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [kind]
              properties:
                kind: { type: string, enum: [upload, cloudflare_origin, letsencrypt] }
                cert: { type: string, description: 'For `upload`.' }
                key: { type: string, description: 'For `upload`.' }
                integration_id: { type: integer, description: 'For `cloudflare_origin`.' }
      responses:
        '200':
          description: Nothing started yet; `message` says why.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: object }
                  message: { type: string }
        '202':
          description: Set the certificate of a domain.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: object }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps/{site}/domains/{composeDomain}/secure:
    post:
      tags: [Compose Apps]
      summary: Check the DNS of a domain
      description: |
        When each name of the domain points to the server, FlyWP asks Let's Encrypt for its certificate. The answer has the domain and what happens now: `202` when a certificate is on its way, `200` when nothing started (`message` says why: the DNS is not ready, too soon after a failure). At most 12 checks a minute, and at most 12 started (`202`) an hour for each app, with the certificates of the domains. Scope `compose:manage`; Owner or Admin.
      operationId: secureComposeDomain
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/ComposeDomainId'
      responses:
        '200':
          description: Nothing started; `message` says why.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: [object, 'null'], description: 'Null for another name of a domain (it has no row of its own in the list).' }
                  message: { type: string }
        '202':
          description: A certificate is on its way.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: object }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }


  /v1/compose-apps/{site}/domains/{composeDomain}/main:
    post:
      tags: [Compose Apps]
      summary: Make a domain the main domain
      description: |
        The address that FlyWP shows for the app. The answer is the list of the domains. Scope `compose:manage`; Owner or Admin.
      operationId: makeComposeDomainMain
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/ComposeDomainId'
      responses:
        '200':
          description: Make a domain the main domain.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { type: object } }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }


  /v1/compose-apps/{site}/domains/{composeDomain}/redirects:
    put:
      tags: [Compose Apps]
      summary: Set the redirects of a domain
      description: |
        `canonical`: the name of the domain that each other name of it goes to (null: each name serves the app). `redirects`: at most 50 rules for a path (`from`, for example `/old-page`) to a path or an `https://` address (`to`), with `type` 301 or 302. A rule that goes in a circle is `422`, and so is a rule or a `canonical` for a domain with no service (an empty set is allowed). No service of the app restarts. Scope `compose:manage`; Owner or Admin.
      operationId: setComposeDomainRedirects
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/ComposeDomainId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [redirects]
              properties:
                canonical: { type: [string, 'null'] }
                redirects:
                  type: array
                  items:
                    type: object
                    required: [from, to, type]
                    properties:
                      from: { type: string }
                      to: { type: string, maxLength: 2000 }
                      type: { type: integer, enum: [301, 302] }
      responses:
        '200':
          description: Set the redirects of a domain.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: object }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }


  /v1/compose-apps/{site}/logs:
    get:
      tags: [Compose Apps]
      summary: Read the logs
      description: |
        The newest lines of a `service`, of each service, of the web containers (`source`), or of the last deploy (`deploy`). At most 1,000 lines; each saved secret is hidden. `status` is `busy` when the server answers another read: ask again in a few seconds. Scope `compose:read`.
      operationId: readComposeLogs
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - { name: source, in: query, required: true, schema: { type: string, enum: [services, web, deploy] } }
        - { name: service, in: query, schema: { type: string } }
        - { name: lines, in: query, schema: { type: integer, enum: [100, 500, 1000], default: 500 } }
        - { name: since, in: query, schema: { type: string }, description: 'Lines after this time (RFC 3339).' }
      responses:
        '200':
          description: Read the logs.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: object, properties: { status: { type: string }, cut: { type: boolean }, error: { type: boolean }, more: { type: boolean }, lines: { type: array, items: { type: object, properties: { service: { type: string }, at: { type: [string, 'null'] }, text: { type: string } } } } } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps/{site}/logs/export:
    post:
      tags: [Compose Apps]
      summary: Make a file of the logs
      description: |
        Each line that the server has for a `service`, for each service, or for the web containers (`source`), as a text file. A job makes it: download it when its `status` is `ready`. A team makes one file at a time; the file is kept for one hour. The log of the last deploy is in `GET logs` (`source=deploy`): `422` here. Also on the Free plan. At most 6 a minute. Scope `compose:manage`; Owner or Admin.
      operationId: exportComposeLogs
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [source]
              properties:
                source: { type: string, enum: [services, web] }
                service: { type: [string, 'null'] }
      responses:
        '202':
          description: Make a file of the logs.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: [object, 'null'], properties: { status: { type: string, enum: [running, ready, failed] }, source: { type: string }, service: { type: [string, 'null'] }, bytes: { type: [integer, 'null'] }, complete: { type: boolean }, no_lines: { type: boolean }, started_at: { type: string }, kept_until: { type: string } } }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

    get:
      tags: [Compose Apps]
      summary: Download the file of the logs
      description: |
        The file when it is ready (`text/plain`), or a redirect to a link that works for 5 minutes. The download is in the activity log of the team. While FlyWP makes it: `202` with its `status` (`running`); ask again. No file: `404`, with the `status` of the last file (`failed`, or `ready` when the file is gone) or null. At most 6 a minute. Scope `compose:manage`; Owner or Admin.
      operationId: downloadComposeLogs
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '200':
          description: The file of the logs.
        '302':
          description: A link of the file that works for 5 minutes.
        '202':
          description: FlyWP makes the file.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: object }
                  message: { type: string }
        '404':
          description: There is no file.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: [object, 'null'], properties: { status: { type: string, enum: [running, ready, failed] }, source: { type: string }, service: { type: [string, 'null'] }, bytes: { type: [integer, 'null'] }, complete: { type: boolean }, no_lines: { type: boolean }, started_at: { type: string }, kept_until: { type: string } } }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }


  /v1/compose-apps/{site}/images/cleanup:
    post:
      tags: [Compose Apps]
      summary: Clean up the images
      description: |
        FlyWP removes the images that the app does not keep (the images of the versions that it can roll back to stay), and the build cache of the server. Also on the Free plan: it only frees disk. At most 6 a minute. Scope `compose:manage`; Owner or Admin.
      operationId: cleanComposeImages
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '202':
          description: Clean up the images.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }


  /v1/compose-apps/{site}/backups:
    get:
      tags: [Compose Apps]
      summary: List the backups
      description: |
        Newest first. Takes `per_page` and `cursor`. The app can restore a backup in place when `restorable` and `runs` are both true (else roll back to its version first). Scope `compose:read`.
      operationId: listComposeBackups
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/PerPage'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: List the backups.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/ComposeBackup' } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    post:
      tags: [Compose Apps]
      summary: Back up the app
      description: |
        A copy of the data of the app to its backup destination; the services that the copy needs stop for a moment. The list of the backups has its progress. Also on the Free plan. At most 6 backups an hour for each app; `429` has `Retry-After`. Scope `compose:backups`; Owner or Admin.
      operationId: backUpComposeApp
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '202':
          description: Back up the app.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/ComposeBackup' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps/{site}/backups/settings:
    get:
      tags: [Compose Apps]
      summary: Show the backup settings
      description: |
        The destination and the schedule (`setting`, null: none), whether the plan has backups (`allowed`), and what each backup copies (`items`, with the size of each in the newest backup). Scope `compose:read`.
      operationId: showComposeBackupSettings
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      responses:
        '200':
          description: Show the backup settings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      allowed: { type: boolean }
                      scheduled: { type: boolean }
                      setting: { type: [object, 'null'] }
                      items: { type: array, items: { type: object } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
    put:
      tags: [Compose Apps]
      summary: Set the backup settings
      description: |
        The destination (a backup storage of the team, `integration_id`, with its own fields: `bucket` and `region`, or `root_folder_id`), how many backups to keep, the schedule and its hour in UTC, and the items: `excluded` (keys of `items` that no backup copies) and `brief_stop` (databases that stop for their copy instead of an export). FlyWP prepares the destination on the server after. The plan needs backups. Not on the Free plan. Scope `compose:backups`; Owner or Admin.
      operationId: updateComposeBackupSettings
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [integration_id, retention, frequency, backup_time, scheduled]
              properties:
                integration_id: { type: integer }
                retention: { type: integer, minimum: 1, maximum: 365 }
                frequency: { type: string, enum: [hourly, daily] }
                backup_time: { type: string, example: '02:00:00', description: 'The hour in UTC.' }
                scheduled: { type: boolean }
                excluded: { type: array, items: { type: string } }
                brief_stop: { type: array, items: { type: string } }
                bucket: { type: string }
                region: { type: string }
                root_folder_id: { type: string }
      responses:
        '200':
          description: Set the backup settings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: object }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps/{site}/backups/{backup}/restore:
    post:
      tags: [Compose Apps]
      summary: Restore a backup
      description: |
        Puts the data of the backup into the version that runs; the app must run the layout of the backup (`restorable` and `runs` in the list). Send `name`, the name of the app, as in the dashboard. FlyWP backs up the app as it is first; when it cannot (no destination that works, or no backups in the plan), the request needs `without_safety_backup: true`, else it is `422`. The list of the backups has the progress in `restore`. Not on the Free plan. At most 3 restores an hour for each app. Scope `compose:backups`; Owner or Admin.
      operationId: restoreComposeBackup
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/BackupId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string }
                without_safety_backup: { type: boolean, default: false, description: 'Accept a restore with no backup of the data of now: nothing can undo it.' }
      responses:
        '202':
          description: Restore a backup.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/ComposeBackup' }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/compose-apps/{site}/backups/{backup}:
    delete:
      tags: [Compose Apps]
      summary: Delete a backup
      description: |
        The backup and its file at the destination. `409` when the backup runs, when a deploy or a restore waits for it, when the sign-in of the destination expired, or when the destination did not remove the file. Not on the Free plan. Scope `compose:backups`; Owner or Admin.
      operationId: deleteComposeBackup
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/BackupId'
      responses:
        '200':
          description: Delete a backup.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }


  /v1/compose-apps/{site}/backups/{backup}/download:
    get:
      tags: [Compose Apps]
      summary: Get the download link of a backup
      description: |
        A link of the destination for the file of the backup. The download is in the activity log of the team. A backup with no file, or a destination that gives no link, is `409`. Also on the Free plan, so the data can leave before the app is removed. Scope `compose:backups`; Owner or Admin.
      operationId: downloadComposeBackup
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/BackupId'
      responses:
        '200':
          description: Get the download link of a backup.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: object, properties: { url: { type: string } } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }


  /v1/servers/{server}/compose-apps/check:
    post:
      tags: [Compose Apps]
      summary: Check a compose file
      description: |
        The pre-deploy check of a new app: the services, what FlyWP adds or changes, each blocked line with its reason, the settings with no value, and the fit on the server. Nothing is saved. The Free plan is `402`; a server that cannot take a compose app now is `409`. At most 60 checks an hour for each team. Scope `compose:manage`; Owner or Admin.
      operationId: checkComposeApp
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/ServerId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string, maxLength: 60, description: 'Create only. The name of the app.' }
                source: { type: string, enum: [paste, url, git], description: 'Leave it out with `template`.' }
                text: { type: string, description: 'The compose file (`paste`). With `url` or `git` FlyWP reads it.' }
                source_url: { type: string, description: 'An https link to the compose file (`url`).' }
                repository: { type: string, description: 'owner/name on GitHub (`git`), read with the GitHub connection of the person of the token.' }
                branch: { type: string }
                path: { type: string, default: docker-compose.yml }
                template: { type: string, description: 'The slug of a template. FlyWP writes the file and makes its secrets.' }
                variables: { type: object, additionalProperties: { type: string }, description: 'The values of the settings of the file, or of the template, and each other environment variable of the app.' }
                secret_names: { type: array, maxItems: 200, items: { type: string }, description: 'The variables that are secrets (each one a key of `variables`). The answer shows each one as `******`, except a name in a place that a page shows (an image, a port, a limit): it cannot be a secret. Not sent: FlyWP guesses by the name. The secrets of a template are always hidden.' }
                domain_service: { type: string, description: 'Create only. The service of the test domain.' }
                domain_port: { type: integer }
      responses:
        '200':
          description: Check a compose file.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      check: { type: object, description: 'The result of the checker. `blocked` (stops the deploy), `changed` (FlyWP removed or replaced it), `advanced` (an unlocked line in use) and `warnings`: each a list of findings with `rule`, `message`, `line`, `service`, `setting` and `unlockable`. `missing`: the settings with no value (`name`, `hint`, `line`, `used_in`). `services`: each service with `name`, `image`, `ports`, `volumes`, `folders`, `memory_mb`, `cpus`, `pids`, `runs_once`, `network_mode`, `environment_names`, `build`, `dockerfile` and `mount_targets`. `used`: each setting name that the file reads. `file`: the file that FlyWP writes, with each secret as `******`; null when it cannot deploy. When a secret is in a place where `******` changes the result (a port, a number), `file` is a short note and each `blocked` message has no value in it. A create that is refused for its file (`422`) has the `blocked`, `advanced` and `missing` of this object. A secret setting of an app in such a place is the finding `setting.secret-shown` (the name, never the value).' }
                      fit:
                        type: object
                        properties:
                          need_mb: { type: integer, description: 'The total of the memory limits of the services.' }
                          room_mb: { type: integer, description: 'What is free for compose apps on the server, without this app.' }
                          fits: { type: boolean }
                          server_gb: { type: [integer, 'null'], description: 'When the app does not fit: the smallest server size, in GB, that has room for it.' }
                          build_mb: { type: integer, description: 'The room that a build of the images needs while it runs (a Git app); 0 with no build.' }
                      shown_settings: { type: array, items: { type: string }, description: 'The variables that the file puts where a page shows a value: they cannot be a secret.' }
                      suggested_target:
                        type: [object, 'null']
                        description: 'The service and the port of the test domain: those of the template, or those that the file leaves no doubt about.'
                        properties:
                          service: { type: string }
                          port: { type: integer }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }

  /v1/servers/{server}/compose-apps:
    post:
      tags: [Compose Apps]
      summary: Create a compose app
      description: |
        The same checks as the panel: the plan, the server, the safety checker and the room. The Free plan is `402`; a server that cannot take a compose app now is `409`. A file that FlyWP does not deploy is `422` with `check.blocked`, `check.advanced` and `check.missing`. The first deploy runs in the background: `deployment` is its number. At most 10 creates an hour for each team. Scope `compose:manage`; Owner or Admin.
      operationId: createComposeApp
      parameters:
        - $ref: '#/components/parameters/TeamId'
        - $ref: '#/components/parameters/ServerId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string, maxLength: 60, description: 'Create only. The name of the app.' }
                source: { type: string, enum: [paste, url, git], description: 'Leave it out with `template`.' }
                text: { type: string, description: 'The compose file (`paste`). With `url` or `git` FlyWP reads it.' }
                source_url: { type: string, description: 'An https link to the compose file (`url`).' }
                repository: { type: string, description: 'owner/name on GitHub (`git`), read with the GitHub connection of the person of the token.' }
                branch: { type: string }
                path: { type: string, default: docker-compose.yml }
                template: { type: string, description: 'The slug of a template. FlyWP writes the file and makes its secrets.' }
                variables: { type: object, additionalProperties: { type: string }, description: 'The values of the settings of the file, or of the template, and each other environment variable of the app: FlyWP gives each one to each service. At most 200, with the names that a template makes. A name has letters, digits and underscore (at most 255); a value is UTF-8 with no NUL, at most 32 KB.' }
                secret_names: { type: array, maxItems: 200, items: { type: string }, description: 'Create only. The variables that are secrets (each one a key of `variables`). Not sent: FlyWP guesses by the name. A template makes its own secrets. A name that the file puts in an image, a port, a volume, a build, the network mode or a limit is `422` on `secret_names`.' }
                domain_service: { type: string, description: 'Create only. The service of the main domain of the app.' }
                domain_port: { type: integer }
                testdomain: { type: boolean, description: 'Use the free test domain as the main domain. Default: true when no `domain` comes. When true, the other domain fields are not read. With your own `domain`, the app gets no test domain.' }
                domain: { type: string, description: 'Your own domain, the main domain of the app (with `www.` as an alias for an apex domain). Point its A record to the server: HTTPS starts when it points.' }
                cloudflare: { type: boolean, default: false, description: 'Add a DNS-only A record for each name of `domain` in a Cloudflare account of the team.' }
                cloudflare_integration_id: { type: integer, description: 'The Cloudflare account. Required with `cloudflare`.' }
      responses:
        '202':
          description: Create a compose app.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/ComposeApp' }
                  deployment: { type: integer }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/PaymentRequired' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
