swagger: '2.0'
info:
  description: OpenFaaS API documentation
  version: 0.8.12
  title: OpenFaaS API Gateway
  license:
    name: MIT
basePath: /
schemes:
- http
paths:
  '/system/functions':
    get:
      summary: 'Get a list of deployed functions with: stats and image digest'
      consumes:
      - application/json
      produces:
      - application/json
      responses:
        '200':
          description: List of deployed functions.
          schema:
            type: array
            items:
              $ref: '#/definitions/FunctionListEntry'
    post:
      summary: Deploy a new function.
      description: ''
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - in: body
        name: body
        description: Function to deploy
        required: true
        schema:
          $ref: '#/definitions/FunctionDefintion'
      responses:
        '202':
          description: Accepted
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
    put:
      summary: Update a function.
      description: ''
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - in: body
        name: body
        description: Function to update
        required: true
        schema:
          $ref: '#/definitions/FunctionDefintion'
      responses:
        '200':
          description: Accepted
        '400':
          description: Bad Request
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
    delete:
      summary: Remove a deployed function.
      description: ''
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - in: body
        name: body
        description: Function to delete
        required: true
        schema:
          $ref: '#/definitions/DeleteFunctionRequest'
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
  '/system/alert':
    post:
      summary: 'Event-sink for AlertManager, for auto-scaling'
      description: 'Internal use for AlertManager, requires valid AlertManager alert JSON'
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - in: body
        name: body
        description: Incoming alert
        schema:
          type: object
          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
            }
      responses:
        '200':
          description: Alert handled successfully
        '500':
          description: Internal error with swarm or request JSON invalid
  '/async-function/{functionName}':
    post:
      summary: 'Invoke a function asynchronously in OpenFaaS'
      description: >-
        See https://docs.openfaas.com/reference/async/.
      parameters:
      - in: path
        name: functionName
        description: Function name
        type: string
        required: true
      - in: body
        name: input
        description: (Optional) data to pass to function
        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
  '/function/{functionName}':
    post:
      summary: Invoke a function defined in OpenFaaS
      parameters:
      - in: path
        name: functionName
        description: Function name
        type: string
        required: true
      - in: body
        name: input
        description: (Optional) data to pass to function
        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
  '/system/scale-function/{functionName}':
    post:
      summary: Scale a function
      parameters:
      - in: path
        name: functionName
        description: Function name
        type: string
        required: true
      - in: body
        name: input
        description: Function to scale plus replica count
        schema:
          type: string
          format: binary
          example:
            '{"service": "hello-world", "replicas": 10}'
        required: false
      responses:
        '200':
          description: Scaling OK
        '202':
          description: Scaling OK
        '404':
          description: Function not found
        '500':
          description: Error scaling function
  '/system/function/{functionName}':
    get:
      summary: Get a summary of an OpenFaaS function
      parameters:
      - in: path
        name: functionName
        description: Function name
        type: string
        required: true
      responses:
        '200':
          description: Function Summary
          schema:
            $ref: '#/definitions/FunctionListEntry'
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
  '/system/secrets':
    get:
      summary: 'Get a list of secret names and metadata from the provider'
      consumes:
      - application/json
      produces:
      - application/json
      responses:
        '200':
          description: List of submitted secrets.
          schema:
            $ref: '#/definitions/SecretName'
    post:
      summary: Create a new secret.
      description: ''
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - in: body
        name: body
        description: A new secret to create
        required: true
        schema:
          $ref: '#/definitions/Secret'
      responses:
        '201':
          description: Created
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
    put:
      summary: Update a secret.
      description: ''
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - in: body
        name: body
        description: Secret to update
        required: true
        schema:
          $ref: '#/definitions/Secret'
      responses:
        '200':
          description: Ok
        '400':
          description: Bad Request
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
    delete:
      summary: Remove a secret.
      description: ''
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - in: body
        name: body
        description: Secret to delete
        required: true
        schema:
          $ref: '#/definitions/SecretName'
      responses:
        '204':
          description: OK
        '400':
          description: Bad Request
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
  '/system/logs':
      get:
        summary: Get a stream of the logs for a specific function
        produces:
          - application/x-ndjson
      parameters:
      - in: query
        name: name
        description: Function name
        type: string
        required: true
      - in: query
        name: since
        description: Only return logs after a specific date (RFC3339)
        type: string
        required: false
      - in: query
        name: tail
        description: Sets the maximum number of log messages to return, <=0 means unlimited
        type: integer
        required: false
      - in: query
        name: follow
        description: When true, the request will stream logs until the request timeout
        type: boolean
        required: false
      responses:
        '200':
          description: Newline delimited stream of log messages
          schema:
            $ref: '#/definitions/LogEntry'
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
  '/system/info':
    get:
      summary: Get info such as provider version number and provider orchestrator
      produces:
      - application/json
      responses:
        '200':
          description: Info result
          schema:
            $ref: '#/definitions/Info'
        '404':
          description: Provider does not support info endpoint
        '500':
          description: Internal Server Error
  '/healthz':
    get:
      summary: Healthcheck
      responses:
        '200':
          description: Healthy
        '500':
          description: Not healthy
securityDefinitions:
  basicAuth:
    type: basic
definitions:
  Info:
    type: object
    properties:
      provider:
        type: object
        description: The OpenFaaS Provider
        properties:
          provider:
            type: string
            example: faas-swarm
          orchestration:
            type: string
            example: swarm
          version:
            type: object
            description: Version of the OpenFaaS Provider
            properties:
              commit_message:
                type: string
                example: Sample Message
              sha:
                type: string
                example: 7108418d9dd6b329ddff40e7393b3166f8160a88
              release:
                type: string
                format: semver
                example: 0.2.6
      version:
        type: object
        description: Version of the Gateway
        properties:
          commit_message:
            type: string
            example: Sample Message
          sha:
            type: string
            example: 7108418d9dd6b329ddff40e7393b3166f8160a88
          release:
            type: string
            format: semver
            example: 0.8.9
    required:
    - provider
    - version
  DeleteFunctionRequest:
    type: object
    properties:
      functionName:
        type: string
        description: Name of deployed function
        example: nodeinfo
    required:
    - functionName
  FunctionDefintion:
    type: object
    properties:
      service:
        type: string
        description: Name of deployed function
        example: nodeinfo
      network:
        type: string
        description: Docker swarm network, usually func_functions
        example: func_functions
      image:
        type: string
        description: Docker image in accessible registry
        example: functions/nodeinfo:latest
      envProcess:
        type: string
        description: Process for watchdog to fork
        example: node main.js
      envVars:
        type: object
        additionalProperties:
          type: string
        description: Overrides to environmental variables
      constraints:
        type: array
        items:
          type: string
          description: Constraints are specific to OpenFaaS Provider
          example: "node.platform.os == linux"
      labels:
        description: A map of labels for making scheduling or routing decisions
        type: object
        additionalProperties:
          type: string
        example:
          foo: bar
      annotations:
        description: A map of annotations for management, orchestration, events and build tasks
        type: object
        additionalProperties:
          type: string
        example:
          topics: awesome-kafka-topic
          foo: bar
      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"
      registryAuth:
        type: string
        description: >-
          Private registry base64-encoded basic auth (as present in
          ~/.docker/config.json)
        example: dXNlcjpwYXNzd29yZA==
      limits:
        type: object
        properties:
          memory:
            type: string
            example: "128M"
          cpu:
            type: string
            example: "0.01"
      requests:
        type: object
        properties:
          memory:
            type: string
            example: "128M"
          cpu:
            type: string
            example: "0.01"
      readOnlyRootFilesystem:
        type: boolean
        description: Make the root filesystem of the function read-only
    required:
    - service
    - image
    - envProcess
  FunctionListEntry:
    type: object
    properties:
      name:
        description: The name of the function
        type: string
        example: nodeinfo
      image:
        description: The fully qualified docker image name of the function
        type: string
        example: functions/nodeinfo:latest
      invocationCount:
        description: The amount of invocations for the specified function
        type: number
        format: integer
        example: 1337
      replicas:
        description: The current minimal ammount of replicas
        type: number
        format: integer
        example: 2
      availableReplicas:
        description: The current available amount of replicas
        type: number
        format: integer
        example: 2
      envProcess:
        description: Process for watchdog to fork
        type: string
        example: node main.js
      labels:
        description: A map of labels for making scheduling or routing decisions
        type: object
        additionalProperties:
          type: string
        example:
          foo: bar
      annotations:
        description: A map of annotations for management, orchestration, events and build tasks
        type: object
        additionalProperties:
          type: string
        example:
          topics: awesome-kafka-topic
          foo: bar
    required:
    - name
    - image
    - invocationCount
    - replicas
    - availableReplicas
    - envProcess
    - labels
  Secret:
    type: object
    properties:
      name:
        type: string
        description: Name of secret
        example: aws-key
      value:
        type: string
        description: Value of secret in plain-text
        example: changeme
    required:
    - name
  LogEntry:
    type: object
    property:
      name:
        type: string
        description: the function name
      instance:
        type: string
        description: the name/id of the specific function instance
      timestamp:
        type: string
        format: date-time
        description: the timestamp of when the log message was recorded
      text:
        type: string
        description: raw log message content
  SecretName:
    type: object
    properties:
      name:
        type: string
        description: Name of secret
        example: aws-key
externalDocs:
  description: More documentation available on Github
  url: 'https://github.com/openfaas/faas'