diff --git a/api-docs/spec-v2.openapi.yml b/api-docs/spec-v2.openapi.yml
new file mode 100644
index 000000000..52082a89c
--- /dev/null
+++ b/api-docs/spec-v2.openapi.yml
@@ -0,0 +1,879 @@
+openapi: 3.0.1
+info:
+  title: OpenFaaS API Gateway
+  description: OpenFaaS API V2 proposal
+  license:
+    name: MIT
+  version: 0.8.12
+  contact:
+    name: OpenFaaS Ltd
+    url: https://www.openfaas.com/support/
+servers:
+- url: "http://localhost:8080"
+  description: Local server
+tags:
+  - name: internal
+    description: Internal use only
+  - name: system
+    description: System endpoints for managing functions and related objects
+  - name: function
+    description: Endpoints for invoking functions
+paths:
+  "/healthz":
+    get:
+      summary: Healthcheck
+      operationId: healthcheck
+      description: Healthcheck for the gateway, indicates if the gateway is running and available
+      tags:
+        - internal
+      responses:
+        '200':
+          description: Healthy
+        '500':
+          description: Not healthy
+
+  "/metrics":
+    get:
+      summary: Prometheus metrics
+      operationId: metrics
+      description: Prometheus metrics for the gateway
+      tags:
+        - internal
+      responses:
+        '200':
+          description: Prometheus metrics in text format
+
+  "/v2/system/info":
+    get:
+      operationId: GetSystemInfo
+      description: Get system provider information
+      summary: Get info such as provider version number and provider orchestrator
+      tags:
+        - system
+      responses:
+        '200':
+          description: Info result
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/GatewayInfoResponse"
+        '500':
+          description: Internal Server Error
+
+  "/v2/system/alert":
+    post:
+      operationId: ScaleAlert
+      description: Scale a function based on an alert
+      summary: | 
+        Event-sink for AlertManager, for auto-scaling
+        
+        Internal use for AlertManager, requires valid AlertManager alert
+        JSON
+      tags:
+        - internal
+      requestBody:
+        description: Incoming alert
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/PrometheusAlertRequest'
+        required: false
+      responses:
+        '200':
+          description: Alert handled successfully
+        '500':
+          description: Internal error with swarm or request JSON invalid
+
+  "/v2/system/functions":      
+    get:
+      operationId: GetFunctions
+      description: Get a list of deployed functions
+      summary: 'Get a list of deployed functions with: stats and image digest'
+      tags:
+        - system
+      parameters:
+        - name: namespace
+          in: query
+          description: Namespace of the function
+          required: false
+          schema:
+            type: string
+      responses:
+        '200':
+          description: List of deployed functions.
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/FunctionListResponse"
+
+  "/v2/system/functions/{functionName}":
+    parameters:
+      - name: functionName
+        in: path
+        description: Function name with optional namespace e.g. "function" or "function.namespace"
+        required: true
+        schema:
+          $ref: "#/components/schemas/NamespacedNameParameter"
+    get:
+      operationId: GetFunctionStatus
+      description: Get the status of a function by name
+      tags:
+        - system
+      responses:
+        '200':
+          description: Function Summary
+          content:
+            "*/*":
+              schema:
+                "$ref": "#/components/schemas/FunctionStatusResponse"
+        '404':
+          description: Not Found
+        '500':
+          description: Internal Server Error
+    
+    put:
+      operationId: UpdateFunction
+      description: Update a function deployment
+      summary: |
+        Use this endpoint to update the deployment spec of a function, for
+        example, update the version, change env variables, or secrets.
+
+        To manage the replica count, use the scale endpoint.
+      tags:
+        - system
+      requestBody:
+        description: Function to update
+        content:
+          application/json:
+            schema:
+              "$ref": "#/components/schemas/FunctionDeploymentRequest"
+        required: true
+      responses:
+        '200':
+          description: Accepted
+        '400':
+          description: Bad Request
+        '404':
+          description: Not Found
+        '500':
+          description: Internal Server Error
+
+    delete:
+      operationId: DeleteFunction
+      description: Remove a deployed function.
+      summary: Remove a deployed function.
+      tags:
+        - system
+      responses:
+        '200':
+          description: OK
+        '400':
+          description: Bad Request
+        '404':
+          description: Not Found
+        '500':
+          description: Internal Server Error
+
+  "/v2/system/functions/{functionName}/scale":
+    parameters:
+      - name: functionName
+        in: path
+        description: Function name
+        required: true
+        schema:
+          $ref: "#/components/schemas/NamespacedNameParameter"
+    post:
+      operationId: ScaleFunction
+      description: Scale a function
+      summary: Scale a function to a specific replica count
+      tags:
+        - system
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ScaleFunctionRequest'
+      responses:
+        '200':
+          description: Scaling OK
+        '202':
+          description: Scaling OK
+        '404':
+          description: Function not found
+        '500':
+          description: Error scaling function
+
+  "/v2/system/functions/{functionName}/logs":
+    get:
+      operationId: GetFunctionLogs
+      description: Get a stream of the logs for a specific function
+      summary: Get a stream of the logs for a specific function.
+
+        The response is an chunked HTTP response, where each chunk is one or more log lines
+        in new-line delimited JSON format. The response is terminated by a zero-length chunk.
+      tags:
+        - system
+      parameters:
+      - name: functionName
+        in: path
+        description: Function name
+        required: true
+        schema:
+          $ref: "#/components/schemas/NamespacedNameParameter"
+      - name: instance
+        in: query
+        description: Instance of the function
+        required: false
+        schema:
+          type: string
+      - name: tail
+        in: query
+        description: Sets the maximum number of log messages to return, <=0 means
+          unlimited
+        schema:
+          type: integer
+      - name: follow
+        in: query
+        description: When true, the request will stream logs until the request timeout
+        schema:
+          type: boolean
+      - name: since
+        in: query
+        description: Only return logs after a specific date (RFC3339)
+        schema:
+          type: string
+          format: date-time
+      responses:
+        '200':
+          description: Newline delimited stream of log messages
+          content:
+            application/x-ndjson:
+              schema:
+                "$ref": "#/components/schemas/LogEntry"
+        '404':
+          description: Not Found
+        '500':
+          description: Internal Server Error
+
+  "/v2/system/secrets":
+    get:
+      operationId: ListSecrets
+      description: Get a list of secret names and metadata from the provider
+      summary: Get a list of secret names and metadata from the provider
+      tags:
+        - system
+      parameters:
+        - name: namespace
+          in: query
+          description: Namespace of the secret
+          required: false
+          schema:
+            type: string
+      responses:
+        '200':
+          description: List of submitted secrets.
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/SecretListResponse"
+
+  "/v2/system/secrets/{secretName}":
+    parameters:
+      - name: secretName
+        in: path
+        description: Secret name
+        required: true
+        schema:
+          $ref: "#/components/schemas/NamespacedNameParameter"
+    put:
+      operationId: SetSecret
+      description: Create or replace a secret.
+      tags:
+        - system
+      requestBody:
+        description: Secret to update
+        content:
+          application/json:
+            schema:
+              "$ref": "#/components/schemas/SecretRequest"
+        required: true
+      responses:
+        '200':
+          description: Ok
+        '400':
+          description: Bad Request
+        '404':
+          description: Not Found
+        '405':
+          description: Method Not Allowed. Secret update is not allowed in faas-swarm.
+        '500':
+          description: Internal Server Error
+    delete:
+      operationId: DeleteSecret
+      description: Remove a secret.
+      tags:
+        - system
+      responses:
+        '204':
+          description: OK
+        '400':
+          description: Bad Request
+        '404':
+          description: Not Found
+        '500':
+          description: Internal Server Error
+  
+  "/v2/system/namespaces":
+    get:
+      operationId: ListNamespaces
+      description: Get a list of namespaces
+      tags:
+        - system
+      responses:
+        '200':
+          description: List of namespaces
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ListNamespaceResponse'
+        '500':
+          description: Internal Server Error
+  
+  "/v2/async-invoke/{functionName}":
+    post:
+      operationId: InvokeAsync
+      description: Invoke a function asynchronously
+      summary: |
+        Invoke a function asynchronously in the default OpenFaaS namespace
+
+        Any additional path segments and query parameters will be passed to the function as is.
+
+        See https://docs.openfaas.com/reference/async/.
+      tags:
+        - function
+      parameters:
+      - name: functionName
+        in: path
+        description: Function name
+        required: true
+        schema:
+          $ref: "#/components/schemas/NamespacedNameParameter"
+      requestBody:
+        description: "(Optional) data to pass to function"
+        content:
+          "*/*":
+            schema:
+              type: string
+              format: binary
+              example: '{"hello": "world"}'
+        required: false
+      responses:
+        '202':
+          description: Request accepted and queued
+        '404':
+          description: Not Found
+        '500':
+          description: Internal Server Error
+
+  "/v2/invoke/{functionName}":
+    post:
+      operationId: InvokeFunction
+      description: Invoke a function in the default OpenFaaS namespace.
+      summary: |
+        Synchronously invoke a function defined in te default OpenFaaS namespace.
+
+        Any additional path segments and query parameters will be passed to the function as is.
+      tags:
+        - function
+      parameters:
+      - name: functionName
+        in: path
+        description: Function name
+        required: true
+        schema:
+          $ref: "#/components/schemas/NamespacedNameParameter"
+      requestBody:
+        description: "(Optional) data to pass to function"
+        content:
+          "*/*":
+            schema:
+              type: string
+              format: binary
+              example: '{"hello": "world"}'
+        required: false
+      responses:
+        '200':
+          description: Value returned from function
+        '404':
+          description: Not Found
+        '500':
+          description: Internal server error
+
+components:
+  securitySchemes:
+    basicAuth:
+      type: http
+      scheme: basic
+
+  schemas:
+
+    NamespacedNameParameter:
+      type: string
+      pattern: '^(?<name>[a-zA-Z][a-zA-Z0-9-_]*)(.(?<namespace>[a-zA-Z][a-zA-Z0-9-_]*)?)$'
+
+    GatewayInfoResponse:
+      required:
+      - provider
+      - version
+      - arch
+      type: object
+      properties:
+        provider:
+          nullable: true
+          allOf:
+            - $ref: "#/components/schemas/ProviderInfo"
+        version:
+          nullable: true
+          description: version of the gateway
+          allOf:
+            - $ref: "#/components/schemas/VersionInfo"
+        arch:
+          type: string
+          description: Platform architecture
+          example: x86_64
+
+    VersionInfo:
+      type: object
+      required:
+        - sha
+        - release
+      properties:
+        commit_message:
+          type: string
+          example: Sample Message
+        sha:
+          type: string
+          example: 7108418d9dd6b329ddff40e7393b3166f8160a88
+        release:
+          type: string
+          format: semver
+          example: 0.8.9
+
+    ProviderInfo:
+      type: object
+      required:
+        - provider
+        - orchestration
+        - version
+      properties:
+        provider:
+          type: string
+          description: The orchestration provider / implementation
+          example: faas-netes
+        orchestration:
+          type: string
+          example: kubernetes
+        version:
+          description: The version of the provider
+          nullable: true
+          allOf:
+            - $ref: "#/components/schemas/VersionInfo"
+    
+    PrometheusAlertRequest:
+      type: object
+      description: Prometheus alert produced by AlertManager. This is only a subset of the full alert payload.
+      required:
+        - status
+        - receiver
+        - alerts
+      properties:
+        status:
+          type: string
+          description: The status of the alert
+          example: resolved
+        receiver:
+          type: string
+          description: The name of the receiver
+          example: webhook
+        alerts:
+          type: array
+          description: The list of alerts
+          items:
+            $ref: "#/components/schemas/PrometheusInnerAlert"
+      example:
+        {
+          "receiver": "scale-up",
+          "status": "firing",
+          "alerts": [{
+              "status": "firing",
+              "labels": {
+                  "alertname": "APIHighInvocationRate",
+                  "code": "200",
+                  "function_name": "func_nodeinfo",
+                  "instance": "gateway:8080",
+                  "job": "gateway",
+                  "monitor": "faas-monitor",
+                  "service": "gateway",
+                  "severity": "major",
+                  "value": "8.998200359928017"
+              },
+              "annotations": {
+                  "description": "High invocation total on gateway:8080",
+                  "summary": "High invocation total on gateway:8080"
+              },
+              "startsAt": "2017-03-15T15:52:57.805Z",
+              "endsAt": "0001-01-01T00:00:00Z",
+              "generatorURL": "http://4156cb797423:9090/graph?g0.expr=rate%28gateway_function_invocation_total%5B10s%5D%29+%3E+5\u0026g0.tab=0"
+          }],
+          "groupLabels": {
+              "alertname": "APIHighInvocationRate",
+              "service": "gateway"
+          },
+          "commonLabels": {
+              "alertname": "APIHighInvocationRate",
+              "code": "200",
+              "function_name": "func_nodeinfo",
+              "instance": "gateway:8080",
+              "job": "gateway",
+              "monitor": "faas-monitor",
+              "service": "gateway",
+              "severity": "major",
+              "value": "8.998200359928017"
+          },
+          "commonAnnotations": {
+              "description": "High invocation total on gateway:8080",
+              "summary": "High invocation total on gateway:8080"
+          },
+          "externalURL": "http://f054879d97db:9093",
+          "version": "3",
+          "groupKey": 18195285354214864953
+        }
+      
+    PrometheusInnerAlert:
+      type: object
+      description: A single alert produced by Prometheus
+      required:
+        - status
+        - labels
+      properties:
+        status:
+          type: string
+          description: The status of the alert
+          example: resolved
+        labels:
+          $ref: "#/components/schemas/PrometheusInnerAlertLabel"
+
+    PrometheusInnerAlertLabel:
+      type: object
+      description: A single label of a Prometheus alert
+      required:
+        - alertname
+        - function_name
+      properties:
+        alertname:
+          type: string
+          description: The name of the alert
+        function_name:
+          type: string
+          description: The name of the function
+          example: nodeinfo
+
+    FunctionDeploymentRequest:
+      required:
+      - name
+      - image
+      type: object
+      properties:
+        name:
+          type: string
+          description: Name of deployed function or service
+          example: nodeinfo
+          pattern: "^[a-zA-Z][a-zA-Z0-9-_]+$"
+        image:
+          type: string
+          description: Docker image in accessible registry
+          example: functions/nodeinfo:latest
+        namespace:
+          type: string
+          description: Namespace to deploy function to. When omitted, the default namespace
+            is used, typically this is `openfaas-fn` but is configured by the provider.
+          example: openfaas-fn
+        envProcess:
+          type: string
+          description: |
+            Process for watchdog to fork, i.e. the command to start the function process.
+
+            This value configures the `fprocess` env variable.
+          example: node main.js
+        constraints:
+          type: array
+          items:
+            type: string
+            description: Constraints are specific to OpenFaaS Provider
+            example: node.platform.os == linux
+        envVars:
+          type: object
+          additionalProperties:
+            type: string
+          description: Overrides to environmental variables
+        secrets:
+          type: array
+          items:
+            type: string
+            description: An array of names of secrets that are required to be loaded
+              from the Docker Swarm.
+            example: secret-name-1
+        labels:
+          type: object
+          nullable: true
+          additionalProperties:
+            type: string
+          description: A map of labels for making scheduling or routing decisions
+          example:
+            foo: bar
+        annotations:
+          type: object
+          nullable: true
+          additionalProperties:
+            type: string
+          description: A map of annotations for management, orchestration, events
+            and build tasks
+          example:
+            topics: awesome-kafka-topic
+            foo: bar
+        limits:
+          nullable: true
+          allOf:
+            - $ref: "#/components/schemas/ResourcesSpec"
+        requests:
+          nullable: true
+          allOf:
+            - $ref: "#/components/schemas/ResourcesSpec"
+        readOnlyRootFilesystem:
+          type: boolean
+          description: Make the root filesystem of the function read-only
+
+    FunctionListResponse:
+      type: object
+      required:
+        - functions
+      properties:
+        functions:
+          type: array
+          items:
+            $ref: "#/components/schemas/FunctionStatusResponse"
+
+    FunctionStatusResponse:
+      type: object
+      required:
+        - name
+        - image
+      properties:
+        name:
+          type: string
+          description: The name of the function / service
+          example: nodeinfo
+        image:
+          type: string
+          description: The fully qualified docker image name of the function
+          example: functions/nodeinfo:latest
+        namespace:
+          type: string
+          description: The namespace of the function
+          example: openfaas-fn
+        envProcess:
+          type: string
+          description: Process for watchdog to fork
+          example: node main.js
+        envVars:
+          type: object
+          additionalProperties:
+            type: string
+          description: environment variables for the function runtime
+        constraints:
+          type: array
+          items:
+            type: string
+            description: Constraints are specific to OpenFaaS Provider
+            example: node.platform.os == linux
+        secrets:
+          type: array
+          items:
+            type: string
+            description: An array of names of secrets that are made available to the function
+        labels:
+          type: object
+          nullable: true
+          additionalProperties:
+            type: string
+          description: A map of labels for making scheduling or routing decisions
+          example:
+            foo: bar
+        annotations:
+          type: object
+          nullable: true
+          additionalProperties:
+            type: string
+          description: A map of annotations for management, orchestration, events
+            and build tasks
+          example:
+            topics: awesome-kafka-topic
+            foo: bar
+        limits:
+          nullable: true
+          allOf:
+            - $ref: "#/components/schemas/ResourcesSpec"
+        requests:
+          nullable: true
+          allOf:
+            - $ref: "#/components/schemas/ResourcesSpec"
+        readOnlyRootFilesystem:
+          type: boolean
+          description: removes write-access from the root filesystem mount-point.
+        invocationCount:
+          type: number
+          description: The amount of invocations for the specified function
+          format: integer
+          example: 1337
+        replicas:
+          type: number
+          description: The current minimal ammount of replicas
+          format: integer
+          example: 2
+        availableReplicas:
+          type: number
+          description: The current available amount of replicas
+          format: integer
+          example: 2
+        createdAt:
+          type: string
+          description: | 
+            is the time read back from the faas backend's
+            data store for when the function or its container was created.
+          format: date-time
+        usage:
+          nullable: true
+          allOf:  
+            - $ref: "#/components/schemas/UsageInfo"
+
+    ResourcesSpec:
+      type: object
+      properties:
+        memory:
+          type: string
+          description: The amount of memory that is allocated for the function
+          example: 128M
+        cpu:
+          type: string
+          description: The amount of cpu that is allocated for the function
+          example: '0.01'
+
+    UsageInfo:
+      type: object
+      properties:
+        cpu:
+          type: number
+          description: | 
+            is the increase in CPU usage since the last measurement
+            equivalent to Kubernetes' concept of millicores.
+          format: double
+          example: 0.01
+        totalMemoryBytes:
+          type: number
+          description: is the total memory usage in bytes.
+          format: double
+          example: 1337
+
+
+    ScaleFunctionRequest:
+      required:
+      - replicas
+      type: object
+      properties:
+        replicas:
+          type: integer
+          format: int64
+          minimum: 0
+          description: Number of replicas to scale to
+          example: 2
+
+
+    SecretListResponse:
+      type: object
+      properties:
+        secrets:
+          type: array
+          items:
+            $ref: "#/components/schemas/SecretDescription"
+
+    SecretDescription:
+      required:
+        - name
+      type: object
+      properties:
+        name:
+          type: string
+          description: Name of secret
+          example: aws-key
+        namespace:
+          type: string
+          description: Namespace of secret
+          example: openfaas-fn
+
+    SecretValues:
+      type: object
+      properties:
+        value:
+          type: string
+          description: Value of secret in plain-text
+          example: changeme
+        rawValue:
+          type: string
+          format: byte
+          description: |
+            Value of secret in base64.
+
+            This can be used to provide raw binary data when the `value` field is omitted.
+          example: Y2hhbmdlbWU=
+
+    SecretRequest:
+      type: object
+      allOf:
+        - $ref: "#/components/schemas/SecretDescription"
+        - $ref: "#/components/schemas/SecretValues"
+      
+    LogEntry:
+      type: object
+      required:
+        - name
+        - namespace
+        - instance
+        - timestamp
+        - text
+      properties:
+        name:
+          type: string
+          description: the function name
+        namespace:
+          type: string
+          description: the namespace of the function
+        instance:
+          type: string
+          description: the name/id of the specific function instance
+        timestamp:
+          type: string
+          description: the timestamp of when the log message was recorded
+          format: date-time
+        text:
+          type: string
+          description: raw log message content
+
+    ListNamespaceResponse:
+      type: object
+      properties:
+        namespaces:
+          type: array
+          items:
+            type: string
+            description: Namespace name
+            example: openfaas-fn