diff --git a/api/http/handler/auth/authenticate.go b/api/http/handler/auth/authenticate.go
index 500854a0f..a890d5ab5 100644
--- a/api/http/handler/auth/authenticate.go
+++ b/api/http/handler/auth/authenticate.go
@@ -39,6 +39,7 @@ func (payload *authenticatePayload) Validate(r *http.Request) error {
 
 // @id AuthenticateUser
 // @summary Authenticate
+// @description **Access policy**: public
 // @description Use this environment(endpoint) to authenticate against Portainer using a username and password.
 // @tags auth
 // @accept json
diff --git a/api/http/handler/auth/authenticate_oauth.go b/api/http/handler/auth/authenticate_oauth.go
index 5fd2075d0..fb79b8d25 100644
--- a/api/http/handler/auth/authenticate_oauth.go
+++ b/api/http/handler/auth/authenticate_oauth.go
@@ -44,6 +44,7 @@ func (handler *Handler) authenticateOAuth(code string, settings *portainer.OAuth
 
 // @id ValidateOAuth
 // @summary Authenticate with OAuth
+// @description **Access policy**: public
 // @tags auth
 // @accept json
 // @produce json
diff --git a/api/http/handler/auth/logout.go b/api/http/handler/auth/logout.go
index 03f63566c..d2d2303d8 100644
--- a/api/http/handler/auth/logout.go
+++ b/api/http/handler/auth/logout.go
@@ -10,6 +10,7 @@ import (
 
 // @id Logout
 // @summary Logout
+// @description **Access policy**: authenticated
 // @security jwt
 // @tags auth
 // @success 204 "Success"
diff --git a/api/http/handler/backup/backup.go b/api/http/handler/backup/backup.go
index 018dd2d34..61fba3cc6 100644
--- a/api/http/handler/backup/backup.go
+++ b/api/http/handler/backup/backup.go
@@ -27,8 +27,9 @@ func (p *backupPayload) Validate(r *http.Request) error {
 // @description **Access policy**: admin
 // @tags backup
 // @security jwt
+// @accept json
 // @produce octet-stream
-// @param Password body string false "Password to encrypt the backup with"
+// @param body body backupPayload false "An object contains the password to encrypt the backup with"
 // @success 200 "Success"
 // @failure 400 "Invalid request"
 // @failure 500 "Server error"
diff --git a/api/http/handler/backup/restore.go b/api/http/handler/backup/restore.go
index db08e5335..5e533f934 100644
--- a/api/http/handler/backup/restore.go
+++ b/api/http/handler/backup/restore.go
@@ -22,10 +22,9 @@ type restorePayload struct {
 // @description Triggers a system restore using provided backup file
 // @description **Access policy**: public
 // @tags backup
-// @param FileContent body []byte true "Content of the backup"
-// @param FileName body string true "File name"
-// @param Password body string false "Password to decrypt the backup with"
-// @success 200  "Success"
+// @accept json
+// @param restorePayload body restorePayload true "Restore request payload"
+// @success 200 "Success"
 // @failure 400 "Invalid request"
 // @failure 500 "Server error"
 // @router /restore [post]
diff --git a/api/http/handler/customtemplates/customtemplate_delete.go b/api/http/handler/customtemplates/customtemplate_delete.go
index edb9cb8fe..f5a865084 100644
--- a/api/http/handler/customtemplates/customtemplate_delete.go
+++ b/api/http/handler/customtemplates/customtemplate_delete.go
@@ -16,7 +16,7 @@ import (
 // @id CustomTemplateDelete
 // @summary Remove a template
 // @description Remove a template.
-// @description **Access policy**: authorized
+// @description **Access policy**: authenticated
 // @tags custom_templates
 // @security jwt
 // @param id path int true "Template identifier"
diff --git a/api/http/handler/customtemplates/customtemplate_file.go b/api/http/handler/customtemplates/customtemplate_file.go
index c8de77de3..e238dffb5 100644
--- a/api/http/handler/customtemplates/customtemplate_file.go
+++ b/api/http/handler/customtemplates/customtemplate_file.go
@@ -18,7 +18,7 @@ type fileResponse struct {
 // @id CustomTemplateFile
 // @summary Get Template stack file content.
 // @description Retrieve the content of the Stack file for the specified custom template
-// @description **Access policy**: authorized
+// @description **Access policy**: authenticated
 // @tags custom_templates
 // @security jwt
 // @produce json
diff --git a/api/http/handler/customtemplates/customtemplate_inspect.go b/api/http/handler/customtemplates/customtemplate_inspect.go
index 500716817..118a095be 100644
--- a/api/http/handler/customtemplates/customtemplate_inspect.go
+++ b/api/http/handler/customtemplates/customtemplate_inspect.go
@@ -19,7 +19,6 @@ import (
 // @description **Access policy**: authenticated
 // @tags custom_templates
 // @security jwt
-// @accept json
 // @produce json
 // @param id path int true "Template identifier"
 // @success 200 {object} portainer.CustomTemplate "Success"
diff --git a/api/http/handler/edgegroups/edgegroup_create.go b/api/http/handler/edgegroups/edgegroup_create.go
index 087e7847a..a8d63f6e4 100644
--- a/api/http/handler/edgegroups/edgegroup_create.go
+++ b/api/http/handler/edgegroups/edgegroup_create.go
@@ -34,7 +34,7 @@ func (payload *edgeGroupCreatePayload) Validate(r *http.Request) error {
 
 // @id EdgeGroupCreate
 // @summary Create an EdgeGroup
-// @description
+// @description **Access policy**: administrator
 // @tags edge_groups
 // @security jwt
 // @accept json
diff --git a/api/http/handler/edgegroups/edgegroup_delete.go b/api/http/handler/edgegroups/edgegroup_delete.go
index 7ff9c1ed5..468df4b04 100644
--- a/api/http/handler/edgegroups/edgegroup_delete.go
+++ b/api/http/handler/edgegroups/edgegroup_delete.go
@@ -13,11 +13,9 @@ import (
 
 // @id EdgeGroupDelete
 // @summary Deletes an EdgeGroup
-// @description
+// @description **Access policy**: administrator
 // @tags edge_groups
 // @security jwt
-// @accept json
-// @produce json
 // @param id path int true "EdgeGroup Id"
 // @success 204
 // @failure 503 "Edge compute features are disabled"
diff --git a/api/http/handler/edgegroups/edgegroup_inspect.go b/api/http/handler/edgegroups/edgegroup_inspect.go
index 4d378b2be..cb81e18b7 100644
--- a/api/http/handler/edgegroups/edgegroup_inspect.go
+++ b/api/http/handler/edgegroups/edgegroup_inspect.go
@@ -12,10 +12,9 @@ import (
 
 // @id EdgeGroupInspect
 // @summary Inspects an EdgeGroup
-// @description
+// @description **Access policy**: administrator
 // @tags edge_groups
 // @security jwt
-// @accept json
 // @produce json
 // @param id path int true "EdgeGroup Id"
 // @success 200 {object} portainer.EdgeGroup
diff --git a/api/http/handler/edgegroups/edgegroup_list.go b/api/http/handler/edgegroups/edgegroup_list.go
index 5d81feed9..2c6f3bcec 100644
--- a/api/http/handler/edgegroups/edgegroup_list.go
+++ b/api/http/handler/edgegroups/edgegroup_list.go
@@ -17,10 +17,9 @@ type decoratedEdgeGroup struct {
 
 // @id EdgeGroupList
 // @summary list EdgeGroups
-// @description
+// @description **Access policy**: administrator
 // @tags edge_groups
 // @security jwt
-// @accept json
 // @produce json
 // @success 200 {array} portainer.EdgeGroup{HasEdgeStack=bool} "EdgeGroups"
 // @failure 500
diff --git a/api/http/handler/edgegroups/edgegroup_update.go b/api/http/handler/edgegroups/edgegroup_update.go
index 15920c5b2..12b1c9ca7 100644
--- a/api/http/handler/edgegroups/edgegroup_update.go
+++ b/api/http/handler/edgegroups/edgegroup_update.go
@@ -36,7 +36,7 @@ func (payload *edgeGroupUpdatePayload) Validate(r *http.Request) error {
 
 // @id EgeGroupUpdate
 // @summary Updates an EdgeGroup
-// @description
+// @description **Access policy**: administrator
 // @tags edge_groups
 // @security jwt
 // @accept json
diff --git a/api/http/handler/edgejobs/edgejob_create.go b/api/http/handler/edgejobs/edgejob_create.go
index b2c2c8f52..d5facd3c0 100644
--- a/api/http/handler/edgejobs/edgejob_create.go
+++ b/api/http/handler/edgejobs/edgejob_create.go
@@ -16,10 +16,9 @@ import (
 
 // @id EdgeJobCreate
 // @summary Create an EdgeJob
-// @description
+// @description **Access policy**: administrator
 // @tags edge_jobs
 // @security jwt
-// @accept json
 // @produce json
 // @param method query string true "Creation Method" Enums(file, string)
 // @param body_string body edgeJobCreateFromFileContentPayload true "EdgeGroup data when method is string"
diff --git a/api/http/handler/edgejobs/edgejob_delete.go b/api/http/handler/edgejobs/edgejob_delete.go
index 8217dcd39..a2686b131 100644
--- a/api/http/handler/edgejobs/edgejob_delete.go
+++ b/api/http/handler/edgejobs/edgejob_delete.go
@@ -13,11 +13,9 @@ import (
 
 // @id EdgeJobDelete
 // @summary Delete an EdgeJob
-// @description
+// @description **Access policy**: administrator
 // @tags edge_jobs
 // @security jwt
-// @accept json
-// @produce json
 // @param id path string true "EdgeJob Id"
 // @success 204
 // @failure 500
diff --git a/api/http/handler/edgejobs/edgejob_file.go b/api/http/handler/edgejobs/edgejob_file.go
index 1b5d4ae29..751d56246 100644
--- a/api/http/handler/edgejobs/edgejob_file.go
+++ b/api/http/handler/edgejobs/edgejob_file.go
@@ -16,10 +16,9 @@ type edgeJobFileResponse struct {
 
 // @id EdgeJobFile
 // @summary Fetch a file of an EdgeJob
-// @description
+// @description **Access policy**: administrator
 // @tags edge_jobs
 // @security jwt
-// @accept json
 // @produce json
 // @param id path string true "EdgeJob Id"
 // @success 200 {object} edgeJobFileResponse
diff --git a/api/http/handler/edgejobs/edgejob_inspect.go b/api/http/handler/edgejobs/edgejob_inspect.go
index 38c826227..1f402f0b9 100644
--- a/api/http/handler/edgejobs/edgejob_inspect.go
+++ b/api/http/handler/edgejobs/edgejob_inspect.go
@@ -17,10 +17,9 @@ type edgeJobInspectResponse struct {
 
 // @id EdgeJobInspect
 // @summary Inspect an EdgeJob
-// @description
+// @description **Access policy**: administrator
 // @tags edge_jobs
 // @security jwt
-// @accept json
 // @produce json
 // @param id path string true "EdgeJob Id"
 // @success 200 {object} portainer.EdgeJob
diff --git a/api/http/handler/edgejobs/edgejob_list.go b/api/http/handler/edgejobs/edgejob_list.go
index f2c93ebf1..7eca94c0a 100644
--- a/api/http/handler/edgejobs/edgejob_list.go
+++ b/api/http/handler/edgejobs/edgejob_list.go
@@ -9,10 +9,9 @@ import (
 
 // @id EdgeJobList
 // @summary Fetch EdgeJobs list
-// @description
+// @description **Access policy**: administrator
 // @tags edge_jobs
 // @security jwt
-// @accept json
 // @produce json
 // @success 200 {array} portainer.EdgeJob
 // @failure 500
diff --git a/api/http/handler/edgejobs/edgejob_tasklogs_clear.go b/api/http/handler/edgejobs/edgejob_tasklogs_clear.go
index 230b387af..1f34f7854 100644
--- a/api/http/handler/edgejobs/edgejob_tasklogs_clear.go
+++ b/api/http/handler/edgejobs/edgejob_tasklogs_clear.go
@@ -13,10 +13,9 @@ import (
 
 // @id EdgeJobTasksClear
 // @summary Clear the log for a specifc task on an EdgeJob
-// @description
+// @description **Access policy**: administrator
 // @tags edge_jobs
 // @security jwt
-// @accept json
 // @produce json
 // @param id path string true "EdgeJob Id"
 // @param taskID path string true "Task Id"
diff --git a/api/http/handler/edgejobs/edgejob_tasklogs_collect.go b/api/http/handler/edgejobs/edgejob_tasklogs_collect.go
index 919b2ff4c..be97a2320 100644
--- a/api/http/handler/edgejobs/edgejob_tasklogs_collect.go
+++ b/api/http/handler/edgejobs/edgejob_tasklogs_collect.go
@@ -12,10 +12,9 @@ import (
 
 // @id EdgeJobTasksCollect
 // @summary Collect the log for a specifc task on an EdgeJob
-// @description
+// @description **Access policy**: administrator
 // @tags edge_jobs
 // @security jwt
-// @accept json
 // @produce json
 // @param id path string true "EdgeJob Id"
 // @param taskID path string true "Task Id"
diff --git a/api/http/handler/edgejobs/edgejob_tasklogs_inspect.go b/api/http/handler/edgejobs/edgejob_tasklogs_inspect.go
index ce7813d28..320f1bfe9 100644
--- a/api/http/handler/edgejobs/edgejob_tasklogs_inspect.go
+++ b/api/http/handler/edgejobs/edgejob_tasklogs_inspect.go
@@ -15,10 +15,9 @@ type fileResponse struct {
 
 // @id EdgeJobTaskLogsInspect
 // @summary Fetch the log for a specifc task on an EdgeJob
-// @description
+// @description **Access policy**: administrator
 // @tags edge_jobs
 // @security jwt
-// @accept json
 // @produce json
 // @param id path string true "EdgeJob Id"
 // @param taskID path string true "Task Id"
diff --git a/api/http/handler/edgejobs/edgejob_tasks_list.go b/api/http/handler/edgejobs/edgejob_tasks_list.go
index 6f05946c9..430ccb3b2 100644
--- a/api/http/handler/edgejobs/edgejob_tasks_list.go
+++ b/api/http/handler/edgejobs/edgejob_tasks_list.go
@@ -19,10 +19,9 @@ type taskContainer struct {
 
 // @id EdgeJobTasksList
 // @summary Fetch the list of tasks on an EdgeJob
-// @description
+// @description **Access policy**: administrator
 // @tags edge_jobs
 // @security jwt
-// @accept json
 // @produce json
 // @param id path string true "EdgeJob Id"
 // @success 200 {array} taskContainer
diff --git a/api/http/handler/edgejobs/edgejob_update.go b/api/http/handler/edgejobs/edgejob_update.go
index 9e2a6eae0..e9753c3f9 100644
--- a/api/http/handler/edgejobs/edgejob_update.go
+++ b/api/http/handler/edgejobs/edgejob_update.go
@@ -30,7 +30,7 @@ func (payload *edgeJobUpdatePayload) Validate(r *http.Request) error {
 
 // @id EdgeJobUpdate
 // @summary Update an EdgeJob
-// @description
+// @description **Access policy**: administrator
 // @tags edge_jobs
 // @security jwt
 // @accept json
diff --git a/api/http/handler/edgestacks/edgestack_create.go b/api/http/handler/edgestacks/edgestack_create.go
index 5c12ad392..95b65319c 100644
--- a/api/http/handler/edgestacks/edgestack_create.go
+++ b/api/http/handler/edgestacks/edgestack_create.go
@@ -19,10 +19,9 @@ import (
 
 // @id EdgeStackCreate
 // @summary Create an EdgeStack
-// @description
+// @description **Access policy**: administrator
 // @tags edge_stacks
 // @security jwt
-// @accept json
 // @produce json
 // @param method query string true "Creation Method" Enums(file,string,repository)
 // @param body_string body swarmStackFromFileContentPayload true "Required when using method=string"
diff --git a/api/http/handler/edgestacks/edgestack_delete.go b/api/http/handler/edgestacks/edgestack_delete.go
index b9e61d594..9b536ba52 100644
--- a/api/http/handler/edgestacks/edgestack_delete.go
+++ b/api/http/handler/edgestacks/edgestack_delete.go
@@ -13,11 +13,9 @@ import (
 
 // @id EdgeStackDelete
 // @summary Delete an EdgeStack
-// @description
+// @description **Access policy**: administrator
 // @tags edge_stacks
 // @security jwt
-// @accept json
-// @produce json
 // @param id path string true "EdgeStack Id"
 // @success 204
 // @failure 500
diff --git a/api/http/handler/edgestacks/edgestack_file.go b/api/http/handler/edgestacks/edgestack_file.go
index 5584fd806..7ecafa883 100644
--- a/api/http/handler/edgestacks/edgestack_file.go
+++ b/api/http/handler/edgestacks/edgestack_file.go
@@ -17,10 +17,9 @@ type stackFileResponse struct {
 
 // @id EdgeStackFile
 // @summary Fetches the stack file for an EdgeStack
-// @description
+// @description **Access policy**: administrator
 // @tags edge_stacks
 // @security jwt
-// @accept json
 // @produce json
 // @param id path string true "EdgeStack Id"
 // @success 200 {object} stackFileResponse
diff --git a/api/http/handler/edgestacks/edgestack_inspect.go b/api/http/handler/edgestacks/edgestack_inspect.go
index 463fca874..24376e803 100644
--- a/api/http/handler/edgestacks/edgestack_inspect.go
+++ b/api/http/handler/edgestacks/edgestack_inspect.go
@@ -12,10 +12,9 @@ import (
 
 // @id EdgeStackInspect
 // @summary Inspect an EdgeStack
-// @description
+// @description **Access policy**: administrator
 // @tags edge_stacks
 // @security jwt
-// @accept json
 // @produce json
 // @param id path string true "EdgeStack Id"
 // @success 200 {object} portainer.EdgeStack
diff --git a/api/http/handler/edgestacks/edgestack_list.go b/api/http/handler/edgestacks/edgestack_list.go
index 5be73dea1..2e4d8a4f3 100644
--- a/api/http/handler/edgestacks/edgestack_list.go
+++ b/api/http/handler/edgestacks/edgestack_list.go
@@ -9,10 +9,9 @@ import (
 
 // @id EdgeStackList
 // @summary Fetches the list of EdgeStacks
-// @description
+// @description **Access policy**: administrator
 // @tags edge_stacks
 // @security jwt
-// @accept json
 // @produce json
 // @success 200 {array} portainer.EdgeStack
 // @failure 500
diff --git a/api/http/handler/edgestacks/edgestack_update.go b/api/http/handler/edgestacks/edgestack_update.go
index 80c148e58..f4ac69367 100644
--- a/api/http/handler/edgestacks/edgestack_update.go
+++ b/api/http/handler/edgestacks/edgestack_update.go
@@ -33,7 +33,7 @@ func (payload *updateEdgeStackPayload) Validate(r *http.Request) error {
 
 // @id EdgeStackUpdate
 // @summary Update an EdgeStack
-// @description
+// @description **Access policy**: administrator
 // @tags edge_stacks
 // @security jwt
 // @accept json
diff --git a/api/http/handler/edgetemplates/edgetemplate_list.go b/api/http/handler/edgetemplates/edgetemplate_list.go
index 0dfc766c9..05a9c5b03 100644
--- a/api/http/handler/edgetemplates/edgetemplate_list.go
+++ b/api/http/handler/edgetemplates/edgetemplate_list.go
@@ -17,7 +17,7 @@ type templateFileFormat struct {
 
 // @id EdgeTemplateList
 // @summary Fetches the list of Edge Templates
-// @description
+// @description **Access policy**: administrator
 // @tags edge_templates
 // @security jwt
 // @accept json
diff --git a/api/http/handler/endpointedge/endpoint_edgejob_logs.go b/api/http/handler/endpointedge/endpoint_edgejob_logs.go
index 629783bf9..838754503 100644
--- a/api/http/handler/endpointedge/endpoint_edgejob_logs.go
+++ b/api/http/handler/endpointedge/endpoint_edgejob_logs.go
@@ -21,7 +21,7 @@ func (payload *logsPayload) Validate(r *http.Request) error {
 
 // endpointEdgeJobsLogs
 // @summary Inspect an EdgeJob Log
-// @description
+// @description **Access policy**: public
 // @tags edge, endpoints
 // @accept json
 // @produce json
diff --git a/api/http/handler/endpointedge/endpoint_edgestack_inspect.go b/api/http/handler/endpointedge/endpoint_edgestack_inspect.go
index 11b85ff9b..7f89f128c 100644
--- a/api/http/handler/endpointedge/endpoint_edgestack_inspect.go
+++ b/api/http/handler/endpointedge/endpoint_edgestack_inspect.go
@@ -19,7 +19,7 @@ type configResponse struct {
 }
 
 // @summary Inspect an Edge Stack for an Environment(Endpoint)
-// @description
+// @description **Access policy**: public
 // @tags edge, endpoints, edge_stacks
 // @accept json
 // @produce json
diff --git a/api/http/handler/endpointgroups/endpointgroup_delete.go b/api/http/handler/endpointgroups/endpointgroup_delete.go
index f2375d0a6..40c5a1c59 100644
--- a/api/http/handler/endpointgroups/endpointgroup_delete.go
+++ b/api/http/handler/endpointgroups/endpointgroup_delete.go
@@ -17,8 +17,6 @@ import (
 // @description **Access policy**: administrator
 // @tags endpoint_groups
 // @security jwt
-// @accept json
-// @produce json
 // @param id path int true "EndpointGroup identifier"
 // @success 204 "Success"
 // @failure 400 "Invalid request"
diff --git a/api/http/handler/endpoints/endpoint_association_delete.go b/api/http/handler/endpoints/endpoint_association_delete.go
index 092f9bd30..0a4a05152 100644
--- a/api/http/handler/endpoints/endpoint_association_delete.go
+++ b/api/http/handler/endpoints/endpoint_association_delete.go
@@ -27,7 +27,7 @@ import (
 // @failure 400 "Invalid request"
 // @failure 404 "Environment(Endpoint) not found"
 // @failure 500 "Server error"
-// @router /api/endpoints/{id}/association [put]
+// @router /endpoints/{id}/association [put]
 func (handler *Handler) endpointAssociationDelete(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	endpointID, err := request.RetrieveNumericRouteVariableValue(r, "id")
 	if err != nil {
diff --git a/api/http/handler/endpoints/endpoint_dockerhub_status.go b/api/http/handler/endpoints/endpoint_dockerhub_status.go
index 5be4d39a4..7c5b33277 100644
--- a/api/http/handler/endpoints/endpoint_dockerhub_status.go
+++ b/api/http/handler/endpoints/endpoint_dockerhub_status.go
@@ -18,11 +18,27 @@ import (
 )
 
 type dockerhubStatusResponse struct {
+	// Remaiming images to pull
 	Remaining int `json:"remaining"`
-	Limit     int `json:"limit"`
+	// Daily limit
+	Limit int `json:"limit"`
 }
 
-// GET request on /api/endpoints/{id}/dockerhub/{registryId}
+// @id endpointDockerhubStatus
+// @summary fetch docker pull limits
+// @description get docker pull limits for a docker hub registry in the environment
+// @description **Access policy**:
+// @tags endpoints
+// @security jwt
+// @produce json
+// @param id path int true "endpoint ID"
+// @param registryId path int true "registry ID"
+// @success 200 {object} dockerhubStatusResponse "Success"
+// @failure 400 "Invalid request"
+// @failure 403 "Permission denied"
+// @failure 404 "registry or endpoint not found"
+// @failure 500 "Server error"
+// @router /endpoints/{id}/dockerhub/{registryId} [get]
 func (handler *Handler) endpointDockerhubStatus(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	endpointID, err := request.RetrieveNumericRouteVariableValue(r, "id")
 	if err != nil {
diff --git a/api/http/handler/endpoints/endpoint_extension_add.go b/api/http/handler/endpoints/endpoint_extension_add.go
index 7e08fc1b8..fb84af010 100644
--- a/api/http/handler/endpoints/endpoint_extension_add.go
+++ b/api/http/handler/endpoints/endpoint_extension_add.go
@@ -29,6 +29,12 @@ func (payload *endpointExtensionAddPayload) Validate(r *http.Request) error {
 	return nil
 }
 
+// @id endpointExtensionAdd
+// @tags endpoints
+// @deprecated
+// @param id path int true "Environment(Endpoint) identifier"
+// @success 204 "Success"
+// @router /endpoints/{id}/extensions [post]
 func (handler *Handler) endpointExtensionAdd(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	endpointID, err := request.RetrieveNumericRouteVariableValue(r, "id")
 	if err != nil {
diff --git a/api/http/handler/endpoints/endpoint_extension_remove.go b/api/http/handler/endpoints/endpoint_extension_remove.go
index 75d798cd7..94893fcd6 100644
--- a/api/http/handler/endpoints/endpoint_extension_remove.go
+++ b/api/http/handler/endpoints/endpoint_extension_remove.go
@@ -12,6 +12,13 @@ import (
 	"github.com/portainer/portainer/api/bolt/errors"
 )
 
+// @id endpointExtensionRemove
+// @tags endpoints
+// @deprecated
+// @param id path int true "Environment(Endpoint) identifier"
+// @param extensionType path string true "Extension Type"
+// @success 204 "Success"
+// @router /endpoints/{id}/extensions/{extensionType} [delete]
 func (handler *Handler) endpointExtensionRemove(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	endpointID, err := request.RetrieveNumericRouteVariableValue(r, "id")
 	if err != nil {
diff --git a/api/http/handler/endpoints/endpoint_registries_inspect.go b/api/http/handler/endpoints/endpoint_registries_inspect.go
index 03c0fe66c..8c4e94d84 100644
--- a/api/http/handler/endpoints/endpoint_registries_inspect.go
+++ b/api/http/handler/endpoints/endpoint_registries_inspect.go
@@ -12,7 +12,20 @@ import (
 	"github.com/portainer/portainer/api/http/security"
 )
 
-// GET request on /endpoints/{id}/registries/{registryId}
+// @id endpointRegistryInspect
+// @summary get registry for environment
+// @description **Access policy**: authenticated
+// @tags endpoints
+// @security jwt
+// @produce json
+// @param id path int true "identifier"
+// @param registryId path int true "Registry identifier"
+// @success 200 {object} portainer.Registry "Success"
+// @failure 400 "Invalid request"
+// @failure 403 "Permission denied"
+// @failure 404 "Registry not found"
+// @failure 500 "Server error"
+// @router /endpoints/{id}/registries/{registryId} [get]
 func (handler *Handler) endpointRegistryInspect(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	endpointID, err := request.RetrieveNumericRouteVariableValue(r, "id")
 	if err != nil {
diff --git a/api/http/handler/endpoints/endpoint_registries_list.go b/api/http/handler/endpoints/endpoint_registries_list.go
index 7d276e000..cb22677dc 100644
--- a/api/http/handler/endpoints/endpoint_registries_list.go
+++ b/api/http/handler/endpoints/endpoint_registries_list.go
@@ -13,7 +13,18 @@ import (
 	"github.com/portainer/portainer/api/internal/endpointutils"
 )
 
-// GET request on /endpoints/{id}/registries?namespace
+// @id endpointRegistriesList
+// @summary List Registries on environment
+// @description List all registries based on the current user authorizations in current environment.
+// @description **Access policy**: authenticated
+// @tags endpoints
+// @param namespace query string false "required if kubernetes environment, will show registries by namespace"
+// @security jwt
+// @produce json
+// @param id path int true "Environment(Endpoint) identifier"
+// @success 200 {array} portainer.Registry "Success"
+// @failure 500 "Server error"
+// @router /endpoints/{id}/registries [get]
 func (handler *Handler) endpointRegistriesList(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	securityContext, err := security.RetrieveRestrictedRequestContext(r)
 	if err != nil {
diff --git a/api/http/handler/endpoints/endpoint_registry_access.go b/api/http/handler/endpoints/endpoint_registry_access.go
index d74fe721e..3f02e46c0 100644
--- a/api/http/handler/endpoints/endpoint_registry_access.go
+++ b/api/http/handler/endpoints/endpoint_registry_access.go
@@ -21,7 +21,22 @@ func (payload *registryAccessPayload) Validate(r *http.Request) error {
 	return nil
 }
 
-// PUT request on /endpoints/{id}/registries/{registryId}
+// @id endpointRegistryAccess
+// @summary update registry access for environment
+// @description **Access policy**: authenticated
+// @tags endpoints
+// @security jwt
+// @accept json
+// @produce json
+// @param id path int true "Environment(Endpoint) identifier"
+// @param registryId path int true "Registry identifier"
+// @param body body registryAccessPayload true "details"
+// @success 204 "Success"
+// @failure 400 "Invalid request"
+// @failure 403 "Permission denied"
+// @failure 404 "Endpoint not found"
+// @failure 500 "Server error"
+// @router /endpoints/{id}/registries/{registryId} [put]
 func (handler *Handler) endpointRegistryAccess(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	endpointID, err := request.RetrieveNumericRouteVariableValue(r, "id")
 	if err != nil {
diff --git a/api/http/handler/endpoints/endpoint_settings_update.go b/api/http/handler/endpoints/endpoint_settings_update.go
index 0950f2d24..6e31fd01b 100644
--- a/api/http/handler/endpoints/endpoint_settings_update.go
+++ b/api/http/handler/endpoints/endpoint_settings_update.go
@@ -36,9 +36,9 @@ func (payload *endpointSettingsUpdatePayload) Validate(r *http.Request) error {
 }
 
 // @id EndpointSettingsUpdate
-// @summary Update settings for an environments(endpoints)
-// @description Update settings for an environments(endpoints).
-// @description **Access policy**: administrator
+// @summary Update settings for an environment(endpoint)
+// @description Update settings for an environment(endpoint).
+// @description **Access policy**: authenticated
 // @security jwt
 // @tags endpoints
 // @accept json
@@ -49,7 +49,7 @@ func (payload *endpointSettingsUpdatePayload) Validate(r *http.Request) error {
 // @failure 400 "Invalid request"
 // @failure 404 "Environment(Endpoint) not found"
 // @failure 500 "Server error"
-// @router /api/endpoints/{id}/settings [put]
+// @router /endpoints/{id}/settings [put]
 func (handler *Handler) endpointSettingsUpdate(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	endpointID, err := request.RetrieveNumericRouteVariableValue(r, "id")
 	if err != nil {
diff --git a/api/http/handler/endpoints/endpoint_snapshot.go b/api/http/handler/endpoints/endpoint_snapshot.go
index 8d9ed811c..cbecbad5d 100644
--- a/api/http/handler/endpoints/endpoint_snapshot.go
+++ b/api/http/handler/endpoints/endpoint_snapshot.go
@@ -12,9 +12,9 @@ import (
 )
 
 // @id EndpointSnapshot
-// @summary Snapshots an environments(endpoints)
-// @description Snapshots an environments(endpoints)
-// @description **Access policy**: restricted
+// @summary Snapshots an environment(endpoint)
+// @description Snapshots an environment(endpoint)
+// @description **Access policy**: administrator
 // @tags endpoints
 // @security jwt
 // @param id path int true "Environment(Endpoint) identifier"
diff --git a/api/http/handler/endpoints/endpoint_update.go b/api/http/handler/endpoints/endpoint_update.go
index dfef69542..274eb1056 100644
--- a/api/http/handler/endpoints/endpoint_update.go
+++ b/api/http/handler/endpoints/endpoint_update.go
@@ -56,7 +56,7 @@ func (payload *endpointUpdatePayload) Validate(r *http.Request) error {
 // @id EndpointUpdate
 // @summary Update an environment(endpoint)
 // @description Update an environment(endpoint).
-// @description **Access policy**: administrator
+// @description **Access policy**: authenticated
 // @security jwt
 // @tags endpoints
 // @accept json
diff --git a/api/http/handler/helm/helm_delete.go b/api/http/handler/helm/helm_delete.go
index e3bfe6a4e..8cfb766f1 100644
--- a/api/http/handler/helm/helm_delete.go
+++ b/api/http/handler/helm/helm_delete.go
@@ -12,11 +12,9 @@ import (
 // @id HelmDelete
 // @summary Delete Helm Release
 // @description
-// @description **Access policy**: authorized
+// @description **Access policy**: authenticated
 // @tags helm
 // @security jwt
-// @accept json
-// @produce json
 // @param id path int true "Environment(Endpoint) identifier"
 // @param release path string true "The name of the release/application to uninstall"
 // @param namespace query string true "An optional namespace"
diff --git a/api/http/handler/helm/helm_install.go b/api/http/handler/helm/helm_install.go
index ab196d8c5..1bbe1db83 100644
--- a/api/http/handler/helm/helm_install.go
+++ b/api/http/handler/helm/helm_install.go
@@ -36,7 +36,7 @@ var errChartNameInvalid = errors.New("invalid chart name. " +
 // @id HelmInstall
 // @summary Install Helm Chart
 // @description
-// @description **Access policy**: authorized
+// @description **Access policy**: authenticated
 // @tags helm
 // @security jwt
 // @accept json
diff --git a/api/http/handler/helm/helm_list.go b/api/http/handler/helm/helm_list.go
index d559af9c6..7200d0b5b 100644
--- a/api/http/handler/helm/helm_list.go
+++ b/api/http/handler/helm/helm_list.go
@@ -12,7 +12,7 @@ import (
 // @id HelmList
 // @summary List Helm Releases
 // @description
-// @description **Access policy**: authorized
+// @description **Access policy**: authenticated
 // @tags helm
 // @security jwt
 // @accept json
diff --git a/api/http/handler/helm/helm_repo_search.go b/api/http/handler/helm/helm_repo_search.go
index c5192f178..673555e68 100644
--- a/api/http/handler/helm/helm_repo_search.go
+++ b/api/http/handler/helm/helm_repo_search.go
@@ -13,7 +13,7 @@ import (
 // @id HelmRepoSearch
 // @summary Search Helm Charts
 // @description
-// @description **Access policy**: authorized
+// @description **Access policy**: authenticated
 // @tags helm
 // @param repo query string true "Helm repository URL"
 // @security jwt
diff --git a/api/http/handler/helm/helm_show.go b/api/http/handler/helm/helm_show.go
index 5ecfcffae..76a143f44 100644
--- a/api/http/handler/helm/helm_show.go
+++ b/api/http/handler/helm/helm_show.go
@@ -15,8 +15,8 @@ import (
 // @id HelmShow
 // @summary Show Helm Chart Information
 // @description
-// @description **Access policy**: authorized
-// @tags helm_chart
+// @description **Access policy**: authenticated
+// @tags helm
 // @param repo query string true "Helm repository URL"
 // @param chart query string true "Chart name"
 // @param command path string true "chart/values/readme"
diff --git a/api/http/handler/kubernetes/kubernetes_config.go b/api/http/handler/kubernetes/kubernetes_config.go
index df62601ed..a77e8afd5 100644
--- a/api/http/handler/kubernetes/kubernetes_config.go
+++ b/api/http/handler/kubernetes/kubernetes_config.go
@@ -17,7 +17,7 @@ import (
 // @id GetKubernetesConfig
 // @summary Generates kubeconfig file enabling client communication with k8s api server
 // @description Generates kubeconfig file enabling client communication with k8s api server
-// @description **Access policy**: authorized
+// @description **Access policy**: authenticated
 // @tags kubernetes
 // @security jwt
 // @accept json
diff --git a/api/http/handler/kubernetes/kubernetes_nodes_limits.go b/api/http/handler/kubernetes/kubernetes_nodes_limits.go
index 7bcaed27b..22c40bd08 100644
--- a/api/http/handler/kubernetes/kubernetes_nodes_limits.go
+++ b/api/http/handler/kubernetes/kubernetes_nodes_limits.go
@@ -13,7 +13,7 @@ import (
 // @id getKubernetesNodesLimits
 // @summary Get CPU and memory limits of all nodes within k8s cluster
 // @description Get CPU and memory limits of all nodes within k8s cluster
-// @description **Access policy**: authorized
+// @description **Access policy**: authenticated
 // @tags kubernetes
 // @security jwt
 // @accept json
diff --git a/api/http/handler/motd/motd.go b/api/http/handler/motd/motd.go
index d0ffc0d72..18848585e 100644
--- a/api/http/handler/motd/motd.go
+++ b/api/http/handler/motd/motd.go
@@ -26,7 +26,9 @@ type motdData struct {
 	Style         string            `json:"style"`
 }
 
+// @id MOTD
 // @summary fetches the message of the day
+// @description **Access policy**: restricted
 // @tags motd
 // @security jwt
 // @produce json
diff --git a/api/http/handler/registries/registry_configure.go b/api/http/handler/registries/registry_configure.go
index cc9398a61..0be1a5068 100644
--- a/api/http/handler/registries/registry_configure.go
+++ b/api/http/handler/registries/registry_configure.go
@@ -81,7 +81,7 @@ func (payload *registryConfigurePayload) Validate(r *http.Request) error {
 // @id RegistryConfigure
 // @summary Configures a registry
 // @description Configures a registry.
-// @description **Access policy**: admin
+// @description **Access policy**: restricted
 // @tags registries
 // @security jwt
 // @accept json
diff --git a/api/http/handler/registries/registry_create.go b/api/http/handler/registries/registry_create.go
index 017121887..0ce637416 100644
--- a/api/http/handler/registries/registry_create.go
+++ b/api/http/handler/registries/registry_create.go
@@ -62,7 +62,7 @@ func (payload *registryCreatePayload) Validate(_ *http.Request) error {
 // @id RegistryCreate
 // @summary Create a new registry
 // @description Create a new registry.
-// @description **Access policy**: administrator
+// @description **Access policy**: restricted
 // @tags registries
 // @security jwt
 // @accept json
diff --git a/api/http/handler/registries/registry_delete.go b/api/http/handler/registries/registry_delete.go
index d5db6769a..2cb101267 100644
--- a/api/http/handler/registries/registry_delete.go
+++ b/api/http/handler/registries/registry_delete.go
@@ -15,7 +15,7 @@ import (
 // @id RegistryDelete
 // @summary Remove a registry
 // @description Remove a registry
-// @description **Access policy**: administrator
+// @description **Access policy**: restricted
 // @tags registries
 // @security jwt
 // @param id path int true "Registry identifier"
diff --git a/api/http/handler/registries/registry_inspect.go b/api/http/handler/registries/registry_inspect.go
index 29b57fbc2..0575d04c3 100644
--- a/api/http/handler/registries/registry_inspect.go
+++ b/api/http/handler/registries/registry_inspect.go
@@ -14,7 +14,7 @@ import (
 // @id RegistryInspect
 // @summary Inspect a registry
 // @description Retrieve details about a registry.
-// @description **Access policy**: administrator
+// @description **Access policy**: restricted
 // @tags registries
 // @security jwt
 // @produce json
diff --git a/api/http/handler/registries/registry_update.go b/api/http/handler/registries/registry_update.go
index bf89fab82..449e47236 100644
--- a/api/http/handler/registries/registry_update.go
+++ b/api/http/handler/registries/registry_update.go
@@ -37,7 +37,7 @@ func (payload *registryUpdatePayload) Validate(r *http.Request) error {
 // @id RegistryUpdate
 // @summary Update a registry
 // @description Update a registry
-// @description **Access policy**: administrator
+// @description **Access policy**: restricted
 // @tags registries
 // @security jwt
 // @accept json
diff --git a/api/http/handler/resourcecontrols/resourcecontrol_update.go b/api/http/handler/resourcecontrols/resourcecontrol_update.go
index 47336a8f1..6f8bfd8c8 100644
--- a/api/http/handler/resourcecontrols/resourcecontrol_update.go
+++ b/api/http/handler/resourcecontrols/resourcecontrol_update.go
@@ -38,7 +38,7 @@ func (payload *resourceControlUpdatePayload) Validate(r *http.Request) error {
 // @id ResourceControlUpdate
 // @summary Update a resource control
 // @description Update a resource control
-// @description **Access policy**: restricted
+// @description **Access policy**: authenticated
 // @tags resource_controls
 // @security jwt
 // @accept json
diff --git a/api/http/handler/stacks/stack_associate.go b/api/http/handler/stacks/stack_associate.go
index 14a04ed89..84c3aca66 100644
--- a/api/http/handler/stacks/stack_associate.go
+++ b/api/http/handler/stacks/stack_associate.go
@@ -14,7 +14,22 @@ import (
 	"github.com/portainer/portainer/api/internal/stackutils"
 )
 
-// PUT request on /api/stacks/:id/associate?endpointId=<endpointId>&swarmId=<swarmId>&orphanedRunning=<orphanedRunning>
+// @id StackAssociate
+// @summary Associate an orphaned stack to a new environment(endpoint)
+// @description **Access policy**: administrator
+// @tags stacks
+// @security jwt
+// @produce json
+// @param id path int true "Stack identifier"
+// @param endpointId query int true "Stacks created before version 1.18.0 might not have an associated environment(endpoint) identifier. Use this optional parameter to set the environment(endpoint) identifier used by the stack."
+// @param swarmId query int true "Swarm identifier"
+// @param orphanedRunning query boolean true "Indicates whether the stack is orphaned"
+// @success 200 {object} portainer.Stack "Success"
+// @failure 400 "Invalid request"
+// @failure 403 "Permission denied"
+// @failure 404 "Stack not found"
+// @failure 500 "Server error"
+// @router /stacks/{id}/associate [put]
 func (handler *Handler) stackAssociate(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	stackID, err := request.RetrieveNumericRouteVariableValue(r, "id")
 	if err != nil {
diff --git a/api/http/handler/stacks/stack_create.go b/api/http/handler/stacks/stack_create.go
index 225dcb42d..6381ccc5a 100644
--- a/api/http/handler/stacks/stack_create.go
+++ b/api/http/handler/stacks/stack_create.go
@@ -33,7 +33,7 @@ func (handler *Handler) cleanUp(stack *portainer.Stack, doCleanUp *bool) error {
 // @id StackCreate
 // @summary Deploy a new stack
 // @description Deploy a new stack into a Docker environment(endpoint) specified via the environment(endpoint) identifier.
-// @description **Access policy**: restricted
+// @description **Access policy**: authenticated
 // @tags stacks
 // @security jwt
 // @accept json,multipart/form-data
diff --git a/api/http/handler/stacks/stack_list.go b/api/http/handler/stacks/stack_list.go
index aeb950bda..a79bb3be6 100644
--- a/api/http/handler/stacks/stack_list.go
+++ b/api/http/handler/stacks/stack_list.go
@@ -24,7 +24,7 @@ type stackListOperationFilters struct {
 // @description List all stacks based on the current user authorizations.
 // @description Will return all stacks if using an administrator account otherwise it
 // @description will only return the list of stacks the user have access to.
-// @description **Access policy**: restricted
+// @description **Access policy**: authenticated
 // @tags stacks
 // @security jwt
 // @param filters query string false "Filters to process on the stack list. Encoded as JSON (a map[string]string). For example, {"SwarmID": "jpofkc0i9uo9wtx1zesuk649w"} will only return stacks that are part of the specified Swarm cluster. Available filters: EndpointID, SwarmID."
diff --git a/api/http/handler/stacks/stack_migrate.go b/api/http/handler/stacks/stack_migrate.go
index d69666d90..5cdb17a6b 100644
--- a/api/http/handler/stacks/stack_migrate.go
+++ b/api/http/handler/stacks/stack_migrate.go
@@ -34,7 +34,7 @@ func (payload *stackMigratePayload) Validate(r *http.Request) error {
 // @id StackMigrate
 // @summary Migrate a stack to another environment(endpoint)
 // @description  Migrate a stack from an environment(endpoint) to another environment(endpoint). It will re-create the stack inside the target environment(endpoint) before removing the original stack.
-// @description **Access policy**: restricted
+// @description **Access policy**: authenticated
 // @tags stacks
 // @security jwt
 // @produce json
diff --git a/api/http/handler/stacks/stack_start.go b/api/http/handler/stacks/stack_start.go
index 7c1f20f97..6144d4230 100644
--- a/api/http/handler/stacks/stack_start.go
+++ b/api/http/handler/stacks/stack_start.go
@@ -20,7 +20,7 @@ import (
 // @id StackStart
 // @summary Starts a stopped Stack
 // @description Starts a stopped Stack.
-// @description **Access policy**: restricted
+// @description **Access policy**: authenticated
 // @tags stacks
 // @security jwt
 // @param id path int true "Stack identifier"
diff --git a/api/http/handler/stacks/stack_stop.go b/api/http/handler/stacks/stack_stop.go
index 0b9816ef4..5de94af75 100644
--- a/api/http/handler/stacks/stack_stop.go
+++ b/api/http/handler/stacks/stack_stop.go
@@ -18,7 +18,7 @@ import (
 // @id StackStop
 // @summary Stops a stopped Stack
 // @description Stops a stopped Stack.
-// @description **Access policy**: restricted
+// @description **Access policy**: authenticated
 // @tags stacks
 // @security jwt
 // @param id path int true "Stack identifier"
diff --git a/api/http/handler/stacks/stack_update.go b/api/http/handler/stacks/stack_update.go
index 02147b546..6cca116b4 100644
--- a/api/http/handler/stacks/stack_update.go
+++ b/api/http/handler/stacks/stack_update.go
@@ -51,7 +51,7 @@ func (payload *updateSwarmStackPayload) Validate(r *http.Request) error {
 // @id StackUpdate
 // @summary Update a stack
 // @description Update a stack.
-// @description **Access policy**: restricted
+// @description **Access policy**: authenticated
 // @tags stacks
 // @security jwt
 // @accept json
diff --git a/api/http/handler/stacks/stack_update_git.go b/api/http/handler/stacks/stack_update_git.go
index a37ba54f5..cfafacbf0 100644
--- a/api/http/handler/stacks/stack_update_git.go
+++ b/api/http/handler/stacks/stack_update_git.go
@@ -40,7 +40,7 @@ func (payload *stackGitUpdatePayload) Validate(r *http.Request) error {
 // @id StackUpdateGit
 // @summary Update a stack's Git configs
 // @description Update the Git settings in a stack, e.g., RepositoryReferenceName and AutoUpdate
-// @description **Access policy**: restricted
+// @description **Access policy**: authenticated
 // @tags stacks
 // @security jwt
 // @accept json
diff --git a/api/http/handler/stacks/stack_update_git_redeploy.go b/api/http/handler/stacks/stack_update_git_redeploy.go
index 300a33d07..0a2d58f1c 100644
--- a/api/http/handler/stacks/stack_update_git_redeploy.go
+++ b/api/http/handler/stacks/stack_update_git_redeploy.go
@@ -38,7 +38,7 @@ func (payload *stackGitRedployPayload) Validate(r *http.Request) error {
 // @id StackGitRedeploy
 // @summary Redeploy a stack
 // @description Pull and redeploy a stack via Git
-// @description **Access policy**: restricted
+// @description **Access policy**: authenticated
 // @tags stacks
 // @security jwt
 // @accept json
diff --git a/api/http/handler/stacks/webhook_invoke.go b/api/http/handler/stacks/webhook_invoke.go
index 5868dc79e..0bcc4d99d 100644
--- a/api/http/handler/stacks/webhook_invoke.go
+++ b/api/http/handler/stacks/webhook_invoke.go
@@ -15,6 +15,16 @@ import (
 	"github.com/portainer/libhttp/request"
 )
 
+// @id WebhookInvoke
+// @summary Webhook for triggering stack updates from git
+// @description **Access policy**: public
+// @tags stacks
+// @param webhookID path string true "Stack identifier"
+// @success 200 "Success"
+// @failure 400 "Invalid request"
+// @failure 409 "Conflict"
+// @failure 500 "Server error"
+// @router /stacks/webhooks/{webhookID} [post]
 func (handler *Handler) webhookInvoke(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	webhookID, err := retrieveUUIDRouteVariableValue(r, "webhookID")
 	if err != nil {
diff --git a/api/http/handler/tags/tag_create.go b/api/http/handler/tags/tag_create.go
index d969d3d91..0a47a0e64 100644
--- a/api/http/handler/tags/tag_create.go
+++ b/api/http/handler/tags/tag_create.go
@@ -29,6 +29,7 @@ func (payload *tagCreatePayload) Validate(r *http.Request) error {
 // @description **Access policy**: administrator
 // @tags tags
 // @security jwt
+// @accept json
 // @produce json
 // @param body body tagCreatePayload true "Tag details"
 // @success 200 {object} portainer.Tag "Success"
diff --git a/api/http/handler/tags/tag_delete.go b/api/http/handler/tags/tag_delete.go
index 9d756cb89..9946e2cc3 100644
--- a/api/http/handler/tags/tag_delete.go
+++ b/api/http/handler/tags/tag_delete.go
@@ -17,8 +17,6 @@ import (
 // @description **Access policy**: administrator
 // @tags tags
 // @security jwt
-// @accept json
-// @produce json
 // @param id path int true "Tag identifier"
 // @success 204 "Success"
 // @failure 400 "Invalid request"
diff --git a/api/http/handler/tags/tag_list.go b/api/http/handler/tags/tag_list.go
index 52852809b..070f5eba5 100644
--- a/api/http/handler/tags/tag_list.go
+++ b/api/http/handler/tags/tag_list.go
@@ -10,7 +10,7 @@ import (
 // @id TagList
 // @summary List tags
 // @description List tags.
-// @description **Access policy**: administrator
+// @description **Access policy**: authenticated
 // @tags tags
 // @security jwt
 // @produce json
diff --git a/api/http/handler/teammemberships/teammembership_create.go b/api/http/handler/teammemberships/teammembership_create.go
index 1b61e99a1..3096d2105 100644
--- a/api/http/handler/teammemberships/teammembership_create.go
+++ b/api/http/handler/teammemberships/teammembership_create.go
@@ -37,7 +37,7 @@ func (payload *teamMembershipCreatePayload) Validate(r *http.Request) error {
 // @id TeamMembershipCreate
 // @summary Create a new team membership
 // @description Create a new team memberships. Access is only available to administrators leaders of the associated team.
-// @description **Access policy**: admin
+// @description **Access policy**: administrator
 // @tags team_memberships
 // @security jwt
 // @accept json
diff --git a/api/http/handler/teammemberships/teammembership_delete.go b/api/http/handler/teammemberships/teammembership_delete.go
index bcc4ac1c9..f53997ca7 100644
--- a/api/http/handler/teammemberships/teammembership_delete.go
+++ b/api/http/handler/teammemberships/teammembership_delete.go
@@ -15,7 +15,7 @@ import (
 // @id TeamMembershipDelete
 // @summary Remove a team membership
 // @description Remove a team membership. Access is only available to administrators leaders of the associated team.
-// @description **Access policy**: restricted
+// @description **Access policy**: administrator
 // @tags team_memberships
 // @security jwt
 // @param id path int true "TeamMembership identifier"
diff --git a/api/http/handler/teammemberships/teammembership_list.go b/api/http/handler/teammemberships/teammembership_list.go
index 7c69a9be9..e88b67a48 100644
--- a/api/http/handler/teammemberships/teammembership_list.go
+++ b/api/http/handler/teammemberships/teammembership_list.go
@@ -12,7 +12,7 @@ import (
 // @id TeamMembershipList
 // @summary List team memberships
 // @description  List team memberships. Access is only available to administrators and team leaders.
-// @description **Access policy**: admin
+// @description **Access policy**: administrator
 // @tags team_memberships
 // @security jwt
 // @produce json
diff --git a/api/http/handler/teammemberships/teammembership_update.go b/api/http/handler/teammemberships/teammembership_update.go
index b01130a40..e1c28b66e 100644
--- a/api/http/handler/teammemberships/teammembership_update.go
+++ b/api/http/handler/teammemberships/teammembership_update.go
@@ -38,7 +38,7 @@ func (payload *teamMembershipUpdatePayload) Validate(r *http.Request) error {
 // @id TeamMembershipUpdate
 // @summary Update a team membership
 // @description Update a team membership. Access is only available to administrators leaders of the associated team.
-// @description **Access policy**: restricted
+// @description **Access policy**: administrator
 // @tags team_memberships
 // @security jwt
 // @accept json
diff --git a/api/http/handler/teams/team_inspect.go b/api/http/handler/teams/team_inspect.go
index b4ac14a83..ba8229fd4 100644
--- a/api/http/handler/teams/team_inspect.go
+++ b/api/http/handler/teams/team_inspect.go
@@ -15,7 +15,7 @@ import (
 // @id TeamInspect
 // @summary Inspect a team
 // @description Retrieve details about a team. Access is only available for administrator and leaders of that team.
-// @description **Access policy**: restricted
+// @description **Access policy**: administrator
 // @tags teams
 // @security jwt
 // @produce json
diff --git a/api/http/handler/teams/team_update.go b/api/http/handler/teams/team_update.go
index 9ca8dd766..e73a00c74 100644
--- a/api/http/handler/teams/team_update.go
+++ b/api/http/handler/teams/team_update.go
@@ -23,7 +23,7 @@ func (payload *teamUpdatePayload) Validate(r *http.Request) error {
 // @summary Update a team
 // @description Update a team.
 // @description **Access policy**: administrator
-// @tags
+// @tags teams
 // @security jwt
 // @accept json
 // @produce json
diff --git a/api/http/handler/templates/template_file.go b/api/http/handler/templates/template_file.go
index 12f6b5b70..844e99e16 100644
--- a/api/http/handler/templates/template_file.go
+++ b/api/http/handler/templates/template_file.go
@@ -39,7 +39,7 @@ func (payload *filePayload) Validate(r *http.Request) error {
 // @id TemplateFile
 // @summary Get a template's file
 // @description Get a template's file
-// @description **Access policy**: restricted
+// @description **Access policy**: authenticated
 // @tags templates
 // @security jwt
 // @accept json
diff --git a/api/http/handler/templates/template_list.go b/api/http/handler/templates/template_list.go
index 62e3f48d7..57d8da452 100644
--- a/api/http/handler/templates/template_list.go
+++ b/api/http/handler/templates/template_list.go
@@ -17,7 +17,7 @@ type listResponse struct {
 // @id TemplateList
 // @summary List available templates
 // @description List available templates.
-// @description **Access policy**: restricted
+// @description **Access policy**: authenticated
 // @tags templates
 // @security jwt
 // @produce json
diff --git a/api/http/handler/users/admin_init.go b/api/http/handler/users/admin_init.go
index 184041cef..968063823 100644
--- a/api/http/handler/users/admin_init.go
+++ b/api/http/handler/users/admin_init.go
@@ -32,7 +32,7 @@ func (payload *adminInitPayload) Validate(r *http.Request) error {
 // @summary Initialize administrator account
 // @description Initialize the 'admin' user account.
 // @description **Access policy**: public
-// @tags
+// @tags users
 // @accept json
 // @produce json
 // @param body body adminInitPayload true "User details"
diff --git a/api/http/handler/users/user_delete.go b/api/http/handler/users/user_delete.go
index 488a94d7d..493421437 100644
--- a/api/http/handler/users/user_delete.go
+++ b/api/http/handler/users/user_delete.go
@@ -18,7 +18,6 @@ import (
 // @description **Access policy**: administrator
 // @tags users
 // @security jwt
-// @accept json
 // @produce json
 // @param id path int true "User identifier"
 // @success 204 "Success"
diff --git a/api/http/handler/users/user_inspect.go b/api/http/handler/users/user_inspect.go
index c6a25145e..61195d372 100644
--- a/api/http/handler/users/user_inspect.go
+++ b/api/http/handler/users/user_inspect.go
@@ -16,7 +16,7 @@ import (
 // @summary Inspect a user
 // @description Retrieve details about a user.
 // @description User passwords are filtered out, and should never be accessible.
-// @description **Access policy**: administrator
+// @description **Access policy**: authenticated
 // @tags users
 // @security jwt
 // @produce json
diff --git a/api/http/handler/users/user_memberships.go b/api/http/handler/users/user_memberships.go
index 3b1d38ca2..271c36e43 100644
--- a/api/http/handler/users/user_memberships.go
+++ b/api/http/handler/users/user_memberships.go
@@ -14,7 +14,7 @@ import (
 // @id UserMembershipsInspect
 // @summary Inspect a user memberships
 // @description Inspect a user memberships.
-// @description **Access policy**: authenticated
+// @description **Access policy**: restricted
 // @tags users
 // @security jwt
 // @produce json
diff --git a/api/http/handler/webhooks/webhook_create.go b/api/http/handler/webhooks/webhook_create.go
index f82f35651..746fcd6ed 100644
--- a/api/http/handler/webhooks/webhook_create.go
+++ b/api/http/handler/webhooks/webhook_create.go
@@ -33,7 +33,7 @@ func (payload *webhookCreatePayload) Validate(r *http.Request) error {
 }
 
 // @summary Create a webhook
-// @description
+// @description **Access policy**: authenticated
 // @security jwt
 // @tags webhooks
 // @accept json
diff --git a/api/http/handler/webhooks/webhook_delete.go b/api/http/handler/webhooks/webhook_delete.go
index 0cbaf944f..40c09e521 100644
--- a/api/http/handler/webhooks/webhook_delete.go
+++ b/api/http/handler/webhooks/webhook_delete.go
@@ -10,11 +10,9 @@ import (
 )
 
 // @summary Delete a webhook
-// @description
+// @description **Access policy**: authenticated
 // @security jwt
 // @tags webhooks
-// @accept json
-// @produce json
 // @param id path int true "Webhook id"
 // @success 202 "Webhook deleted"
 // @failure 400
diff --git a/api/http/handler/webhooks/webhook_execute.go b/api/http/handler/webhooks/webhook_execute.go
index 2fbc12772..300b2a6dc 100644
--- a/api/http/handler/webhooks/webhook_execute.go
+++ b/api/http/handler/webhooks/webhook_execute.go
@@ -16,9 +16,8 @@ import (
 
 // @summary Execute a webhook
 // @description Acts on a passed in token UUID to restart the docker service
+// @description **Access policy**: public
 // @tags webhooks
-// @accept json
-// @produce json
 // @param token path string true "Webhook token"
 // @success 202 "Webhook executed"
 // @failure 400
diff --git a/api/http/handler/webhooks/webhook_list.go b/api/http/handler/webhooks/webhook_list.go
index 4acfac728..e4c6b6558 100644
--- a/api/http/handler/webhooks/webhook_list.go
+++ b/api/http/handler/webhooks/webhook_list.go
@@ -15,7 +15,7 @@ type webhookListOperationFilters struct {
 }
 
 // @summary List webhooks
-// @description
+// @description **Access policy**: authenticated
 // @security jwt
 // @tags webhooks
 // @accept json
diff --git a/api/http/handler/websocket/attach.go b/api/http/handler/websocket/attach.go
index 102cb35dc..c41f85269 100644
--- a/api/http/handler/websocket/attach.go
+++ b/api/http/handler/websocket/attach.go
@@ -18,7 +18,7 @@ import (
 // @description If the nodeName query parameter is present, the request will be proxied to the underlying agent environment(endpoint).
 // @description If the nodeName query parameter is not specified, the request will be upgraded to the websocket protocol and
 // @description an AttachStart operation HTTP request will be created and hijacked.
-// @description Authentication and access is controlled via the mandatory token query parameter.
+// @description **Access policy**: authenticated
 // @security jwt
 // @tags websocket
 // @accept json
diff --git a/api/http/handler/websocket/exec.go b/api/http/handler/websocket/exec.go
index 023af618e..544b60cd2 100644
--- a/api/http/handler/websocket/exec.go
+++ b/api/http/handler/websocket/exec.go
@@ -26,7 +26,7 @@ type execStartOperationPayload struct {
 // @description If the nodeName query parameter is present, the request will be proxied to the underlying agent environment(endpoint).
 // @description If the nodeName query parameter is not specified, the request will be upgraded to the websocket protocol and
 // @description an ExecStart operation HTTP request will be created and hijacked.
-// @description Authentication and access is controlled via the mandatory token query parameter.
+// @**Access policy**: authenticated
 // @security jwt
 // @tags websocket
 // @accept json
diff --git a/api/http/handler/websocket/pod.go b/api/http/handler/websocket/pod.go
index 5b0022773..5e2bb6952 100644
--- a/api/http/handler/websocket/pod.go
+++ b/api/http/handler/websocket/pod.go
@@ -19,7 +19,7 @@ import (
 
 // @summary Execute a websocket on pod
 // @description The request will be upgraded to the websocket protocol.
-// @description Authentication and access is controlled via the mandatory token query parameter.
+// @description **Access policy**: authenticated
 // @security jwt
 // @tags websocket
 // @accept json
diff --git a/api/http/handler/websocket/shell_pod.go b/api/http/handler/websocket/shell_pod.go
index 4249a350d..97d876784 100644
--- a/api/http/handler/websocket/shell_pod.go
+++ b/api/http/handler/websocket/shell_pod.go
@@ -19,11 +19,10 @@ import (
 // @produce json
 // @param endpointId query int true "environment(endpoint) ID of the environment(endpoint) where the resource is located"
 // @param token query string true "JWT token used for authentication against this environment(endpoint)"
-// @success 200
-// @failure 400
-// @failure 403
-// @failure 404
-// @failure 500
+// @success 200 "Success"
+// @failure 400 "Invalid request"
+// @failure 403 "Permission denied"
+// @failure 500 "Server error"
 // @router /websocket/kubernetes-shell [get]
 func (handler *Handler) websocketShellPodExec(w http.ResponseWriter, r *http.Request) *httperror.HandlerError {
 	endpointID, err := request.RetrieveNumericQueryParameter(r, "endpointId", false)