# TODO:
# - rename all List* responses to *List
# - add pagination headers to all List* responses
# - remove pagination meta and pagination links schemas

openapi: 3.0.0
info:
  title: Chaos
  version: "1.0.0"
  description: Central Management API - publicly exposed set of APIs for cloud resources
  contact:
    email: help@qernal.support
  x-logo:
    url: /assets/components/Chaos.png
    backgroundColor: "#FFFFFF"
    altText: Qernal Chaos
servers:
  - url: "https://chaos.qernal.com/v1"
    description: Production
security:
  - token: []
  - cookie: []

paths:
  # users
  "/users/{user_id}/quotas":
    parameters:
      - $ref: "#/components/parameters/user_id"
    get:
      summary: List user quotas
      tags:
        - users
        - quotas
      security:
        - token: []
        - cookie: []
      responses:
        "200":
          $ref: "#/components/responses/QuotasList"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "403":
          $ref: "#/components/responses/Unauthorised"
      operationId: users-quotas-list
      description: Get the quotas for a user
  "/users/{user_id}/quotas/{quota_entity_quota}":
    parameters:
      - $ref: "#/components/parameters/user_id"
      - $ref: "#/components/parameters/quota_entity_quota"
    get:
      summary: Get specific user quota
      tags:
        - users
        - quotas
      security:
        - token: []
        - cookie: []
      responses:
        "200":
          $ref: "#/components/responses/QuotasList"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "403":
          $ref: "#/components/responses/Unauthorised"
      operationId: users-quotas-get
      description: Get a specific quota for a user

  # billing
  "/billing/accounts":
    get:
      summary: List billing accounts
      tags:
        - billing
      security:
        - token: []
        - cookie: []
      responses:
        "200":
          $ref: "#/components/responses/BillingAccountsList"
        "401":
          $ref: "#/components/responses/Unauthorised"
      operationId: billing-accounts-list
      description: List all billing accounts for this user, paginated
    post:
      summary: Create billing account
      operationId: billing-accounts-create
      responses:
        "201":
          $ref: "#/components/responses/BillingAccount"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorised"
      description: Create a new billing account
      requestBody:
        $ref: "#/components/requestBodies/BillingAccountBody"
      tags:
        - billing
      security:
        - token: []
        - cookie: []

  "/billing/accounts/{billing_account_id}":
    parameters:
      - $ref: "#/components/parameters/billing_account_id"
    get:
      summary: Get billing account
      tags:
        - billing
      security:
        - token: []
        - cookie: []
      responses:
        "200":
          $ref: "#/components/responses/BillingAccount"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "403":
          $ref: "#/components/responses/Unauthorised"
      operationId: billing-accounts-get
      description: Get a specific billing account
    put:
      operationId: billing-accounts-update
      summary: Update billing account
      description: Update the details of a specific billing account.
      tags:
        - billing
      security:
        - token: []
        - cookie: []
      responses:
        "200":
          $ref: "#/components/responses/BillingAccount"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Unauthorised"
      requestBody:
        $ref: "#/components/requestBodies/BillingAccountBody"
    delete:
      operationId: billing-accounts-delete
      summary: Delete billing account
      description: Delete a specific billing account if it is no longer attached to any organizations or projects and has no outstanding balances or invoice payments.
      tags:
        - billing
      security:
        - token: []
        - cookie: []
      responses:
        "200":
          $ref: "#/components/responses/ResourceDeleted"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "403":
          $ref: "#/components/responses/Unauthorised"

  "/billing/accounts/{billing_account_id}/payment-methods":
    parameters:
      - $ref: "#/components/parameters/billing_account_id"
    get:
      summary: List payment methods for a billing account
      description: Retrieve a list of payment methods associated with a specific billing account.
      tags:
        - billing
      security:
        - token: []
        - cookie: []
      responses:
        "200":
          $ref: "#/components/responses/PaymentMethodsList"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "403":
          $ref: "#/components/responses/Unauthorised"
      operationId: accounts-payment-methods-list
    post:
      summary: Create a new payment method for a billing account
      description: Create a new payment method associated with a specific billing account.
      tags:
        - billing
      security:
        - token: []
        - cookie: []
      requestBody:
        $ref: "#/components/requestBodies/PaymentMethodBody"
      responses:
        "201":
          $ref: "#/components/responses/PaymentMethodCreate"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Unauthorised"
        "409":
          $ref: "#/components/responses/ResourceConflict"
      operationId: accounts-payment-methods-create

  "/billing/payment-methods/{billing_payment_method_id}":
    parameters:
      - $ref: "#/components/parameters/billing_payment_method_id"
    get:
      summary: Retrieve metadata for a specific payment method
      description: Get metadata (such as state, active, declined, cancelled, etc.) for a specific payment method.
      tags:
        - billing
      security:
        - token: []
        - cookie: []
      responses:
        "200":
          $ref: "#/components/responses/PaymentMethod"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "403":
          $ref: "#/components/responses/Unauthorised"
      operationId: payment-methods-get
    put:
      summary: Update a specific payment method
      description: Update the details of a specific payment method.
      tags:
        - billing
      security:
        - token: []
        - cookie: []
      requestBody:
        $ref: "#/components/requestBodies/PaymentMethodBody"
      responses:
        "200":
          $ref: "#/components/responses/PaymentMethod"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Unauthorised"
      operationId: payment-methods-update
    delete:
      summary: Delete a specific payment method
      description: Remove a specific payment method entirely if there are no associated resources and no pending partial invoices.
      tags:
        - billing
      security:
        - token: []
        - cookie: []
      responses:
        "200":
          $ref: "#/components/responses/ResourceDeleted"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "403":
          $ref: "#/components/responses/Unauthorised"
      operationId: payment-methods-delete

  # organisations
  "/organisations":
    get:
      parameters:
        - $ref: "#/components/parameters/pagination_page"
        - $ref: "#/components/parameters/filter_name"
      summary: List organisations
      tags:
        - organisations
      security:
        - token: []
        - cookie: []
      responses:
        "200":
          $ref: "#/components/responses/OrganisationsList"
        "403":
          $ref: "#/components/responses/Unauthorised"
      operationId: organisations-list
      description: List organisations
    post:
      summary: Create organisations
      operationId: organisations-create
      responses:
        "201":
          $ref: "#/components/responses/Organisation"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Unauthorised"
        "409":
          $ref: "#/components/responses/ResourceConflict"
      description: Create an organisation
      tags:
        - organisations
      security:
        - token: []
        - cookie: []
      requestBody:
        $ref: "#/components/requestBodies/OrganisationBody"

  "/organisations/{organisation_id}":
    parameters:
      - $ref: "#/components/parameters/organisation_id"
    get:
      summary: Get an organisation
      tags:
        - organisations
      security:
        - token: []
        - cookie: []
      responses:
        "200":
          $ref: "#/components/responses/Organisation"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "403":
          $ref: "#/components/responses/Unauthorised"
      operationId: organisations-get
      description: Get a single organisation
    put:
      summary: Update an organisation
      operationId: organisations-update
      responses:
        "200":
          $ref: "#/components/responses/Organisation"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Unauthorised"
      description: Update an organisation
      tags:
        - organisations
      security:
        - token: []
        - cookie: []
      requestBody:
        $ref: "#/components/requestBodies/OrganisationBody"
    delete:
      summary: Delete an organisation
      operationId: organisations-delete
      responses:
        "200":
          $ref: "#/components/responses/ResourceDeleted"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "403":
          $ref: "#/components/responses/Unauthorised"
      description: Delete organisation, this will also delete all the resources within the organisation
      tags:
        - organisations
      security:
        - token: []
        - cookie: []

  "/organisations/{organisation_id}/projects":
    parameters:
      - $ref: "#/components/parameters/organisation_id"
    get:
      parameters:
        - $ref: "#/components/parameters/pagination_page"
        - $ref: "#/components/parameters/filter_name"
      summary: Get all projects within an organisation
      tags:
        - projects
      security:
        - token: []
        - cookie: []
      responses:
        "200":
          $ref: "#/components/responses/ProjectsList"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "403":
          $ref: "#/components/responses/Unauthorised"
      operationId: organisations-projects-list
      description: Get all the projects linked to a specific organisation
  "/organisations/{organisation_id}/quotas":
    parameters:
      - $ref: "#/components/parameters/organisation_id"
    get:
      summary: List organisation quotas
      tags:
        - organisations
        - quotas
      security:
        - token: []
        - cookie: []
      responses:
        "200":
          $ref: "#/components/responses/QuotasList"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "403":
          $ref: "#/components/responses/Unauthorised"
      operationId: organisations-quotas-list
      description: Get the quotas for an organisation
  "/organisations/{organisation_id}/quotas/{quota_entity_quota}":
    parameters:
      - $ref: "#/components/parameters/organisation_id"
      - $ref: "#/components/parameters/quota_entity_quota"
    get:
      summary: Get specific organisation quota
      tags:
        - organisations
        - quotas
      security:
        - token: []
        - cookie: []
      responses:
        "200":
          $ref: "#/components/responses/QuotasList"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "403":
          $ref: "#/components/responses/Unauthorised"
      operationId: organisations-quotas-get
      description: Get a specific quota for an organisation

  # projects
  "/projects":
    get:
      parameters:
        - $ref: "#/components/parameters/pagination_page"
        - $ref: "#/components/parameters/filter_name"
      summary: List projects
      tags:
        - projects
      security:
        - token: []
        - cookie: []
      responses:
        "200":
          $ref: "#/components/responses/ProjectsList"
        "403":
          $ref: "#/components/responses/Unauthorised"
      operationId: projects-list
      description: "Get all projects for this user, paginated"
    post:
      summary: Create project
      operationId: projects-create
      responses:
        "201":
          $ref: "#/components/responses/Project"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Unauthorised"
        "409":
          $ref: "#/components/responses/ResourceConflict"
      description: Create a new project
      requestBody:
        $ref: "#/components/requestBodies/ProjectBody"
      tags:
        - projects
      security:
        - token: []
        - cookie: []

  "/projects/{project_id}":
    parameters:
      - $ref: "#/components/parameters/project_id"
    get:
      summary: Get project
      tags:
        - projects
      security:
        - token: []
        - cookie: []
      responses:
        "200":
          $ref: "#/components/responses/Project"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "403":
          $ref: "#/components/responses/Unauthorised"
      operationId: projects-get
      description: Get a specific project
    put:
      summary: Update project
      operationId: projects-update
      responses:
        "200":
          $ref: "#/components/responses/Project"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Unauthorised"
      description: Update project
      requestBody:
        $ref: "#/components/requestBodies/ProjectBodyPatch"
      tags:
        - projects
      security:
        - token: []
        - cookie: []
    delete:
      summary: Delete project
      operationId: projects-delete
      responses:
        "200":
          $ref: "#/components/responses/ResourceDeleted"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "403":
          $ref: "#/components/responses/Unauthorised"
      description: Delete project, this will also delete all the resources within the project
      tags:
        - projects
      security:
        - token: []
        - cookie: []

  # secrets
  "/projects/{project_id}/secrets":
    parameters:
      - $ref: "#/components/parameters/project_id"
    get:
      parameters:
        - $ref: "#/components/parameters/pagination_page"
        - $ref: "#/components/parameters/secret_type"
      summary: List project secrets of a specific type
      tags:
        - secrets
      security:
        - token: []
        - cookie: []
      responses:
        "200":
          $ref: "#/components/responses/SecretsList"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "403":
          $ref: "#/components/responses/Unauthorised"
      operationId: projects-secrets-list
      description: List project secrets of a specific type
    post:
      summary: Create project secret
      operationId: projects-secrets-create
      responses:
        "201":
          $ref: "#/components/responses/Secret"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Unauthorised"
        "409":
          $ref: "#/components/responses/ResourceConflict"
      description: Create a new project secret
      requestBody:
        $ref: "#/components/requestBodies/SecretBody"
      tags:
        - secrets
      security:
        - token: []
        - cookie: []

  "/projects/{project_id}/secrets/{secret_name}":
    parameters:
      - $ref: "#/components/parameters/project_id"
      - $ref: "#/components/parameters/secret_name"
    get:
      summary: Get project secret
      tags:
        - secrets
      security:
        - token: []
        - cookie: []
      responses:
        "200":
          $ref: "#/components/responses/Secret"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "403":
          $ref: "#/components/responses/Unauthorised"
      operationId: projects-secrets-get
      description: Get a specific project
    put:
      summary: Update project secret
      operationId: projects-secrets-update
      responses:
        "200":
          $ref: "#/components/responses/Secret"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Unauthorised"
      description: Update project
      requestBody:
        $ref: "#/components/requestBodies/SecretBodyPatch"
      tags:
        - secrets
      security:
        - token: []
        - cookie: []
    delete:
      summary: Delete project secret
      operationId: projects-secrets-delete
      responses:
        "200":
          $ref: "#/components/responses/ResourceDeleted"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "403":
          $ref: "#/components/responses/Unauthorised"
      description: Delete project secret, if the secret is still linked to an active/deployed function - it cannot be removed
      tags:
        - secrets
      security:
        - token: []
        - cookie: []

  "/projects/{project_id}/hosts":
    post:
      summary: Create host for project
      description: |
        Assign a host/domain to a project - hosts are globally unique and require verification, so a host cannot be assigned to multiple projects.

        A host can be a valid domain, either a root domain or a subdomain.
      operationId: projects-hosts-create
      tags:
        - hosts
      parameters:
        - $ref: "#/components/parameters/project_id"
      security:
        - token: []
        - cookie: []
      requestBody:
        $ref: "#/components/requestBodies/HostBody"
      responses:
        "200":
          $ref: "#/components/responses/Host"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "400":
          $ref: "#/components/responses/BadRequest"
        "409":
          $ref: "#/components/responses/ResourceConflict"
    get:
      summary: List hosts for project
      operationId: projects-hosts-list
      parameters:
        - $ref: "#/components/parameters/project_id"
        - $ref: "#/components/parameters/pagination_page"
      security:
        - token: []
        - cookie: []
      tags:
        - hosts
      responses:
        "200":
          $ref: "#/components/responses/HostsList"
        "404":
          $ref: "#/components/responses/ResourceNotFound"

  "/projects/{project_id}/hosts/{hostname}":
    get:
      summary: Get specific host by hostname
      operationId: projects-hosts-get
      parameters:
        - $ref: "#/components/parameters/project_id"
        - $ref: "#/components/parameters/hostname"
      security:
        - token: []
        - cookie: []
      tags:
        - hosts
      responses:
        "200":
          $ref: "#/components/responses/Host"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
    delete:
      summary: Delete specific host by hostname
      operationId: projects-hosts-delete
      parameters:
        - $ref: "#/components/parameters/project_id"
        - $ref: "#/components/parameters/hostname"
      security:
        - token: []
        - cookie: []
      tags:
        - hosts
      responses:
        "200":
          $ref: "#/components/responses/ResourceDeleted"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
    put:
      summary: Update specific host by hostname
      operationId: projects-hosts-update
      parameters:
        - $ref: "#/components/parameters/project_id"
        - $ref: "#/components/parameters/hostname"
      security:
        - token: []
        - cookie: []
      tags:
        - hosts
      requestBody:
        $ref: "#/components/requestBodies/HostBodyPatch"
      responses:
        "200":
          $ref: "#/components/responses/Host"
        "404":
          $ref: "#/components/responses/ResourceNotFound"

  "/projects/{project_id}/hosts/{hostname}/verify":
    post:
      summary: Schedule host verification task
      operationId: projects-hosts-verify-create
      parameters:
        - $ref: "#/components/parameters/project_id"
        - $ref: "#/components/parameters/hostname"
      security:
        - token: []
        - cookie: []
      tags:
        - hosts
      responses:
        "200":
          $ref: "#/components/responses/Host"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "400":
          $ref: "#/components/responses/BadRequest"

  "/projects/{project_id}/quotas":
    parameters:
      - $ref: "#/components/parameters/project_id"
    get:
      summary: List project quotas
      tags:
        - projects
        - quotas
      security:
        - token: []
        - cookie: []
      responses:
        "200":
          $ref: "#/components/responses/QuotasList"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "403":
          $ref: "#/components/responses/Unauthorised"
      operationId: projects-quotas-list
      description: Get the quotas for a project
  "/projects/{project_id}/quotas/{quota_entity_quota}":
    parameters:
      - $ref: "#/components/parameters/project_id"
      - $ref: "#/components/parameters/quota_entity_quota"
    get:
      summary: Get specific project quota
      tags:
        - projects
        - quotas
      security:
        - token: []
        - cookie: []
      responses:
        "200":
          $ref: "#/components/responses/QuotasList"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "403":
          $ref: "#/components/responses/Unauthorised"
      operationId: projects-quotas-get
      description: Get a specific quota for a project

  "/auth/tokens":
    post:
      summary: Create new auth token
      description: |
        Create new auth token for use with the CLI and TF Provider

        ### Warning
        The `token` field is only shown once and can't be retrieved again without generating a new token. Securely save this once the response has been received.
      security:
        - token: []
        - cookie: []
      tags:
        - tokens
      requestBody:
        $ref: "#/components/requestBodies/AuthTokenBody"
      responses:
        "200":
          $ref: "#/components/responses/AuthToken"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "400":
          $ref: "#/components/responses/BadRequest"
      operationId: auth-tokens-create
    get:
      summary: List all user auth tokens
      tags:
        - tokens
      parameters:
        - $ref: "#/components/parameters/pagination_page"
      security:
        - token: []
        - cookie: []
      responses:
        "200":
          $ref: "#/components/responses/AuthTokenList"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "400":
          $ref: "#/components/responses/BadRequest"
      operationId: auth-tokens-list

  "/auth/tokens/{token_id}":
    parameters:
      - $ref: "#/components/parameters/token_id"
    get:
      summary: Get token information
      tags:
        - tokens
      security:
        - token: []
        - cookie: []
      responses:
        "200":
          $ref: "#/components/responses/AuthTokenMeta"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "400":
          $ref: "#/components/responses/BadRequest"
      operationId: auth-tokens-get
    put:
      summary: Update token
      tags:
        - tokens
      security:
        - token: []
        - cookie: []
      requestBody:
        $ref: "#/components/requestBodies/AuthTokenPatch"
      responses:
        "200":
          $ref: "#/components/responses/AuthToken"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
        "400":
          $ref: "#/components/responses/BadRequest"
      operationId: auth-tokens-update
    delete:
      summary: Delete token
      tags:
        - tokens
      security:
        - token: []
        - cookie: []
      responses:
        "200":
          $ref: "#/components/responses/ResourceDeleted"
        "404":
          $ref: "#/components/responses/ResourceNotFound"
      operationId: auth-tokens-delete
  # "/projects/{project_id}/secrets/{secret_type}/{secret_id}/revisions":
  #   parameters:
  #     - $ref: "#/components/parameters/project_id"
  #     - $ref: "#/components/parameters/secret_type"
  #   get:
  #     parameters:
  #       - $ref: "#/components/parameters/pagination_page"
  #     summary: List project secrets of a specific type
  #     tags:
  #       - secrets
  #     security:
  #       - token: []
  #       - cookie: []
  #     responses:
  #       "200":
  #         $ref: "#/components/responses/ListSecrets"
  #       "404":
  #         $ref: "#/components/responses/ResourceNotFound"
  #       "403":
  #         $ref: "#/components/responses/Unauthorised"
  #     operationId: projects-secrets-list
  #     description: List project secrets of a specific type
  # "/projects/{project_id}/secrets/{secret_type}/{secret_id}/revisions/{revision_id}":
  #   parameters:
  #     - $ref: "#/components/parameters/project_id"
  #     - $ref: "#/components/parameters/secret_type"
  #   get:
  #     parameters:
  #       - $ref: "#/components/parameters/pagination_page"
  #     summary: List project secrets of a specific type
  #     tags:
  #       - secrets
  #     security:
  #       - token: []
  #       - cookie: []
  #     responses:
  #       "200":
  #         $ref: "#/components/responses/Secret"
  #       "404":
  #         $ref: "#/components/responses/ResourceNotFound"
  #       "403":
  #         $ref: "#/components/responses/Unauthorised"
  #     operationId: projects-secrets-revision-get
  #     description: List project secrets of a specific type
  # "/organisations/{organisation_id}/secrets":
  # functions
  '/projects/{project_id}/functions':
    get:
      summary: List all functions within a project
      description: List all functions
      parameters:
        - $ref: "#/components/parameters/project_id"
        - $ref: '#/components/parameters/pagination_page'
      security:
        - token: []
        - cookie: []
      tags:
        - functions
      responses:
        '200':
          $ref: '#/components/responses/ListFunction'
      operationId: projects-functions-list

  '/functions':
     post:
      summary: Create function
      operationId: functions-create
      security:
        - token: []
        - cookie: []
      responses:
        '201':
          $ref: '#/components/responses/Function'
        '400':
          $ref: '#/components/responses/BadRequest'
      description: Create a new function
      requestBody:
        $ref: '#/components/requestBodies/FunctionBody'
      tags:
        - functions

  '/functions/{function_id}':
    parameters:
      - $ref: '#/components/parameters/function_id'
    get:
      summary: Get function (latest revision)
      tags:
        - functions
      security:
        - token: []
        - cookie: []
      responses:
        '200':
          $ref: '#/components/responses/Function'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
      operationId: functions-get
      description: Get a specific function (latest revision)
    put:
      summary: Update function
      operationId: functions-update
      security:
        - token: []
        - cookie: []
      responses:
        '200':
          $ref: '#/components/responses/Function'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
      tags:
        - functions
      description: Update a function (creates a new revision)
      requestBody:
        $ref: '#/components/requestBodies/FunctionBodyPatch'
    delete:
      summary: Delete function
      operationId: functions-delete
      security:
        - token: []
        - cookie: []
      responses:
        '200':
          $ref: '#/components/responses/ResourceDeleted'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
      tags:
        - functions
      description: Delete a function (and all revisions)

  '/functions/{function_id}/revisions':
    parameters:
      - $ref: '#/components/parameters/function_id'
    get:
      summary: List all revisions for a function
      parameters:
        - $ref: '#/components/parameters/pagination_page'
      security:
        - token: []
        - cookie: []
      tags:
        - functions
      responses:
        '200':
          $ref: '#/components/responses/ListFunction'
      operationId: functions-revisions-list
      description: List all revisions for a function

  '/functions/{function_id}/revisions/{function_revision_id}':
    parameters:
      - $ref: '#/components/parameters/function_id'
      - $ref: '#/components/parameters/function_revision_id'
    get:
      summary: Get a specific revision of a function
      tags:
        - functions
      security:
        - token: []
        - cookie: []
      responses:
        '200':
          $ref: '#/components/responses/Function'
      operationId: functions-revisions-get
      description: Get a specific revision of a function

  # providers
  '/providers':
    get:
      parameters:
        - $ref: '#/components/parameters/pagination_page'
      summary: Get available providers
      tags:
        - providers
      responses:
        '200':
          $ref: '#/components/responses/ListProvider'
      operationId: providers-list
      description: Retrieve a list of all providers with their respective deployed regions and cities.
      security:
        - token: []
        - cookie: []

  # logs
  '/logs':
    get:
      parameters:
        - $ref: '#/components/parameters/pagination_page'
        - $ref: '#/components/parameters/filter_project'
        - $ref: '#/components/parameters/filter_function'
        - $ref: '#/components/parameters/filter_timestamps'
        - $ref: '#/components/parameters/filter_query'
        - $ref: '#/components/parameters/filter_log_type'
      summary: Get logs
      tags:
        - logs
      responses:
        '200':
          $ref: '#/components/responses/ListLog'
        '400':
          $ref: '#/components/responses/BadRequest'
      operationId: logs-list
      description: |
        Retrieve logs for a specific project or function. Use the query parameter to search logs.

        > Note: Logs are always returned in a descending order based on the timestamp.
        > Note: A max size of 500 logs is returned per request (when using page[size]).
      security:
        - token: []
        - cookie: []

  # metrics
  '/metrics/aggregations/{metric_aggregation_type}':
    get:
      parameters:
        - $ref: '#/components/parameters/metric_aggregation_type'
        - $ref: '#/components/parameters/filter_project'
        - $ref: '#/components/parameters/filter_function'
        - $ref: '#/components/parameters/filter_timestamps'
        - $ref: '#/components/parameters/filter_histogram_interval'
      summary: Get metrics
      tags:
        - metrics
      responses:
        '200':
          $ref: '#/components/responses/MetricAggregation'
        '400':
          $ref: '#/components/responses/BadRequest'
      operationId: metrics-aggregations-list
      description: |
        Retrieve metrics for a specific project or function. Use the query parameter to request a metrics report.

        > Note: Metrics are always returned in a descending order based on the timestamp.
      security:
        - token: []
        - cookie: []

components:
  # headers
  headers:
    Pagination-Total-Count:
      description: Total number of items available
      schema:
        type: integer
      example: 100
    Pagination-Page-Size:
      description: |
        Number of items returned in the current page.
        This is defined by the `page[size]` query parameter, if not specified it defaults to 20 and has a maximum of 100.
      schema:
        type: integer
      example: 20
    Pagination-Page-After:
      description: |
        The 'after' cursor for the current page, to be used to fetch the next page.
        This is defined by the `page[after]` query parameter.
      schema:
        type: integer
      example: 20
    Pagination-Page-Before:
      description: |
        The 'before' cursor for the current page, to be used to fetch the previous page.
        This is defined by the `page[before]` query parameter.
      schema:
        type: integer
      example: 0
    Pagination-Total-Pages:
      description: Total number of pages/iterations available based on the current page size
      schema:
        type: integer
      example: 5
    Link:
      description: |
        Pagination links in RFC 8288 Web Linking format.
        Relations used are; first, prev, next, last.
      schema:
        type: string
      example: |
        <https://chaos.qernal.com/v1/projects?page[size]=20&page[after]=20&page[before]=40>; rel="next",
        <https://chaos.qernal.com/v1/projects?page[size]=20&page[after]=40&page[before]=60>; rel="last"

  # schemas
  schemas:
    NotFoundResponse:
      description: "Resource not found"
      type: object
      properties:
        message:
          type: string
      required:
        - message
    UnauthorisedResponse:
      description: "Unauthorised"
      type: object
      properties:
        message:
          type: string
      required:
        - message
    BadRequestResponse:
      description: "Bad request"
      type: object
      properties:
        message:
          type: string
        fields:
          type: object
          properties:
            email:
              type: string
      required:
        - message
        - fields
    ConflictResponse:
      description: "Conflict Response"
      type: object
      properties:
        message:
          type: string
      required:
        - message
    DeletedResponse:
      description: "Deleted Response"
      type: object
      properties:
        message:
          type: string
      required:
        - message

    Date:
      description: Object date information
      type: object
      properties:
        created_at:
          type: string
          description: UTC creation datetime (ISO 8601 date format)
          format: datetime
          example: 2023-07-22T14:50:13Z20230722T145013Z
        updated_at:
          type: string
          description: UTC update datetime (ISO 8601 date format)
          format: datetime
          example: 2023-07-22T14:50:13Z20230722T145013Z
      required:
        - created_at
        - updated_at

    HostVerificationStatus:
      description: Host verification status
      type: string
      enum: [pending, already_verified, completed, failed]
      example: pending

    Host:
      description: Host response
      type: object
      properties:
        id:
          type: string
          description: Host id
          format: uuid
        host:
          type: string
          description: Hostname, this can be the root of a domain or a subdomain
          example: example-domain.com
          minLength: 1
          # TODO: add domain pattern
        certificate:
          type: string
          description: The secret reference to the certificate
          pattern: '^projects:(?<project_id>[a-z0-9-]{36})\/(?<secret_name>[A-Z0-9_]+)@(?<revision>[0-9]+)$'
          example: "projects:d8f6ede4-e3a4-414d-b6c3-b8a972773e56/MY_CERT@0"
        project_id:
          type: string
          description: Project ID this is attached to
          format: uuid
          minLength: 1
        read_only:
          type: boolean
          description: If the host is read only and cannot be removed, primarily used for *.qrnl.app domains
        disabled:
          type: boolean
          description: If the host is disabled, then this host won't be accessible and so the deployments will not be routable
        txt_verification:
          type: string
          description: TXT record of host to verify ownership - if this record is removed, it may become unverified as this is checked periodically to continually verify ownership
          example: qernal=my.app=KSjfasiqwePdsakm12kdas3
        verified_at:
          type: string
          description: UTC datetime when the host was verified (ISO 8601 date format).
          format: datetime
          example: 2023-07-22T14:50:13Z20230722T145013Z
        date:
          $ref: "#/components/schemas/Date"
        verification_status:
          $ref: "#/components/schemas/HostVerificationStatus"
      required:
        - id
        - host
        - project_id
        - read_only
        - disabled
        - txt_verification
        - date
        - verification_status

    HostBody:
      description: Host body
      type: object
      properties:
        host: #resolve:true
          $ref: '#/components/schemas/Host/properties/host'
        certificate: #resolve:true
          $ref: '#/components/schemas/Host/properties/certificate'
        disabled: #resolve:true
          $ref: '#/components/schemas/Host/properties/disabled'
      required:
        - host
        - certificate
        - disabled

    HostBodyPatch:
      description: Host body update
      type: object
      properties:
        certificate: #resolve:true
          $ref: '#/components/schemas/Host/properties/certificate'
        disabled: #resolve:true
          $ref: '#/components/schemas/Host/properties/disabled'

    AuthTokenBody:
      description: API auth token create
      type: object
      properties:
        name:
          type: string
          description: Name of token
          example: tf-token
          pattern: "^[A-z-]+$"
        expiry_duration:
          type: integer
          description: Token expiration duration in days. 0 - token will never expire
          example: 90
      required:
        - name
        - expiry_duration

    AuthTokenPatch:
      description: API auth token patch
      properties:
        name: #resolve:true
          $ref: '#/components/schemas/AuthTokenBody/properties/name'
        expiry_duration: #resolve:true
          $ref: '#/components/schemas/AuthTokenBody/properties/expiry_duration'

    AuthToken:
      description: API auth token
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Auth token uuid
          example: 51687d2f-07b0-4260-8ecb-f5098305fdd4
        user_id:
          type: string
          description: User
          format: uuid
          example: a01594c7-3ebf-4ad1-8565-a7895e9c2d49
        name:
          type: string
          description: Name of token
          example: "TF Token"
        expiry_at:
          type: string
          format: datetime
          example: 2023-07-22T14:50:13Z20230722T145013Z
          description: When the token expires
        token:
          type: string
          description: Combined token required for requesting an access token, this field is only returned once on creation or update (during regeneration).
          example: 51687d2f-07b0-4260-8ecb-f5098305fdd4@T.KcV~_96jfOoD5ixFP8qu0Spm
        date:
          $ref: "#/components/schemas/Date"
      required:
        - id
        - name
        - user_id
        - date

    AuthTokenMeta:
      description: API auth token meta
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 51687d2f-07b0-4260-8ecb-f5098305fdd4
        user_id:
          type: string
          description: User
          format: uuid
          example: a01594c7-3ebf-4ad1-8565-a7895e9c2d49
        name:
          type: string
          description: Name of token
          example: "TF Token"
        expiry_at:
          type: string
          format: datetime
          example: 2023-07-22T14:50:13Z20230722T145013Z
        date:
          $ref: "#/components/schemas/Date"
      required:
        - id
        - name
        - user_id
        - date

    # TODO: remove
    PaginationMeta:
      description: Meta object for pagination use
      type: object
      properties:
        results:
          type: integer
          example: 200
        start:
          type: integer
          example: 20
        end:
          type: integer
          example: 40
        pages:
          type: integer
          example: 20
        links:
          $ref: "#/components/schemas/PaginationLinks"
      required:
        - results
        - start
        - end
        - pages
        - links

    # TODO: remove
    PaginationLinks:
      description: Links object for pagination use
      type: object
      properties:
        prev:
          type: string
          minLength: 1
          example: /{url}?page[before]=20&page[size]=20
        next:
          type: string
          minLength: 1
          example: /{url}?page[after]=40&page[size]=20
      required:
        - prev
        - next

    Organisation:
      description: Organisation response/object
      type: object
      properties:
        id:
          type: string
          description: Organisation id
          format: uuid
          minLength: 1
          example: 3069614e-adc8-47cb-a69c-decf9c5f90fc
        user_id:
          type: string
          description: User id
          format: uuid
          minLength: 1
          example: 3069614e-adc8-47cb-a69c-decf9c5f90fc
        billing_account_id:
          type: string
          description: Billing account id
          format: uuid
          minLength: 1
          example: 3069614e-adc8-47cb-a69c-decf9c5f90fc
        name:
          type: string
          description: Organisation name
          minLength: 1
          pattern: "^[A-z-]+$"
          example: my-org
        date:
          $ref: "#/components/schemas/Date"
      required:
        - id
        - user_id
        - name
        - date
    OrganisationBody:
      description: Organisation body
      type: object
      properties:
        name: #resolve:true
          $ref: '#/components/schemas/Organisation/properties/name'
        billing_account_id: #resolve:true
          $ref: '#/components/schemas/Organisation/properties/billing_account_id'
      required:
        - name
        - billing_account_id
    OrganisationBodyPatch:
      description: Organisation patch fields
      type: object
      properties:
        name: #resolve:true
          $ref: '#/components/schemas/Organisation/properties/name'
        billing_account_id: #resolve:true
          $ref: '#/components/schemas/Organisation/properties/billing_account_id'

    Project:
      description: Project response/object
      type: object
      properties:
        id:
          type: string
          description: Project id
          format: uuid
          minLength: 1
          example: 3069614e-adc8-47cb-a69c-decf9c5f90fc
        org_id:
          type: string
          description: Organisation id
          format: uuid
          minLength: 1
          example: 3069614e-adc8-47cb-a69c-decf9c5f90fc
        name:
          type: string
          description: Project name
          minLength: 1
          pattern: "^[A-z-]+$"
          example: first-api
        date:
          $ref: "#/components/schemas/Date"
      required:
        - id
        - org_id
        - name
        - date

    ProjectBody:
      description: Project body
      type: object
      properties:
        org_id: #resolve:true
          $ref: '#/components/schemas/Project/properties/org_id'
        name: #resolve:true
          $ref: '#/components/schemas/Project/properties/name'
      required:
        - org_id
        - name

    ProjectBodyPatch:
      description: Project patch fields
      type: object
      properties:
        org_id: #resolve:true
          $ref: '#/components/schemas/Project/properties/org_id'
        name: #resolve:true
          $ref: '#/components/schemas/Project/properties/name'

    # secrets
    Secret:
      description: Secret response/object
      type: object
      properties:
        name:
          type: string
          description: Secret name
          minLength: 1
          pattern: "^[A-Z0-9_]+$"
          example: MY_SECRET_25
        type:
          $ref: "#/components/schemas/SecretType"
        payload:
          oneOf:
            - $ref: "#/components/schemas/SecretCertificatePayload"
            - $ref: "#/components/schemas/SecretRegistryPayload"
            - $ref: "#/components/schemas/SecretDekPayload"
            - $ref: "#/components/schemas/SecretEnvironmentPayload"
        revision:
          type: integer
          description: Secret revision
          example: 32
        date:
          $ref: "#/components/schemas/Date"
      required:
        - name
        - type
        - revision
        - date

    SecretType:
      description: "Secrets types: registry, certificate, environment, dek"
      enum: ["registry", "certificate", "environment", "dek"]
      example: "registry"

    SecretEnvironmentPayload:
      description: Secret metadata environment payload

    SecretCertificatePayload:
      description: Secret metadata certificate payload
      type: object
      properties:
        certificate:
          type: string
          minLength: 1
          description: Public TLS certificate
          example: "<x509 content in PEM format>"
          format: string
      required:
        - certificate

    SecretRegistryPayload:
      description: Secret metadata registry payload
      type: object
      properties:
        registry:
          type: string
          description: |
            Private registry domain/location, when using the private docker hub registry sepcify `docker.io`
            > Without http scheme
          example: ghcr.io
          format: hostname
      required:
        - registry

    SecretDekPayload:
      description: "DEK secret, `type: dek`"
      type: object
      properties:
        dek:
          type: string
          description: Base64 encoded Data Encryption Key (DEK)
      required:
        - dek

    SecretBodyPayload:
      description: Payload for secret
      type: object
      oneOf:
        - $ref: "#/components/schemas/SecretBodyRegistryPayload"
        - $ref: "#/components/schemas/SecretBodyEnvironmentPayload"
        - $ref: "#/components/schemas/SecretBodyCertificatePayload"

    SecretBodyType:
      description: "Secrets types: registry, certificate, environment"
      enum: ["registry", "certificate", "environment"]
      example: "registry"

    SecretBodyEnvironmentPayload:
      description: "Encrypted ENV secret, `type: environment`"
      type: object
      properties:
        environment_value:
          type: string
          format: base64
          description: Encrypted environment value
          example: SGVsbG8gd29ybGQ=
      required:
        - environment_value

    SecretBodyCertificatePayload:
      description: "Encrypted TLS private key and plain certificate.
        Certificate expected in x509 pem format, key expected in pkcs8 or pkcs1 pem format.
        `type: certificate`"
      type: object
      properties:
        certificate: #resolve:true
          $ref: "#/components/schemas/SecretCertificatePayload/properties/certificate"
        certificate_value:
          type: string
          format: base64
          description: Encrypted certificate private key
          example: <base64 encrypted pkcs8 or pkcs1 pem format>
      required:
        - certificate
        - certificate_value

    SecretBodyRegistryPayload:
      description: "Encrypted private container registry, `type: registry`"
      type: object
      properties:
        registry: #resolve:true
          $ref: "#/components/schemas/SecretRegistryPayload/properties/registry"
        registry_value:
          type: string
          format: base64
          description: Token used for auth to the registry
          example: SGVsbG8gd29ybGQ=
      required:
        - registry
        - registry_value

    SecretBody:
      description: Secret body
      type: object
      properties:
        name: #resolve:true
          $ref: '#/components/schemas/Secret/properties/name'
        type:
          $ref: "#/components/schemas/SecretBodyType"
        payload:
          $ref: "#/components/schemas/SecretBodyPayload"
        encryption:
          type: string
          description: Encryption entity
          example: keys/DEK/123
          pattern: "^keys\\/DEK\\/[0-9]+$"
      required:
        - name
        - type
        - payload
        - encryption

    SecretBodyPatch:
      description: Secret body patch fields
      type: object
      properties:
        payload:
          $ref: "#/components/schemas/SecretBodyPayload"
        encryption: #resolve:true
          $ref: '#/components/schemas/SecretBody/properties/encryption'
      required:
        - payload
        - encryption

    Location:
      type: object
      description: Location of allowed clusters
      properties:
        provider_id:
          type: string
          format: uuid
          description: UUID of provider to deploy into
          example: 51687d2f-07b0-4260-8ecb-f5098305fdd4
        continent:
          type: string
          description: Deployment continent
          example: EU
        country:
          type: string
          description: Deployment country
          example: GB
        city:
          type: string
          description: Deployment city
          example: London
      required:
        - provider_id

    FunctionScaling:
      type: object
      description: Scaling logic
      properties:
        type:
          type: string
          description: CPU or Memory supported
          enum: [cpu, memory]
          example: cpu
        low:
          type: integer
          description: For type to drop below before scale down
          minLength: 1
          example: 30
        high:
          type: integer
          description: For type to go above before scale up
          minLength: 1
          example: 60
      required:
        - type
        - low
        - high

    FunctionReplicas:
      type: object
      description: Balancing logic
      properties:
        min:
          type: integer
          description: Minimum number of replicas to have
          minLength: 1
          example: 1
        max:
          type: integer
          description: Maximum number of replicas to have
          minLength: 1
          example: 5
        affinity:
          type: object
          description: Replica strategy
          properties:
            cluster:
              type: boolean
              description: If there are > 1 replica, make sure they're on different clusters
              example: true
            cloud:
              type: boolean
              description: If there are > 1 replica, make sure they're on different clouds
              example: true
          required:
            - cluster
            - cloud
      required:
        - min
        - max
        - affinity

    FunctionEnv:
      type: object
      description: Environment variable for function
      properties:
        name:
          type: string
          description: Key name
          example: MY_ENV_VAR
          pattern: "^[A-Z_]+$"
        reference:
          type: string
          description: |
            Reference for the secret, it's split up into 4 main parts;
            - [1] "projects:" - This references which resource type the secret is within
            - [2] "0a6b9ff3-6807-4820-b94b-5e1d7efcdd93" - The project UUID the secret is within
            - [3] "MY_SECRET" - The name of the secret
            - [4] "0" - The revision of the secret to use
          example: "projects:0a6b9ff3-6807-4820-b94b-5e1d7efcdd93/MY_SECRET@0"
          pattern: '^projects\:(?<project_id>[a-z0-9-]{36})/(?<secret_name>[A-Z0-9_]+\\@[0-9]+)$'
      required:
        - name
        - reference

    FunctionCompliance:
      type: string
      description: |
        Tagged requirements for compliance;
        soc2 = SOC2 compliant data centers
        ipv6 = Function can work within an ipv6 *only* cluster
      enum: [soc2, ipv6]

    FunctionType:
      type: string
      enum: [http, worker]
      description: Type of function, worker types are not exposed to ingress routes
      example: http

    FunctionSize:
      type: object
      description: Size of function, required CPU and Memory
      properties:
        cpu:
          type: integer
          description: |
            CPU in 0.1 vCPU increments, for a whole vCPU specify 1024
            Must be in multiples of 128, with the same multiplier as memory
            from the base
          example: 128
        memory:
          type: integer
          description: |
            Memory in 128 MB increments, values are integer always in MB
            Must be in multiples of 128, with the same multiplier as CPU
            from the base
          example: 128
      required:
        - cpu
        - memory

    FunctionDeployment:
      type: object
      properties:
        id:
          type: string
          description: ID of the deployment
          format: uuid
          example: 51687d2f-07b0-4260-8ecb-f5098305fdd4
        location:
          $ref: "#/components/schemas/Location"
        replicas:
          $ref: "#/components/schemas/FunctionReplicas"
      required:
        - location
        - replicas

    FunctionDeploymentBody:
      type: object
      properties:
        location:
          $ref: "#/components/schemas/Location"
        replicas:
          $ref: "#/components/schemas/FunctionReplicas"
      required:
        - location
        - replicas

    FunctionRoute:
      type: object
      properties:
        path:
          type: string
          description: Can be a regular expression
          example: /hello/{0-9+}
          minLength: 1
        methods:
          type: array
          description: HTTP Verb(s) for this function
          items:
            type: string
            example: GET
          example: [GET, POST]
        weight:
          type: integer
          description: The route weight for consideration
          example: 50
          minLength: 1
      required: [path, methods, weight]

    Function:
      type: object
      description: Function
      properties:
        id:
          type: string
          description: ID of the function
          minLength: 1
          format: uuid
          example: 51687d2f-07b0-4260-8ecb-f5098305fdd4
        project_id:
          type: string
          description: ID of the project this function belongs to
          format: uuid
          example: 51687d2f-07b0-4260-8ecb-f5098305fdd4
        version:
          type: string
          enum: ['1.0.0']
          description: Function spec version
          example: '1.0.0'
        name:
          type: string
          description: Name of the function
          minLength: 1
          example: my-function
        description:
          type: string
          description: Description of what the function does
          example: My function does this
        image:
          type: string
          description: Path to container image
          minLength: 1
          example: docker.io/my-image:latest
        revision:
          type: string
          description: Function revision
          format: uuid
          example: 51687d2f-07b0-4260-8ecb-f5098305fdd4
        type:
          $ref: "#/components/schemas/FunctionType"
        size:
          $ref: "#/components/schemas/FunctionSize"
        port:
          type: integer
          description: Port the application runs on
          example: 8080
        routes:
          type: array
          description: The public route/path to this function, only applicable to http type functions
          items:
            $ref: "#/components/schemas/FunctionRoute"
        scaling:
          $ref: "#/components/schemas/FunctionScaling"
        deployments:
          type: array
          description: List of deployments for this function
          items:
            $ref: "#/components/schemas/FunctionDeployment"
        secrets:
          type: array
          description: List of environment variables for secrets
          items:
            $ref: "#/components/schemas/FunctionEnv"
        compliance:
          type: array
          description: Tags to limit deployment
          items:
            $ref: "#/components/schemas/FunctionCompliance"
      required:
        - id
        - project_id
        - version
        - name
        - description
        - image
        - revision
        - type
        - size
        - port
        - scaling
        - deployments
        - secrets
        - compliance

    FunctionBody:
      description: Function create body
      type: object
      properties:
        project_id: #resolve:true
          $ref: "#/components/schemas/Function/properties/project_id"
        version: #resolve:true
          $ref: "#/components/schemas/Function/properties/version"
        name: #resolve:true
          $ref: "#/components/schemas/Function/properties/name"
        description: #resolve:true
          $ref: "#/components/schemas/Function/properties/description"
        image: #resolve:true
          $ref: "#/components/schemas/Function/properties/image"
        type:
          $ref: "#/components/schemas/FunctionType"
        size:
          $ref: "#/components/schemas/FunctionSize"
        port: #resolve:true
          $ref: "#/components/schemas/Function/properties/port"
        routes:
          type: array
          description: The public route/path to this function, only applicable to http type functions
          items:
            $ref: "#/components/schemas/FunctionRoute"
        scaling:
          $ref: "#/components/schemas/FunctionScaling"
        deployments:
          type: array
          description: List of deployments for this function
          items:
            $ref: "#/components/schemas/FunctionDeploymentBody"
        secrets:
          type: array
          description: List of environment variables for secrets
          items:
            $ref: "#/components/schemas/FunctionEnv"
        compliance:
          type: array
          description: Tags to limit deployment
          items:
            $ref: "#/components/schemas/FunctionCompliance"
      required:
        - project_id
        - version
        - name
        - description
        - image
        - type
        - size
        - port
        - scaling
        - deployments
        - secrets
        - compliance

    ListFunction:
      type: object
      description: 'List of functions'
      properties:
        meta:
          $ref: '#/components/schemas/PaginationMeta'
          links:
            $ref: '#/components/schemas/PaginationLinks'
        data:
          type: array
          items:
            $ref: '#/components/schemas/Function'
      required:
        - meta
        - data

    Provider:
      description: List of providers
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 51687d2f-07b0-4260-8ecb-f5098305fdd4
        name:
          type: string
          minLength: 1
          description: Name of provider
          example: AWS
        locations:
          type: object
          description: Locations at varying levels this provider operates within
          properties:
            continents:
              type: array
              items:
                type: string
                description: Deployment continent
                example: EU
            countries:
              type: array
              items:
                type: string
                description: Deployment country
                example: GB
            cities:
              type: array
              items:
                type: string
                description: Deployment city
                example: London
          required:
            - continents
            - countries
            - cities
      required:
        - id
        - name
        - locations

    Log:
      description: List of logs
      type: object
      properties:
        container:
          type: string
          description: Container ID the log line is for
          example: 51687d2f-07b0-4260-8ecb-f5098305fdd4
        function:
          type: string
          description: Function ID the log line is for
          format: uuid
          example: 51687d2f-07b0-4260-8ecb-f5098305fdd4
        project:
          type: string
          description: Project ID the log line is for
          format: uuid
          example: 51687d2f-07b0-4260-8ecb-f5098305fdd4
        organisation:
          type: string
          description: Organisation ID the log line is for
          format: uuid
          example: 51687d2f-07b0-4260-8ecb-f5098305fdd4
        group:
          type: string
          description: Group ID the log line is for
          format: string
          example: 450983055444
        log:
          description: Log item
          type: object
          properties:
            stream:
              type: string
              enum: [stdout, stderr]
              description: Which log stream
              example: stdout
            kind:
              type: string
              enum: [event, log]
              description: If this was an event on the function or a log line
              example: log
            labels:
              type: array
              description: An array of labels
              items:
                type: string
                description: Text label - may include provider or region it came from
                example: aws
            type:
              type: string
              enum: [info, error]
              description: Log line type
              example: error
            line:
              type: string
              description: Log line
              example: Application started successfully, listening on port 3000
            timestamp:
              type: string
              description: The date/time that this log was generated
              format: datetime
              example: 2023-07-22T14:50:13Z20230722T145013Z

    ListProviderResponse:
      type: object
      description: "List of providers"
      properties:
        meta:
          $ref: "#/components/schemas/PaginationMeta"
          links:
            $ref: "#/components/schemas/PaginationLinks"
        data:
          type: array
          items:
            $ref: "#/components/schemas/Provider"
      required:
        - meta
        - data

    ListLogResponse:
      type: object
      description: "List of log"
      properties:
        meta:
          $ref: "#/components/schemas/PaginationMeta"
          links:
            $ref: "#/components/schemas/PaginationLinks"
        data:
          type: array
          items:
            $ref: "#/components/schemas/Log"
      required:
        - meta
        - data

    MetricResourceAggregation:
      description: Metric resource aggregation
      type: object
      properties:
        resources:
          description: Resource(s) aggregation
          type: object
          properties:
            buckets:
              description: Array of unqiue resources
              type: array
              items:
                description: Histogram bucket
                type: object
                properties:
                  doc_count:
                    description: Number of documents in the bucket
                    type: integer
                    example: 33846
                  histogram:
                    description: Histogram of resource usage
                    type: object
                    properties:
                      buckets:
                        description: |
                          Array of resource usage by interval

                          > Note: A metric will have either a `counter` or `gauge` value
                        type: array
                        items:
                          type: object
                          properties:
                            doc_count:
                              description: Number of documents in the bucket
                              type: integer
                              example: 8173
                            counter:
                              description: Counter (monotonically incrementing)
                              type: object
                              properties:
                                avg:
                                  description: Average counter value
                                  type: number
                                  example: 401989004.45192075
                                  nullable: true
                                count:
                                  description: Number of counter values
                                  type: integer
                                  example: 8174
                                  nullable: true
                                max:
                                  description: Maximum counter value
                                  type: number
                                  example: 2850721300
                                  nullable: true
                                min:
                                  description: Minimum counter value
                                  type: number
                                  example: 9922579
                                  nullable: true
                                sum:
                                  description: Sum of counter values
                                  type: number
                                  example: 3285858122390
                                  nullable: true
                            gauge:
                              description: Gauge (value at a point in time)
                              type: object
                              properties:
                                avg:
                                  description: Average gauge value
                                  type: number
                                  example: 2703633.5168236876
                                  nullable: true
                                count:
                                  description: Number of gauge values
                                  type: integer
                                  example: 8173
                                  nullable: true
                                max:
                                  description: Maximum gauge value
                                  type: number
                                  example: 360253860
                                  nullable: true
                                min:
                                  description: Minimum gauge value
                                  type: number
                                  example: 1604225
                                  nullable: true
                                sum:
                                  description: Sum of gauge values
                                  type: number
                                  example: 22096796733
                            key:
                              description: Histogram key (typically unix timestamp)
                              type: number
                              example: 1738108800000
                            key_as_string:
                              description: Histogram key as string/date-time
                              type: string
                              example: '2025-01-29T00:00:00Z'
                  key:
                    description: Metric key
                    type: string
                    example: cpu-usage
            doc_count_error_upper_bound:
              description: Upper bound of error in document count
              type: integer
              example: 0
            sum_other_doc_count:
              description: Sum of other document counts
              type: integer
              example: 0

    MetricHttpAggregation:
      description: Metric http aggregation
      type: object
      properties:
        http_codes:
          description: HTTP status code aggregation
          type: object
          properties:
            buckets:
              description: Array of unique http status codes
              type: array
              items:
                description: HTTP status code bucket
                type: object
                properties:
                  doc_count:
                    description: Number of documents in the bucket
                    type: integer
                    example: 26
                  histogram:
                    description: Histogram of http status code usage
                    type: object
                    properties:
                      buckets: #resolve:true
                        $ref: "#/components/schemas/MetricResourceAggregation/properties/resources/properties/buckets/items/properties/histogram/properties/buckets"
                  key:
                    description: |
                      HTTP status code, typical values will be;

                      - http-2xx
                      - http-3xx
                      - http-4xx
                      - http-5xx

                      > Note: the 'xx' is intentional and literal, all status codes within that range will be grouped
                    type: string
                    example: http-2xx
            doc_count_error_upper_bound:
              description: Upper bound of error in document count
              type: integer
              example: 0
            sum_other_doc_count:
              description: Sum of other document counts
              type: integer
              example: 0

    # quotas
    ListQuotas:
      type: array
      description: 'List of quota limits and usage'
      items:
        $ref: '#/components/schemas/Quota'

    Quota:
      type: object
      description: Quota usage
      properties:
        name:
          description: Quota name
          type: string
          example: projects_functions_cpu_cores
        description:
          description: Quota description
          type: string
          example: Number of CPU cores for projects functions per project
        limit:
          description: Quota limit
          type: integer
          example: 100
        usage:
          description: Quota usage
          type: integer
          example: 50
        type:
          description: Quota type (group)
          type: string
          example: project
      required:
        - name
        - description
        - limit
        - usage
        - type

    # billing
    ListBillingAccounts:
      type: array
      description: "List of billing accounts"
      items:
        $ref: "#/components/schemas/BillingAccount"

    BillingAccount:
      type: object
      description: Billing account
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the billing account
          example: "123e4567-e89b-12d3-a456-426614174000"
        user_id:
          type: string
          format: uuid
          description: User ID associated with the billing account
          example: "641adf03-0bd2-42e6-9166-cb57008d60eb"
        name:
          type: string
          description: Name of the billing account
          example: "Business Account"
        state:
          type: string
          enum: [created, active, inactive, suspended, deleted]
          description: Current state of the billing account - new accounts are created with state "created" until a card is added
          example: "active"
        balance:
          type: number
          format: float
          description: Current balance of the billing account
          example: 100.50
        # TODO: reference date fields
        created_at:
          type: string
          format: date-time
          description: Timestamp when the billing account was created
          example: "2023-01-01T00:00:00Z"
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the billing account was last updated
          example: "2023-01-01T00:00:00Z"

    BillingAccountBody:
      description: Billing account body
      type: object
      properties:
        # TODO: change fields to match Midas
        name: #resolve:true
          $ref: '#/components/schemas/BillingAccount/properties/name'
      required:
        - name

    PaymentMethod:
      type: object
      description: Payment method
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the payment method
          example: "71afba61-e7b4-4072-a2b4-099c8c2cfcba"
        billing_account: #resolve:true
          $ref: '#/components/schemas/BillingAccount/properties/id'
        name:
          type: string
          description: Name on the payment method
          example: "Amex Business Gold"
        state:
          type: string
          enum: [active, inactive, suspended, deleted]
          description: Current state of the payment method
          example: "active"
        address:
          type: object
          description: Billing address associated with the payment method
          properties:
            title:
              type: string
              description: Title of the cardholder
              example: "Mr"
            first_name:
              type: string
              description: First name of the cardholder
              example: "John"
            last_name:
              type: string
              description: Last name of the cardholder
              example: "Doe"
            organisation:
              type: string
              description: Organisation name, if applicable
              example: "Acme Corp"
            address_line1:
              type: string
              description: First line of the address
              example: "123 Main St"
            address_line2:
              type: string
              description: Second line of the address, if applicable
              example: "Suite 400"
            city:
              type: string
              description: City of the address
              example: "Metropolis"
            county:
              type: string
              description: County or state of the address
              example: "CA"
            postal_code:
              type: string
              description: Postal or ZIP code of the address
              example:
                - "10001"
                - "SW1A 1AA"
            country:
              type: string
              description: Country of the address (ISO 3166-1 alpha-2 code)
              example: "US"
            phone_number:
              type: string
              description: Contact phone number associated with the payment method
              example: "+1-555-123-4567"

    PaymentMethodBody:
      description: Payment method body
      type: object
      properties:
        name: #resolve:true
          $ref: '#/components/schemas/PaymentMethod/properties/name'
        # address fields
        title: #resolve:true
          $ref: '#/components/schemas/PaymentMethod/properties/address/properties/title'
        first_name: #resolve:true
          $ref: '#/components/schemas/PaymentMethod/properties/address/properties/first_name'
        last_name: #resolve:true
          $ref: '#/components/schemas/PaymentMethod/properties/address/properties/last_name'
        organisation: #resolve:true
          $ref: '#/components/schemas/PaymentMethod/properties/address/properties/organisation'
        address_line1: #resolve:true
          $ref: '#/components/schemas/PaymentMethod/properties/address/properties/address_line1'
        address_line2: #resolve:true
          $ref: '#/components/schemas/PaymentMethod/properties/address/properties/address_line2'
        city: #resolve:true
          $ref: '#/components/schemas/PaymentMethod/properties/address/properties/city'
        county: #resolve:true
          $ref: '#/components/schemas/PaymentMethod/properties/address/properties/county'
        postal_code: #resolve:true
          $ref: '#/components/schemas/PaymentMethod/properties/address/properties/postal_code'
        country: #resolve:true
          $ref: '#/components/schemas/PaymentMethod/properties/address/properties/country'
        phone_number: #resolve:true
          $ref: '#/components/schemas/PaymentMethod/properties/address/properties/phone_number'

    PaymentMethodCreate:
      description: Payment method create response
      type: object
      properties:
        payment_method_id:  #resolve:true
          $ref: '#/components/schemas/PaymentMethod/properties/id'
        billing_account_id: #resolve:true
          $ref: '#/components/schemas/BillingAccount/properties/id'
        name: #resolve:true
          $ref: '#/components/schemas/PaymentMethod/properties/name'
        description:
          type: string
          description: Description of this order (e.g. payment authorisation)
        state:  #resolve:true
          $ref: '#/components/schemas/PaymentMethod/properties/state'
        links:
          type: object
          description: Links related to the payment method, such as checkout URL
          properties:
            checkout:
              type: string
              format: uri
              description: URL for the payment method checkout
              example: "https://checkout.paymentprovider.com/pay"
            created_at:
              type: string
              format: date-time
              description: Timestamp when the checkout link was created
              example: "2023-01-01T00:00:00Z"
            expires_at:
              type: string
              format: date-time
              description: Timestamp when the checkout link expires
              example: "2023-01-02T00:00:00Z"

    ListPaymentMethods:
      type: array
      description: "List of payment methods"
      items:
        $ref: "#/components/schemas/PaymentMethod"

  # responses
  responses:
    NoContent:
      description: The resources were updated successfully
    Unauthorised:
      description: Unauthorised
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/UnauthorisedResponse"
          examples:
            generic-unauthorised-response:
              value:
                message: "Unauthorised"
    ResourceNotFound:
      description: Resource Not Found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/NotFoundResponse"
          examples:
            generic-not-found-response:
              value:
                message: "Resource not found"
    ResourceConflict:
      description: Resource Conflict
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ConflictResponse"
          examples:
            generic-conflict-response:
              value:
                message: "Conflict, Resource already exists"
    ResourceDeleted:
      description: Resource deleted
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/DeletedResponse"
          examples:
            generic-deleted-response:
              value:
                message: "Resource deleted"
    BadRequest:
      description: Resource Bad Request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/BadRequestResponse"
          examples:
            generic-bad-request-response:
              value:
                message: "Missing fields"
                fields:
                  generic_field: Valid field required
    Host:
      description: Porject host
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Host"

    HostsList:
      description: List of project hosts
      headers: # TODO: we should find a way to deduplicate these
        Pagination-Total-Count:
          $ref: "#/components/headers/Pagination-Total-Count"
        Pagination-Page-Size:
          $ref: "#/components/headers/Pagination-Page-Size"
        Pagination-Page-After:
          $ref: "#/components/headers/Pagination-Page-After"
        Pagination-Page-Before:
          $ref: "#/components/headers/Pagination-Page-Before"
        Pagination-Total-Pages:
          $ref: "#/components/headers/Pagination-Total-Pages"
        Link:
          $ref: "#/components/headers/Link"
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/Host"

    AuthToken:
      description: Generated token response
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AuthToken"

    AuthTokenMeta:
      description: Token meta information
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AuthTokenMeta"

    AuthTokenList:
      description: List of auth token meta
      headers: # TODO: we should find a way to deduplicate these
        Pagination-Total-Count:
          $ref: "#/components/headers/Pagination-Total-Count"
        Pagination-Page-Size:
          $ref: "#/components/headers/Pagination-Page-Size"
        Pagination-Page-After:
          $ref: "#/components/headers/Pagination-Page-After"
        Pagination-Page-Before:
          $ref: "#/components/headers/Pagination-Page-Before"
        Pagination-Total-Pages:
          $ref: "#/components/headers/Pagination-Total-Pages"
        Link:
          $ref: "#/components/headers/Link"
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/AuthTokenMeta"

    OrganisationsList:
      description: List organisations
      headers: # TODO: we should find a way to deduplicate these
        Pagination-Total-Count:
          $ref: "#/components/headers/Pagination-Total-Count"
        Pagination-Page-Size:
          $ref: "#/components/headers/Pagination-Page-Size"
        Pagination-Page-After:
          $ref: "#/components/headers/Pagination-Page-After"
        Pagination-Page-Before:
          $ref: "#/components/headers/Pagination-Page-Before"
        Pagination-Total-Pages:
          $ref: "#/components/headers/Pagination-Total-Pages"
        Link:
          $ref: "#/components/headers/Link"
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/Organisation"

    Organisation:
      description: Get organisation
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Organisation"

    ProjectsList:
      description: List projects
      headers: # TODO: we should find a way to deduplicate these
        Pagination-Total-Count:
          $ref: "#/components/headers/Pagination-Total-Count"
        Pagination-Page-Size:
          $ref: "#/components/headers/Pagination-Page-Size"
        Pagination-Page-After:
          $ref: "#/components/headers/Pagination-Page-After"
        Pagination-Page-Before:
          $ref: "#/components/headers/Pagination-Page-Before"
        Pagination-Total-Pages:
          $ref: "#/components/headers/Pagination-Total-Pages"
        Link:
          $ref: "#/components/headers/Link"
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/Project"
    Project:
      description: Get project
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Project"

    SecretsList:
      description: List secrets
      headers: # TODO: we should find a way to deduplicate these
        Pagination-Total-Count:
          $ref: "#/components/headers/Pagination-Total-Count"
        Pagination-Page-Size:
          $ref: "#/components/headers/Pagination-Page-Size"
        Pagination-Page-After:
          $ref: "#/components/headers/Pagination-Page-After"
        Pagination-Page-Before:
          $ref: "#/components/headers/Pagination-Page-Before"
        Pagination-Total-Pages:
          $ref: "#/components/headers/Pagination-Total-Pages"
        Link:
          $ref: "#/components/headers/Link"
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/Secret"

    Secret:
      description: Get secret
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Secret"

    # SecretMeta:
    #   description: Get secret metadata
    #   content:
    #     application/json:
    #       schema:
    #         $ref: "#/components/schemas/SecretMeta"
    #       examples:
    #         secret-meta-registry:
    #           value:
    #             name: "FIRST_SECRET"
    #             type: registry
    #             payload:
    #               registry: "ghcr.io"
    #             date:
    #               created_at: "2023-07-22T14:50:13Z20230722T145013Z"
    #               updated_at: "2023-07-22T14:50:13Z20230722T145013Z"
    #         secret-meta-certificate:
    #           value:
    #             name: "FIRST_SECRET"
    #             type: certificate
    #             payload:
    #               domain: "ghcr.io"
    #             date:
    #               created_at: "2023-07-22T14:50:13Z20230722T145013Z"
    #               updated_at: "2023-07-22T14:50:13Z20230722T145013Z"
    #         secret-meta-environment:
    #           value:
    #             name: "FIRST_SECRET"
    #             type: enviornment
    #             payload:
    #               env: "MY_SECRET_NAME"
    #             date:
    #               created_at: "2023-07-22T14:50:13Z20230722T145013Z"
    #               updated_at: "2023-07-22T14:50:13Z20230722T145013Z"

    ListFunction:
      description: List all functions (paginated)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ListFunction'

    Function:
      description: Get specific function
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Function'

    ListProvider:
      description: List providers
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ListProviderResponse'

    ListLog:
      description: List logs
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ListLogResponse'

    MetricAggregation:
      description: Metric aggregation
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/MetricResourceAggregation'
              - $ref: '#/components/schemas/MetricHttpAggregation'

    # quotas
    QuotasList:
      description: List quotas
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ListQuotas'

    # billing
    BillingAccountsList:
      description: List billing accounts
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ListBillingAccounts'

    BillingAccount:
      description: Get billing account
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BillingAccount'

    PaymentMethodsList:
      description: List payment methods
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ListPaymentMethods'

    PaymentMethod:
      description: Get payment method
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaymentMethod'

    PaymentMethodCreate:
      description: Create payment method
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaymentMethodCreate'

  # request bodies
  requestBodies:
    # hosts
    HostBody:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/HostBody"
      required: true

    HostBodyPatch:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/HostBodyPatch"
      required: true

    # tokens
    AuthTokenBody:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AuthTokenBody"
      required: true

    AuthTokenPatch:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AuthTokenPatch"
      required: true

    # organisations
    OrganisationBody:
      description: Create/Update any field
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/OrganisationBody"

    # projects
    ProjectBody:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ProjectBody"
      description: Create/Update any field
    ProjectBodyPatch:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ProjectBodyPatch"
      description: Update any field

    # secrets
    SecretBody:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SecretBody"
      description: |
        Create/Update any field

        The example generated may only be for one
        of the secret types, look towards the payload section of the schema
        for further fields, values and examples.
      required: true

    SecretBodyPatch:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SecretBodyPatch"
      description: Update any field
      required: true

    # compute functions
    FunctionBody:
      description: Create/Update any field
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FunctionBody'
      required: true

    FunctionBodyPatch:
      description: Update any field
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Function'
      required: true

    # billing
    BillingAccountBody:
      description: Create/Update any field
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/BillingAccountBody"
      required: true

    PaymentMethodBody:
      description: Create/Update any field
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PaymentMethodBody"
      required: true

  # parameters
  parameters:
    pagination_page:
      in: query
      name: page
      schema:
        type: object
        properties:
          before:
            type: integer
            example: 20
            description: Offset
          after:
            type: integer
            example: 20
            description: Offset
          size:
            type: integer
            example: 20
            description: Limit
      style: deepObject
      explode: true
      description: Query parameters for pagination
    # users
    user_id:
      name: user_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
        example: 3069614e-adc8-47cb-a69c-decf9c5f90fc
      description: User ID reference
    # organisations
    organisation_id:
      name: organisation_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
        example: 3069614e-adc8-47cb-a69c-decf9c5f90fc
      description: Organisation ID reference
    # projects
    project_id:
      name: project_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
        example: 3069614e-adc8-47cb-a69c-decf9c5f90fc
      description: Project ID reference
    # secrets
    secret_type:
      in: query
      name: secret_type
      schema:
        $ref: "#/components/schemas/SecretType"
      description: Type of secret to filter on
    secret_name:
      name: secret_name
      in: path
      required: true
      schema:
        type: string
        minLength: 1
        example: MY_SECRET
        pattern: "^[A-Z_]+$"
      description: Unique secret name
    # auth
    token_id:
      name: token_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
        example: 3069614e-adc8-47cb-a69c-decf9c5f90fc
      description: Token ID reference
    # hosts
    hostname:
      name: hostname
      in: path
      required: true
      schema:
        type: string
        example: example-domain.com
      description: Hostname
    # functions
    function_id:
      name: function_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
        example: 3069614e-adc8-47cb-a69c-decf9c5f90fc
      description: Function ID reference
    function_revision_id:
      name: function_revision_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
        example: 1069614e-adc8-47cb-a69c-decf9c5f90fc
      description: Function revision ID reference
    # metrics
    metric_aggregation_type:
      name: metric_aggregation_type
      in: path
      required: true
      schema:
        type: string
        enum: [httprequests, resourcestats]
        example: httprequests
      description: |
        Metric aggregation type, types can be used with either a project or a function filter.

        - httprequests: Aggregated HTTP requests
        - resourcestats: Aggregated resource stats (such as CPU, Memory and Network)

        > Note: aggregations cannot return more than 300 data points
    # quotas
    quota_entity_quota:
      name: quota_entity_quota
      in: path
      required: true
      schema:
        type: string
        description: Specific quota to filter by
        example: projects_secrets
    # billing
    billing_account_id:
      name: billing_account_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
        example: 3069614e-adc8-47cb-a69c-decf9c5f90fc
      description: Billing account ID reference
    billing_payment_method_id:
      name: billing_payment_method_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
        example: 3069614e-adc8-47cb-a69c-decf9c5f90fc
      description: Payment method ID reference
    # generic in query filters
    filter_name:
      in: query
      name: f_name
      schema:
        type: string
        example: my-proj*
      description: |
        Filter resource on name, if the value ends in an asterix it will be
        treated as a partial search otherwise, it'll be an exact match
    filter_project:
      in: query
      name: f_project
      description: Project uuid reference
      schema:
        type: string
        format: uuid
        example: 3069614e-adc8-47cb-a69c-decf9c5f90fc
    filter_function:
      in: query
      name: f_function
      description: Function uuid reference
      schema:
        type: string
        format: uuid
        example: 3069614e-adc8-47cb-a69c-decf9c5f90fc
    filter_timestamps:
      in: query
      name: f_timestamps
      schema:
        type: object
        properties:
          after: # qw: start_timestamp
            type: string
            example: 2022-05-06T18:05:57.723262Z
            description: Restrict to after this timestamp
          before: # qw: end_timestamp
            type: string
            example: 2023-05-06T18:05:57.723262Z
            description: Resitrct to before this timestamp
      style: deepObject
      explode: true
      description: Timestamp restriction for query
    filter_query:
      in: query
      name: f_query
      description: Text query string
      schema:
        type: string
        example: bootstrap
    filter_log_type:
      in: query
      name: f_log_type
      description: Type of log
      schema: #resolve:true
        $ref: "#/components/schemas/Log/properties/log/properties/type"
    filter_histogram_interval:
      in: query
      name: f_histogram_interval
      description: Histogram interval
      schema:
        description: Interval in seconds
        type: integer
        example: 600

  securitySchemes:
    token:
      type: http
      scheme: bearer
    cookie:
      type: apiKey
      in: cookie
      name: qernal_kratos_session

# tags
tags:
  - name: users
    description: User operations
  - name: billing
    description: Billing operations for accounts and payment methods
  - name: quotas
    description: Quota limits and usage
  - name: projects
    description: Project operations, projects belong to an organisation
  - name: organisations
    description: Organisations are a hierarchy top-level for a user, they allow for organising of projects
  - name: secrets
    description: Secret operations for certificates, environment and container registry
  - name: tokens
    description: Auth tokens for third party clients
  - name: functions
    description: Function operations, allows deployment of containers via the function endpoints
  - name: providers
    description: List of providers you can use to deploy functions into and their available locations - this includes any private providers attached to your organisation
  - name: hosts
    description: Hosts attached to the project so make functions routeable via the internet
  - name: logs
    description: Logs for functions
  - name: metrics
    description: Metrics and aggregations for functions and projects