diff --git a/.github/workflows/spec.yml b/.github/workflows/spec.yml
new file mode 100644
index 00000000..0411ccf5
--- /dev/null
+++ b/.github/workflows/spec.yml
@@ -0,0 +1,33 @@
+# name of the action
+name: spec
+
+# trigger on release events
+on:
+  release:
+    types: [ created ]
+
+# pipeline to execute
+jobs:
+  schema:
+    runs-on: ubuntu-latest
+    container:
+      image: golang:1.17
+    steps:
+    - name: clone
+      uses: actions/checkout@v2
+
+    - name: tags
+      run: |
+        git fetch --tags
+
+    - name: create spec
+      run: |
+        make spec-install
+        make spec
+
+    - name: upload spec
+      uses: skx/github-action-publish-binaries@master
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      with:
+        args: 'api-spec.json'
diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
index 7ace2e23..273c8361 100644
--- a/.github/workflows/validate.yml
+++ b/.github/workflows/validate.yml
@@ -26,3 +26,8 @@ jobs:
         go fmt ./... && git diff --exit-code; code=$?; git checkout -- .; (exit $code)
         # Check that go fix ./... produces a zero diff; clean up any changes afterwards.
         go fix ./... && git diff --exit-code; code=$?; git checkout -- .; (exit $code)
+
+    - name: validate spec
+      run: |
+        make spec-install
+        make spec
diff --git a/.gitignore b/.gitignore
index f2e68bdc..68b918a3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -42,3 +42,5 @@ secrets.env
 
 # Files to be excluded.
 .DS_Store
+
+api-spec.json
diff --git a/Makefile b/Makefile
index 290035ef..09fa099f 100644
--- a/Makefile
+++ b/Makefile
@@ -5,6 +5,9 @@
 # capture the current date we build the application from
 BUILD_DATE = $(shell date +%Y-%m-%dT%H:%M:%SZ)
 
+# set the filename for the api spec
+SPEC_FILE = api-spec.json
+
 # check if a git commit sha is already set
 ifndef GITHUB_SHA
 	# capture the current git commit sha we build the application from
@@ -243,3 +246,68 @@ compose-down:
 	@echo
 	@echo "### Destroying containers for docker-compose stack"
 	@docker-compose -f docker-compose.yml down
+
+# The `spec-install` target is intended to install the
+# the needed dependencies to generate the api spec.
+# 
+# Tools used:
+# - go-swagger (https://goswagger.io/install.html)
+# - jq (https://stedolan.github.io/jq/download/)
+# - sponge (part of moreutils - https://packages.debian.org/sid/moreutils)
+#
+# Limit use of this make target to CI.
+# Debian-based environment is assumed.
+#
+# Usage: `make spec-install`
+.PHONY: spec-install
+spec-install:
+	$(if $(shell command -v apt-get 2> /dev/null),,$(error 'apt-get' not found - install jq, sponge, and go-swagger manually))
+	@echo
+	@echo "### Installing utilities (jq and sponge)"
+	@apt-get update
+	@apt-get install -y jq moreutils
+	@echo "### Downloading and installing go-swagger"
+	@curl -o /usr/local/bin/swagger -L "https://github.com/go-swagger/go-swagger/releases/download/v0.27.0/swagger_linux_amd64"
+	@chmod +x /usr/local/bin/swagger
+
+# The `spec-gen` target is intended to create an api-spec
+# using go-swagger (https://goswagger.io)
+#
+# Usage: `make spec-gen`
+.PHONY: spec-gen
+spec-gen:
+	@echo
+	@echo "### Generating api spec using go-swagger"
+	@swagger generate spec -m --exclude github.com/docker/docker/api/types --exclude-tag definitions/Step -o ${SPEC_FILE}
+	@echo "### ${SPEC_FILE} created successfully"
+
+# The `spec-validate` target is intended to validate
+# an api-spec using go-swagger (https://goswagger.io)
+#
+# Usage: `make spec-validate`
+.PHONY: spec-validate
+spec-validate:
+	@echo
+	@echo "### Validating api spec using go-swagger"
+	@swagger validate ${SPEC_FILE}
+
+# The `spec-version-update` target is intended to update
+# the api-spec version in the generated api-spec
+# using the latest git tag.
+#
+# Usage: `make spec-version-update`
+.PHONY: spec-version-update
+spec-version-update: APPS = jq sponge
+spec-version-update:
+	$(foreach app,$(APPS),\
+		$(if $(shell command -v $(app) 2> /dev/null),,$(error skipping update of spec version - '$(app)' not found)))
+	@echo
+	@echo "### Updating api-spec version"
+	@jq '.info.version = "$(subst v,,${GITHUB_TAG})"' ${SPEC_FILE} | sponge ${SPEC_FILE}
+
+# The `spec` target will call spec-gen, spec-version-update
+# and spec-validate to create and validate an api-spec.
+#
+# Usage: `make spec`
+.PHONY: spec
+spec: spec-gen spec-version-update spec-validate
diff --git a/api-spec/vela-worker-v0.5.0.json b/api-spec/vela-worker-v0.5.0.json
deleted file mode 100644
index f1ca5d3a..00000000
--- a/api-spec/vela-worker-v0.5.0.json
+++ /dev/null
@@ -1,930 +0,0 @@
-{
-  "consumes": [
-    "application/json"
-  ],
-  "produces": [
-    "application/json"
-  ],
-  "schemes": [
-    "http",
-    "https"
-  ],
-  "swagger": "2.0",
-  "info": {
-    "description": "API for a Vela worker",
-    "title": "Vela worker",
-    "version": "0.4.3"
-  },
-  "paths": {
-    "/api/v1/executors": {
-      "get": {
-        "description": "Get all currently running executors",
-        "produces": [
-          "application/json"
-        ],
-        "tags": [
-          "executor"
-        ],
-        "operationId": "GetExecutors",
-        "parameters": [
-          {
-            "type": "string",
-            "description": "Vela server token",
-            "name": "Authorization",
-            "in": "header",
-            "required": true
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Successfully retrieved all running executors",
-            "schema": {
-              "$ref": "#/definitions/Executor"
-            }
-          },
-          "500": {
-            "description": "Unable to retrieve all running executors"
-          }
-        },
-        "x-success_http_code": "200"
-      }
-    },
-    "/api/v1/executors/{executor}": {
-      "get": {
-        "description": "Get a currently running executor",
-        "produces": [
-          "application/json"
-        ],
-        "tags": [
-          "executor"
-        ],
-        "operationId": "GetExecutor",
-        "parameters": [
-          {
-            "type": "string",
-            "description": "Vela server token",
-            "name": "Authorization",
-            "in": "header",
-            "required": true
-          },
-          {
-            "type": "string",
-            "description": "The executor to retrieve",
-            "name": "executor",
-            "in": "path",
-            "required": true
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Successfully retrieved the executor",
-            "schema": {
-              "$ref": "#/definitions/Executor"
-            }
-          },
-          "500": {
-            "description": "Unable to retrieve the executor"
-          }
-        },
-        "x-success_http_code": "200"
-      }
-    },
-    "/api/v1/executors/{executor}/build": {
-      "get": {
-        "description": "Get the currently running build",
-        "produces": [
-          "application/json"
-        ],
-        "tags": [
-          "build"
-        ],
-        "operationId": "GetBuild",
-        "parameters": [
-          {
-            "type": "string",
-            "description": "Vela server token",
-            "name": "Authorization",
-            "in": "header",
-            "required": true
-          },
-          {
-            "type": "string",
-            "description": "The executor running the build",
-            "name": "executor",
-            "in": "path",
-            "required": true
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Successfully retrieved the build",
-            "schema": {
-              "$ref": "#/definitions/Build"
-            }
-          },
-          "500": {
-            "description": "Unable to retrieve the build",
-            "schema": {
-              "type": "string"
-            }
-          }
-        },
-        "x-success_http_code": "200"
-      }
-    },
-    "/api/v1/executors/{executor}/build/cancel": {
-      "delete": {
-        "description": "Cancel the currently running build",
-        "produces": [
-          "application/json"
-        ],
-        "tags": [
-          "build"
-        ],
-        "operationId": "CancelBuild",
-        "parameters": [
-          {
-            "type": "string",
-            "description": "Vela server token",
-            "name": "Authorization",
-            "in": "header",
-            "required": true
-          },
-          {
-            "type": "string",
-            "description": "The executor running the build",
-            "name": "executor",
-            "in": "path",
-            "required": true
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Successfully cancelled the build"
-          },
-          "500": {
-            "description": "Unable to cancel the build"
-          }
-        },
-        "x-success_http_code": "200"
-      }
-    },
-    "/api/v1/executors/{executor}/pipeline": {
-      "get": {
-        "description": "Get a currently running pipeline",
-        "produces": [
-          "application/json"
-        ],
-        "tags": [
-          "pipeline"
-        ],
-        "operationId": "GetPipeline",
-        "parameters": [
-          {
-            "type": "string",
-            "description": "Vela server token",
-            "name": "Authorization",
-            "in": "header",
-            "required": true
-          },
-          {
-            "type": "string",
-            "description": "The executor running the pipeline",
-            "name": "executor",
-            "in": "path",
-            "required": true
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Successfully retrieved the pipeline",
-            "schema": {
-              "$ref": "#/definitions/PipelineBuild"
-            }
-          },
-          "500": {
-            "description": "Unable to retrieve the pipeline"
-          }
-        },
-        "x-success_http_code": "200"
-      }
-    },
-    "/api/v1/executors/{executor}/repo": {
-      "get": {
-        "description": "Get a currently running repo",
-        "produces": [
-          "application/json"
-        ],
-        "tags": [
-          "repo"
-        ],
-        "operationId": "GetRepo",
-        "parameters": [
-          {
-            "type": "string",
-            "description": "Vela server token",
-            "name": "Authorization",
-            "in": "header",
-            "required": true
-          },
-          {
-            "type": "string",
-            "description": "The executor running the build",
-            "name": "executor",
-            "in": "path",
-            "required": true
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Successfully retrieved the repo",
-            "schema": {
-              "$ref": "#/definitions/Repo"
-            }
-          },
-          "500": {
-            "description": "Unable to retrieve the repo"
-          }
-        },
-        "x-success_http_code": "200"
-      }
-    },
-    "/api/v1/shutdown": {
-      "post": {
-        "description": "Perform a soft shutdown of the worker",
-        "produces": [
-          "application/json"
-        ],
-        "tags": [
-          "system"
-        ],
-        "operationId": "Shutdown",
-        "parameters": [
-          {
-            "type": "string",
-            "description": "Vela server token",
-            "name": "Authorization",
-            "in": "header",
-            "required": true
-          }
-        ],
-        "responses": {
-          "501": {
-            "description": "Endpoint is not yet implemented",
-            "schema": {
-              "type": "string"
-            }
-          }
-        },
-        "x-success_http_code": "501"
-      }
-    },
-    "/health": {
-      "get": {
-        "description": "Check if the worker API is available",
-        "produces": [
-          "application/json"
-        ],
-        "tags": [
-          "system"
-        ],
-        "operationId": "Health",
-        "responses": {
-          "200": {
-            "description": "Successful 'ping' of Vela worker API",
-            "schema": {
-              "type": "string"
-            }
-          }
-        },
-        "x-success_http_code": "200"
-      }
-    },
-    "/metrics": {
-      "get": {
-        "description": "Retrieve metrics from the worker",
-        "produces": [
-          "application/json"
-        ],
-        "tags": [
-          "system"
-        ],
-        "operationId": "Metrics",
-        "responses": {
-          "200": {
-            "description": "Successful retrieval of worker metrics",
-            "schema": {
-              "type": "string"
-            }
-          }
-        },
-        "x-success_http_code": "200"
-      }
-    }
-  },
-  "definitions": {
-    "Build": {
-      "type": "object",
-      "title": "Build is the library representation of a build for a pipeline.",
-      "properties": {
-        "author": {
-          "type": "string",
-          "x-go-name": "Author"
-        },
-        "base_ref": {
-          "type": "string",
-          "x-go-name": "BaseRef"
-        },
-        "branch": {
-          "type": "string",
-          "x-go-name": "Branch"
-        },
-        "clone": {
-          "type": "string",
-          "x-go-name": "Clone"
-        },
-        "commit": {
-          "type": "string",
-          "x-go-name": "Commit"
-        },
-        "created": {
-          "type": "integer",
-          "format": "int64",
-          "x-go-name": "Created"
-        },
-        "deploy": {
-          "type": "string",
-          "x-go-name": "Deploy"
-        },
-        "distribution": {
-          "type": "string",
-          "x-go-name": "Distribution"
-        },
-        "email": {
-          "type": "string",
-          "x-go-name": "Email"
-        },
-        "enqueued": {
-          "type": "integer",
-          "format": "int64",
-          "x-go-name": "Enqueued"
-        },
-        "error": {
-          "type": "string",
-          "x-go-name": "Error"
-        },
-        "event": {
-          "type": "string",
-          "x-go-name": "Event"
-        },
-        "finished": {
-          "type": "integer",
-          "format": "int64",
-          "x-go-name": "Finished"
-        },
-        "host": {
-          "type": "string",
-          "x-go-name": "Host"
-        },
-        "id": {
-          "type": "integer",
-          "format": "int64",
-          "x-go-name": "ID"
-        },
-        "link": {
-          "type": "string",
-          "x-go-name": "Link"
-        },
-        "message": {
-          "type": "string",
-          "x-go-name": "Message"
-        },
-        "number": {
-          "type": "integer",
-          "format": "int64",
-          "x-go-name": "Number"
-        },
-        "parent": {
-          "type": "integer",
-          "format": "int64",
-          "x-go-name": "Parent"
-        },
-        "ref": {
-          "type": "string",
-          "x-go-name": "Ref"
-        },
-        "repo_id": {
-          "type": "integer",
-          "format": "int64",
-          "x-go-name": "RepoID"
-        },
-        "runtime": {
-          "type": "string",
-          "x-go-name": "Runtime"
-        },
-        "sender": {
-          "type": "string",
-          "x-go-name": "Sender"
-        },
-        "source": {
-          "type": "string",
-          "x-go-name": "Source"
-        },
-        "started": {
-          "type": "integer",
-          "format": "int64",
-          "x-go-name": "Started"
-        },
-        "status": {
-          "type": "string",
-          "x-go-name": "Status"
-        },
-        "title": {
-          "type": "string",
-          "x-go-name": "Title"
-        }
-      },
-      "x-go-package": "github.com/go-vela/types/library"
-    },
-    "Container": {
-      "type": "object",
-      "properties": {
-        "commands": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "x-go-name": "Commands"
-        },
-        "detach": {
-          "type": "boolean",
-          "x-go-name": "Detach"
-        },
-        "directory": {
-          "type": "string",
-          "x-go-name": "Directory"
-        },
-        "entrypoint": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "x-go-name": "Entrypoint"
-        },
-        "environment": {
-          "type": "object",
-          "additionalProperties": {
-            "type": "string"
-          },
-          "x-go-name": "Environment"
-        },
-        "exit_code": {
-          "type": "integer",
-          "format": "int64",
-          "x-go-name": "ExitCode"
-        },
-        "id": {
-          "type": "string",
-          "x-go-name": "ID"
-        },
-        "image": {
-          "type": "string",
-          "x-go-name": "Image"
-        },
-        "name": {
-          "type": "string",
-          "x-go-name": "Name"
-        },
-        "needs": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "x-go-name": "Needs"
-        },
-        "networks": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "x-go-name": "Networks"
-        },
-        "number": {
-          "type": "integer",
-          "format": "int64",
-          "x-go-name": "Number"
-        },
-        "ports": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "x-go-name": "Ports"
-        },
-        "privileged": {
-          "type": "boolean",
-          "x-go-name": "Privileged"
-        },
-        "pull": {
-          "type": "boolean",
-          "x-go-name": "Pull"
-        },
-        "ruleset": {
-          "$ref": "#/definitions/Ruleset"
-        },
-        "secrets": {
-          "$ref": "#/definitions/StepSecretSlice"
-        },
-        "ulimits": {
-          "$ref": "#/definitions/UlimitSlice"
-        },
-        "volumes": {
-          "$ref": "#/definitions/VolumeSlice"
-        }
-      },
-      "x-go-package": "github.com/go-vela/types/pipeline"
-    },
-    "ContainerSlice": {
-      "type": "array",
-      "items": {
-        "$ref": "#/definitions/Container"
-      },
-      "x-go-package": "github.com/go-vela/types/pipeline"
-    },
-    "Executor": {
-      "type": "object",
-      "title": "Executor is the library representation of an executor for a worker.",
-      "properties": {
-        "build": {
-          "$ref": "#/definitions/Build"
-        },
-        "distribution": {
-          "type": "string",
-          "x-go-name": "Distribution"
-        },
-        "host": {
-          "type": "string",
-          "x-go-name": "Host"
-        },
-        "id": {
-          "type": "integer",
-          "format": "int64",
-          "x-go-name": "ID"
-        },
-        "pipeline": {
-          "$ref": "#/definitions/PipelineBuild"
-        },
-        "repo": {
-          "$ref": "#/definitions/Repo"
-        },
-        "runtime": {
-          "type": "string",
-          "x-go-name": "Runtime"
-        }
-      },
-      "x-go-package": "github.com/go-vela/types/library"
-    },
-    "PipelineBuild": {
-      "type": "object",
-      "title": "Build is the pipeline representation of a build for a pipeline.",
-      "properties": {
-        "id": {
-          "type": "string",
-          "x-go-name": "ID"
-        },
-        "metadata": {
-          "$ref": "#/definitions/PipelineMetadata"
-        },
-        "secrets": {
-          "$ref": "#/definitions/SecretSlice"
-        },
-        "services": {
-          "$ref": "#/definitions/ContainerSlice"
-        },
-        "stages": {
-          "$ref": "#/definitions/StageSlice"
-        },
-        "steps": {
-          "$ref": "#/definitions/ContainerSlice"
-        },
-        "version": {
-          "type": "string",
-          "x-go-name": "Version"
-        },
-        "worker": {
-          "$ref": "#/definitions/PipelineWorker"
-        }
-      },
-      "x-go-name": "Build",
-      "x-go-package": "github.com/go-vela/types/pipeline"
-    },
-    "PipelineMetadata": {
-      "type": "object",
-      "title": "Metadata is the yaml representation of the metadata block for a pipeline.",
-      "properties": {
-        "template": {
-          "type": "boolean",
-          "x-go-name": "Template"
-        }
-      },
-      "x-go-name": "Metadata",
-      "x-go-package": "github.com/go-vela/types/pipeline"
-    },
-    "PipelineWorker": {
-      "type": "object",
-      "title": "Worker is the yaml representation of the worker block for a pipeline.",
-      "properties": {
-        "flavor": {
-          "type": "string",
-          "x-go-name": "Flavor"
-        },
-        "platform": {
-          "type": "string",
-          "x-go-name": "Platform"
-        }
-      },
-      "x-go-name": "Worker",
-      "x-go-package": "github.com/go-vela/types/pipeline"
-    },
-    "Repo": {
-      "type": "object",
-      "title": "Repo is the library representation of a repo.",
-      "properties": {
-        "active": {
-          "type": "boolean",
-          "x-go-name": "Active"
-        },
-        "allow_comment": {
-          "type": "boolean",
-          "x-go-name": "AllowComment"
-        },
-        "allow_deploy": {
-          "type": "boolean",
-          "x-go-name": "AllowDeploy"
-        },
-        "allow_pull": {
-          "type": "boolean",
-          "x-go-name": "AllowPull"
-        },
-        "allow_push": {
-          "type": "boolean",
-          "x-go-name": "AllowPush"
-        },
-        "allow_tag": {
-          "type": "boolean",
-          "x-go-name": "AllowTag"
-        },
-        "branch": {
-          "type": "string",
-          "x-go-name": "Branch"
-        },
-        "clone": {
-          "type": "string",
-          "x-go-name": "Clone"
-        },
-        "full_name": {
-          "type": "string",
-          "x-go-name": "FullName"
-        },
-        "id": {
-          "type": "integer",
-          "format": "int64",
-          "x-go-name": "ID"
-        },
-        "link": {
-          "type": "string",
-          "x-go-name": "Link"
-        },
-        "name": {
-          "type": "string",
-          "x-go-name": "Name"
-        },
-        "org": {
-          "type": "string",
-          "x-go-name": "Org"
-        },
-        "private": {
-          "type": "boolean",
-          "x-go-name": "Private"
-        },
-        "timeout": {
-          "type": "integer",
-          "format": "int64",
-          "x-go-name": "Timeout"
-        },
-        "trusted": {
-          "type": "boolean",
-          "x-go-name": "Trusted"
-        },
-        "user_id": {
-          "type": "integer",
-          "format": "int64",
-          "x-go-name": "UserID"
-        },
-        "visibility": {
-          "type": "string",
-          "x-go-name": "Visibility"
-        }
-      },
-      "x-go-package": "github.com/go-vela/types/library"
-    },
-    "Rules": {
-      "type": "object",
-      "properties": {
-        "branch": {
-          "$ref": "#/definitions/Ruletype"
-        },
-        "comment": {
-          "$ref": "#/definitions/Ruletype"
-        },
-        "event": {
-          "$ref": "#/definitions/Ruletype"
-        },
-        "path": {
-          "$ref": "#/definitions/Ruletype"
-        },
-        "repo": {
-          "$ref": "#/definitions/Ruletype"
-        },
-        "status": {
-          "$ref": "#/definitions/Ruletype"
-        },
-        "tag": {
-          "$ref": "#/definitions/Ruletype"
-        },
-        "target": {
-          "$ref": "#/definitions/Ruletype"
-        }
-      },
-      "x-go-package": "github.com/go-vela/types/pipeline"
-    },
-    "Ruleset": {
-      "type": "object",
-      "properties": {
-        "continue": {
-          "type": "boolean",
-          "x-go-name": "Continue"
-        },
-        "if": {
-          "$ref": "#/definitions/Rules"
-        },
-        "operator": {
-          "type": "string",
-          "x-go-name": "Operator"
-        },
-        "unless": {
-          "$ref": "#/definitions/Rules"
-        }
-      },
-      "x-go-package": "github.com/go-vela/types/pipeline"
-    },
-    "Ruletype": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      },
-      "x-go-package": "github.com/go-vela/types/pipeline"
-    },
-    "Secret": {
-      "type": "object",
-      "title": "Secret is the library representation of a secret.",
-      "properties": {
-        "engine": {
-          "type": "string",
-          "x-go-name": "Engine"
-        },
-        "key": {
-          "type": "string",
-          "x-go-name": "Key"
-        },
-        "name": {
-          "type": "string",
-          "x-go-name": "Name"
-        },
-        "type": {
-          "type": "string",
-          "x-go-name": "Type"
-        },
-        "value": {
-          "type": "string",
-          "x-go-name": "Value"
-        }
-      },
-      "x-go-package": "github.com/go-vela/types/pipeline"
-    },
-    "SecretSlice": {
-      "type": "array",
-      "items": {
-        "$ref": "#/definitions/Secret"
-      },
-      "x-go-package": "github.com/go-vela/types/pipeline"
-    },
-    "Stage": {
-      "type": "object",
-      "properties": {
-        "name": {
-          "type": "string",
-          "x-go-name": "Name"
-        },
-        "needs": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "x-go-name": "Needs"
-        },
-        "steps": {
-          "$ref": "#/definitions/ContainerSlice"
-        }
-      },
-      "x-go-package": "github.com/go-vela/types/pipeline"
-    },
-    "StageSlice": {
-      "type": "array",
-      "items": {
-        "$ref": "#/definitions/Stage"
-      },
-      "x-go-package": "github.com/go-vela/types/pipeline"
-    },
-    "StepSecret": {
-      "type": "object",
-      "properties": {
-        "source": {
-          "type": "string",
-          "x-go-name": "Source"
-        },
-        "target": {
-          "type": "string",
-          "x-go-name": "Target"
-        }
-      },
-      "x-go-package": "github.com/go-vela/types/pipeline"
-    },
-    "StepSecretSlice": {
-      "type": "array",
-      "items": {
-        "$ref": "#/definitions/StepSecret"
-      },
-      "x-go-package": "github.com/go-vela/types/pipeline"
-    },
-    "Ulimit": {
-      "type": "object",
-      "properties": {
-        "hard": {
-          "type": "integer",
-          "format": "int64",
-          "x-go-name": "Hard"
-        },
-        "name": {
-          "type": "string",
-          "x-go-name": "Name"
-        },
-        "soft": {
-          "type": "integer",
-          "format": "int64",
-          "x-go-name": "Soft"
-        }
-      },
-      "x-go-package": "github.com/go-vela/types/pipeline"
-    },
-    "UlimitSlice": {
-      "type": "array",
-      "items": {
-        "$ref": "#/definitions/Ulimit"
-      },
-      "x-go-package": "github.com/go-vela/types/pipeline"
-    },
-    "Volume": {
-      "type": "object",
-      "properties": {
-        "access_mode": {
-          "type": "string",
-          "x-go-name": "AccessMode"
-        },
-        "destination": {
-          "type": "string",
-          "x-go-name": "Destination"
-        },
-        "source": {
-          "type": "string",
-          "x-go-name": "Source"
-        }
-      },
-      "x-go-package": "github.com/go-vela/types/pipeline"
-    },
-    "VolumeSlice": {
-      "type": "array",
-      "items": {
-        "$ref": "#/definitions/Volume"
-      },
-      "x-go-package": "github.com/go-vela/types/pipeline"
-    }
-  },
-  "securityDefinitions": {
-    "ApiKeyAuth": {
-      "type": "apiKey",
-      "name": "Authorization",
-      "in": "header"
-    }
-  }
-}
\ No newline at end of file
diff --git a/api/build.go b/api/build.go
index e552a815..71e70d60 100644
--- a/api/build.go
+++ b/api/build.go
@@ -19,20 +19,16 @@ import (
 // Get the currently running build
 //
 // ---
-// x-success_http_code: '200'
 // produces:
 // - application/json
 // parameters:
-// - in: header
-//   name: Authorization
-//   description: Vela server token
-//   required: true
-//   type: string
 // - in: path
 //   name: executor
 //   description: The executor running the build
 //   required: true
 //   type: string
+// security:
+//   - ApiKeyAuth: []
 // responses:
 //   '200':
 //     description: Successfully retrieved the build
@@ -66,20 +62,16 @@ func GetBuild(c *gin.Context) {
 // Cancel the currently running build
 //
 // ---
-// x-success_http_code: '200'
 // produces:
 // - application/json
 // parameters:
-// - in: header
-//   name: Authorization
-//   description: Vela server token
-//   required: true
-//   type: string
 // - in: path
 //   name: executor
 //   description: The executor running the build
 //   required: true
 //   type: string
+// security:
+//   - ApiKeyAuth: []
 // responses:
 //   '200':
 //     description: Successfully canceled the build
diff --git a/api/executor.go b/api/executor.go
index d7880a63..b9ff3949 100644
--- a/api/executor.go
+++ b/api/executor.go
@@ -21,20 +21,16 @@ import (
 // Get a currently running executor
 //
 // ---
-// x-success_http_code: '200'
 // produces:
 // - application/json
 // parameters:
-// - in: header
-//   name: Authorization
-//   description: Vela server token
-//   required: true
-//   type: string
 // - in: path
 //   name: executor
 //   description: The executor to retrieve
 //   required: true
 //   type: string
+// security:
+//   - ApiKeyAuth: []
 // responses:
 //   '200':
 //     description: Successfully retrieved the executor
@@ -96,15 +92,10 @@ func GetExecutor(c *gin.Context) {
 // Get all currently running executors
 //
 // ---
-// x-success_http_code: '200'
 // produces:
 // - application/json
-// parameters:
-// - in: header
-//   name: Authorization
-//   description: Vela server token
-//   required: true
-//   type: string
+// security:
+//   - ApiKeyAuth: []
 // responses:
 //   '200':
 //     description: Successfully retrieved all running executors
diff --git a/api/health.go b/api/health.go
index 5609fb75..daa61090 100644
--- a/api/health.go
+++ b/api/health.go
@@ -15,7 +15,6 @@ import (
 // Check if the worker API is available
 //
 // ---
-// x-success_http_code: '200'
 // produces:
 // - application/json
 // parameters:
diff --git a/api/metrics.go b/api/metrics.go
index 67585339..02bb550f 100644
--- a/api/metrics.go
+++ b/api/metrics.go
@@ -15,7 +15,6 @@ import (
 // Retrieve metrics from the worker
 //
 // ---
-// x-success_http_code: '200'
 // produces:
 // - application/json
 // parameters:
diff --git a/api/pipeline.go b/api/pipeline.go
index 3755bd6f..7f266478 100644
--- a/api/pipeline.go
+++ b/api/pipeline.go
@@ -19,20 +19,16 @@ import (
 // Get a currently running pipeline
 //
 // ---
-// x-success_http_code: '200'
 // produces:
 // - application/json
 // parameters:
-// - in: header
-//   name: Authorization
-//   description: Vela server token
-//   required: true
-//   type: string
 // - in: path
 //   name: executor
 //   description: The executor running the pipeline
 //   required: true
 //   type: string
+// security:
+//   - ApiKeyAuth: []
 // responses:
 //   '200':
 //     description: Successfully retrieved the pipeline
diff --git a/api/repo.go b/api/repo.go
index 1a79af62..473e9295 100644
--- a/api/repo.go
+++ b/api/repo.go
@@ -19,20 +19,16 @@ import (
 // Get a currently running repo
 //
 // ---
-// x-success_http_code: '200'
 // produces:
 // - application/json
 // parameters:
-// - in: header
-//   name: Authorization
-//   description: Vela server token
-//   required: true
-//   type: string
 // - in: path
 //   name: executor
 //   description: The executor running the build
 //   required: true
 //   type: string
+// security:
+//   - ApiKeyAuth: []
 // responses:
 //   '200':
 //     description: Successfully retrieved the repo
diff --git a/api/shutdown.go b/api/shutdown.go
index 82e8aa2f..e4d19351 100644
--- a/api/shutdown.go
+++ b/api/shutdown.go
@@ -15,15 +15,10 @@ import (
 // Perform a soft shutdown of the worker
 //
 // ---
-// x-success_http_code: '501'
 // produces:
 // - application/json
-// parameters:
-// - in: header
-//   name: Authorization
-//   description: Vela server token
-//   required: true
-//   type: string
+// security:
+//   - ApiKeyAuth: []
 // responses:
 //   '501':
 //     description: Endpoint is not yet implemented
diff --git a/api/version.go b/api/version.go
index a7400fa9..acbbb82b 100644
--- a/api/version.go
+++ b/api/version.go
@@ -17,7 +17,6 @@ import (
 // Get the version of the Vela API
 //
 // ---
-// x-success_http_code: '200'
 // produces:
 // - application/json
 // parameters:
diff --git a/router/router.go b/router/router.go
index 7268ec9f..c515f5c9 100644
--- a/router/router.go
+++ b/router/router.go
@@ -6,9 +6,9 @@
 //
 // API for a Vela worker
 //
-//     Version: 0.4.3
+//     Version: 0.0.0-dev
 //     Schemes: http, https
-//     BasePath: ""
+//     Host: localhost
 //
 //     Consumes:
 //     - application/json
@@ -18,6 +18,7 @@
 //
 //     SecurityDefinitions:
 //       ApiKeyAuth:
+//         description: Bearer token
 //         type: apiKey
 //         in: header
 //         name: Authorization