@desplega.ai/agent-swarm 1.173.0 → 2.0.0

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.173.0",
+    "version": "2.0.0",
     "description": "Multi-agent orchestration API for Claude Code, Codex, and Gemini CLI. Enables task distribution, agent communication, and service discovery.\n\nMCP tools are documented separately in [MCP.md](./MCP.md)."
   },
   "servers": [
@@ -172,7 +172,8 @@
               "workflow",
               "linear",
               "jira",
-              "comb"
+              "comb",
+              "chat"
             ],
             "default": "mcp"
           },
@@ -375,6 +376,17 @@
           "modelAlias": {
             "type": "string"
           },
+          "resolvedEffort": {
+            "type": "string",
+            "enum": [
+              "off",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          },
           "scheduleId": {
             "type": "string"
           },
@@ -1399,6 +1411,9 @@
           },
           "encrypted": {
             "type": "boolean"
+          },
+          "exportToEnv": {
+            "type": "boolean"
           }
         },
         "required": [
@@ -1412,7 +1427,8 @@
           "description",
           "createdAt",
           "lastUpdatedAt",
-          "encrypted"
+          "encrypted",
+          "exportToEnv"
         ]
       },
       "ContextSnapshot": {
@@ -2923,7 +2939,8 @@
               "mcp",
               "script",
               "slack",
-              "api"
+              "api",
+              "chat"
             ]
           },
           "senderLabel": {
@@ -3044,6 +3061,20 @@
           "createdAt"
         ]
       },
+      "UserCommsPrefs": {
+        "type": "object",
+        "properties": {
+          "tone": {
+            "type": "string"
+          },
+          "language": {
+            "type": "string"
+          },
+          "verbosity": {
+            "type": "string"
+          }
+        }
+      },
       "Page": {
         "type": "object",
         "properties": {
@@ -3330,20 +3361,6 @@
           "changeReason"
         ]
       },
-      "UserCommsPrefs": {
-        "type": "object",
-        "properties": {
-          "tone": {
-            "type": "string"
-          },
-          "language": {
-            "type": "string"
-          },
-          "verbosity": {
-            "type": "string"
-          }
-        }
-      },
       "BudgetRefusedTrigger": {
         "type": "object",
         "properties": {
@@ -4415,93 +4432,6 @@
           "installedAt"
         ]
       },
-      "Service": {
-        "type": "object",
-        "properties": {
-          "id": {
-            "type": "string",
-            "format": "uuid"
-          },
-          "agentId": {
-            "type": "string"
-          },
-          "name": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 50
-          },
-          "port": {
-            "type": "integer",
-            "minimum": 1,
-            "maximum": 65535,
-            "default": 3000
-          },
-          "description": {
-            "type": "string"
-          },
-          "url": {
-            "type": "string",
-            "format": "uri"
-          },
-          "healthCheckPath": {
-            "type": "string",
-            "default": "/health"
-          },
-          "status": {
-            "type": "string",
-            "enum": [
-              "starting",
-              "healthy",
-              "unhealthy",
-              "stopped"
-            ],
-            "default": "starting"
-          },
-          "script": {
-            "type": "string",
-            "minLength": 1
-          },
-          "cwd": {
-            "type": "string"
-          },
-          "interpreter": {
-            "type": "string"
-          },
-          "args": {
-            "type": "array",
-            "items": {
-              "type": "string"
-            }
-          },
-          "env": {
-            "type": "object",
-            "additionalProperties": {
-              "type": "string"
-            }
-          },
-          "metadata": {
-            "type": "object",
-            "additionalProperties": {},
-            "default": {}
-          },
-          "createdAt": {
-            "type": "string",
-            "format": "date-time"
-          },
-          "lastUpdatedAt": {
-            "type": "string",
-            "format": "date-time"
-          }
-        },
-        "required": [
-          "id",
-          "agentId",
-          "name",
-          "script",
-          "createdAt",
-          "lastUpdatedAt"
-        ]
-      },
       "TaskTemplate": {
         "type": "object",
         "properties": {
@@ -10255,7 +10185,6 @@
                               "prompt-templates",
                               "mcp",
                               "profiles",
-                              "services",
                               "scheduling",
                               "memory",
                               "workflows",
@@ -10269,6 +10198,7 @@
                               "repo",
                               "agentmail",
                               "kapso",
+                              "chat-sdk",
                               "swarm-x"
                             ]
                           }
@@ -10318,7 +10248,6 @@
                               "prompt-templates",
                               "mcp",
                               "profiles",
-                              "services",
                               "scheduling",
                               "memory",
                               "workflows",
@@ -10332,6 +10261,7 @@
                               "repo",
                               "agentmail",
                               "kapso",
+                              "chat-sdk",
                               "swarm-x"
                             ]
                           }
@@ -15734,6 +15664,10 @@
                       "string",
                       "null"
                     ]
+                  },
+                  "exportToEnv": {
+                    "type": "boolean",
+                    "description": "Export this row into agent process env (default true on create, false for a few server-side secrets; omitted on update keeps the stored flag). Rejected as true for keys only the API server reads."
                   }
                 },
                 "required": [
@@ -16674,71 +16608,97 @@
         }
       }
     },
-    "/ecosystem": {
-      "get": {
-        "summary": "Get PM2 ecosystem config for agent services",
+    "/api/keys/report-usage": {
+      "post": {
+        "summary": "Record which API key was used for a task",
         "tags": [
-          "Ecosystem"
+          "API Keys"
         ],
         "security": [
           {
             "bearerAuth": []
           }
         ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "keyType": {
+                    "type": "string"
+                  },
+                  "keySuffix": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 10
+                  },
+                  "keyIndex": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "taskId": {
+                    "type": "string",
+                    "format": "uuid"
+                  },
+                  "scope": {
+                    "type": "string"
+                  },
+                  "scopeId": {
+                    "type": "string"
+                  },
+                  "plan": {
+                    "type": "string",
+                    "maxLength": 40
+                  }
+                },
+                "required": [
+                  "keyType",
+                  "keySuffix",
+                  "keyIndex"
+                ]
+              }
+            }
+          }
+        },
         "responses": {
           "200": {
-            "description": "PM2 ecosystem config",
+            "description": "Usage recorded",
             "content": {
               "application/json": {
                 "schema": {
                   "type": "object",
                   "properties": {
-                    "apps": {
-                      "type": "array",
-                      "items": {
-                        "type": "object",
-                        "properties": {
-                          "name": {
-                            "type": "string"
-                          },
-                          "script": {
-                            "type": "string"
-                          },
-                          "cwd": {
-                            "type": "string"
-                          },
-                          "interpreter": {
-                            "type": "string"
-                          },
-                          "args": {
-                            "type": "array",
-                            "items": {
-                              "type": "string"
-                            }
-                          },
-                          "env": {
-                            "type": "object",
-                            "additionalProperties": {
-                              "type": "string"
-                            }
-                          }
-                        },
-                        "required": [
-                          "name",
-                          "script"
-                        ]
-                      }
+                    "success": {
+                      "type": "boolean",
+                      "enum": [
+                        true
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
                     }
                   },
                   "required": [
-                    "apps"
+                    "success",
+                    "message"
                   ]
                 }
               }
             }
           },
           "400": {
-            "description": "Missing X-Agent-ID",
+            "description": "Validation error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized",
             "content": {
               "application/json": {
                 "schema": {
@@ -16750,9 +16710,9 @@
         }
       }
     },
-    "/api/keys/report-usage": {
+    "/api/keys/report-rate-limit": {
       "post": {
-        "summary": "Record which API key was used for a task",
+        "summary": "Mark an API key as rate-limited",
         "tags": [
           "API Keys"
         ],
@@ -16779,25 +16739,22 @@
                     "type": "integer",
                     "minimum": 0
                   },
-                  "taskId": {
+                  "rateLimitedUntil": {
                     "type": "string",
-                    "format": "uuid"
+                    "format": "date-time"
                   },
                   "scope": {
                     "type": "string"
                   },
                   "scopeId": {
                     "type": "string"
-                  },
-                  "plan": {
-                    "type": "string",
-                    "maxLength": 40
                   }
                 },
                 "required": [
                   "keyType",
                   "keySuffix",
-                  "keyIndex"
+                  "keyIndex",
+                  "rateLimitedUntil"
                 ]
               }
             }
@@ -16805,7 +16762,7 @@
         },
         "responses": {
           "200": {
-            "description": "Usage recorded",
+            "description": "Key marked as rate-limited",
             "content": {
               "application/json": {
                 "schema": {
@@ -16852,9 +16809,9 @@
         }
       }
     },
-    "/api/keys/report-rate-limit": {
+    "/api/keys/report-auth-failure": {
       "post": {
-        "summary": "Mark an API key as rate-limited",
+        "summary": "Record an auth failure for a pooled key; bench it after 2 in a row",
         "tags": [
           "API Keys"
         ],
@@ -16881,9 +16838,9 @@
                     "type": "integer",
                     "minimum": 0
                   },
-                  "rateLimitedUntil": {
+                  "taskId": {
                     "type": "string",
-                    "format": "date-time"
+                    "format": "uuid"
                   },
                   "scope": {
                     "type": "string"
@@ -16895,8 +16852,7 @@
                 "required": [
                   "keyType",
                   "keySuffix",
-                  "keyIndex",
-                  "rateLimitedUntil"
+                  "keyIndex"
                 ]
               }
             }
@@ -16904,7 +16860,7 @@
         },
         "responses": {
           "200": {
-            "description": "Key marked as rate-limited",
+            "description": "Failure recorded",
             "content": {
               "application/json": {
                 "schema": {
@@ -16916,122 +16872,24 @@
                         true
                       ]
                     },
-                    "message": {
-                      "type": "string"
+                    "consecutiveAuthFailures": {
+                      "type": "integer"
+                    },
+                    "benched": {
+                      "type": "boolean"
+                    },
+                    "rateLimitedUntil": {
+                      "type": [
+                        "string",
+                        "null"
+                      ]
                     }
                   },
                   "required": [
                     "success",
-                    "message"
-                  ]
-                }
-              }
-            }
-          },
-          "400": {
-            "description": "Validation error",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ErrorResponse"
-                }
-              }
-            }
-          },
-          "401": {
-            "description": "Unauthorized",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ErrorResponse"
-                }
-              }
-            }
-          }
-        }
-      }
-    },
-    "/api/keys/report-auth-failure": {
-      "post": {
-        "summary": "Record an auth failure for a pooled key; bench it after 2 in a row",
-        "tags": [
-          "API Keys"
-        ],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "type": "object",
-                "properties": {
-                  "keyType": {
-                    "type": "string"
-                  },
-                  "keySuffix": {
-                    "type": "string",
-                    "minLength": 1,
-                    "maxLength": 10
-                  },
-                  "keyIndex": {
-                    "type": "integer",
-                    "minimum": 0
-                  },
-                  "taskId": {
-                    "type": "string",
-                    "format": "uuid"
-                  },
-                  "scope": {
-                    "type": "string"
-                  },
-                  "scopeId": {
-                    "type": "string"
-                  }
-                },
-                "required": [
-                  "keyType",
-                  "keySuffix",
-                  "keyIndex"
-                ]
-              }
-            }
-          }
-        },
-        "responses": {
-          "200": {
-            "description": "Failure recorded",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "type": "object",
-                  "properties": {
-                    "success": {
-                      "type": "boolean",
-                      "enum": [
-                        true
-                      ]
-                    },
-                    "consecutiveAuthFailures": {
-                      "type": "integer"
-                    },
-                    "benched": {
-                      "type": "boolean"
-                    },
-                    "rateLimitedUntil": {
-                      "type": [
-                        "string",
-                        "null"
-                      ]
-                    }
-                  },
-                  "required": [
-                    "success",
-                    "consecutiveAuthFailures",
-                    "benched",
-                    "rateLimitedUntil"
+                    "consecutiveAuthFailures",
+                    "benched",
+                    "rateLimitedUntil"
                   ]
                 }
               }
@@ -21106,6 +20964,247 @@
         }
       }
     },
+    "/api/integrations/chat/status": {
+      "get": {
+        "summary": "Chat SDK channel status: enabled flag, Slack clash, per-adapter health and webhook URL.",
+        "tags": [
+          "Integrations"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Per-adapter status. `health` is `disabled` for an adapter that is not running. Never contains secret values.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "enabled": {
+                      "type": "boolean"
+                    },
+                    "slackClash": {
+                      "type": "boolean"
+                    },
+                    "error": {
+                      "type": "string"
+                    },
+                    "adapters": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "name": {
+                            "type": "string",
+                            "enum": [
+                              "telegram",
+                              "slack",
+                              "discord",
+                              "teams"
+                            ]
+                          },
+                          "configured": {
+                            "type": "boolean"
+                          },
+                          "enabled": {
+                            "type": "boolean"
+                          },
+                          "health": {
+                            "type": "string",
+                            "enum": [
+                              "ok",
+                              "error",
+                              "disabled",
+                              "incomplete"
+                            ]
+                          },
+                          "error": {
+                            "type": "string"
+                          },
+                          "webhookUrl": {
+                            "type": "string"
+                          },
+                          "mode": {
+                            "type": "string"
+                          },
+                          "gateway": {
+                            "type": "object",
+                            "properties": {
+                              "state": {
+                                "type": "string",
+                                "enum": [
+                                  "running",
+                                  "backoff",
+                                  "stopped"
+                                ]
+                              },
+                              "since": {
+                                "type": "string"
+                              },
+                              "restarts": {
+                                "type": "number"
+                              }
+                            },
+                            "required": [
+                              "state",
+                              "since",
+                              "restarts"
+                            ]
+                          },
+                          "guilds": {
+                            "type": "object",
+                            "properties": {
+                              "count": {
+                                "type": "number"
+                              },
+                              "names": {
+                                "type": "array",
+                                "items": {
+                                  "type": "string"
+                                }
+                              }
+                            },
+                            "required": [
+                              "count",
+                              "names"
+                            ]
+                          }
+                        },
+                        "required": [
+                          "name",
+                          "configured",
+                          "enabled",
+                          "health",
+                          "webhookUrl"
+                        ]
+                      }
+                    }
+                  },
+                  "required": [
+                    "enabled",
+                    "slackClash",
+                    "adapters"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/integrations/chat/telegram/register-webhook": {
+      "post": {
+        "summary": "Register this swarm's public Telegram webhook URL and secret token with the Bot API (setWebhook), then return getWebhookInfo.",
+        "tags": [
+          "Integrations"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {}
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Webhook registered",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "webhookUrl": {
+                      "type": "string"
+                    },
+                    "webhookInfo": {
+                      "type": "object",
+                      "properties": {
+                        "url": {
+                          "type": "string"
+                        },
+                        "has_custom_certificate": {
+                          "type": "boolean"
+                        },
+                        "pending_update_count": {
+                          "type": "number"
+                        },
+                        "last_error_date": {
+                          "type": "number"
+                        },
+                        "last_error_message": {
+                          "type": "string"
+                        },
+                        "max_connections": {
+                          "type": "number"
+                        },
+                        "ip_address": {
+                          "type": "string"
+                        },
+                        "allowed_updates": {
+                          "type": "array",
+                          "items": {
+                            "type": "string"
+                          }
+                        }
+                      },
+                      "required": [
+                        "url"
+                      ],
+                      "additionalProperties": {}
+                    }
+                  },
+                  "required": [
+                    "webhookUrl",
+                    "webhookInfo"
+                  ]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Telegram is not configured for webhook mode",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Only the lead agent or a dashboard user can register the webhook",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "502": {
+            "description": "The Telegram Bot API rejected the call",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/kv/{key}": {
       "get": {
         "summary": "Get a KV entry by key (namespace resolved from request headers)",
@@ -29856,7 +29955,8 @@
                                   "workflow",
                                   "linear",
                                   "jira",
-                                  "comb"
+                                  "comb",
+                                  "chat"
                                 ],
                                 "default": "mcp"
                               },
@@ -29929,6 +30029,17 @@
                                   "max"
                                 ]
                               },
+                              "resolvedEffort": {
+                                "type": "string",
+                                "enum": [
+                                  "off",
+                                  "low",
+                                  "medium",
+                                  "high",
+                                  "xhigh",
+                                  "max"
+                                ]
+                              },
                               "provider": {
                                 "type": "string",
                                 "enum": [
@@ -30170,7 +30281,8 @@
                       "workflow",
                       "linear",
                       "jira",
-                      "comb"
+                      "comb",
+                      "chat"
                     ]
                   },
                   "outputSchema": {
@@ -30242,6 +30354,16 @@
               }
             }
           },
+          "403": {
+            "description": "An agent caller names a parentTaskId it neither owns nor created, or a non-lead agent binds the task to a chat thread",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
           "422": {
             "description": "Task creation blocked by an extension",
             "content": {
@@ -30426,6 +30548,21 @@
                       "model": {
                         "type": "string"
                       },
+                      "effort": {
+                        "type": [
+                          "string",
+                          "null"
+                        ],
+                        "enum": [
+                          "off",
+                          "low",
+                          "medium",
+                          "high",
+                          "xhigh",
+                          "max",
+                          null
+                        ]
+                      },
                       "providerMeta": {
                         "type": "object",
                         "properties": {
@@ -30613,7 +30750,8 @@
                       "mcp",
                       "script",
                       "slack",
-                      "api"
+                      "api",
+                      "chat"
                     ]
                   },
                   "requestedByUserId": {
@@ -31530,6 +31668,33 @@
                                 "items": {
                                   "$ref": "#/components/schemas/TaskAttachment"
                                 }
+                              },
+                              "requestedBy": {
+                                "type": "object",
+                                "properties": {
+                                  "id": {
+                                    "type": "string"
+                                  },
+                                  "name": {
+                                    "type": "string",
+                                    "minLength": 1
+                                  },
+                                  "email": {
+                                    "type": "string"
+                                  },
+                                  "role": {
+                                    "type": "string"
+                                  },
+                                  "notes": {
+                                    "type": "string"
+                                  },
+                                  "comms": {
+                                    "$ref": "#/components/schemas/UserCommsPrefs"
+                                  }
+                                },
+                                "required": [
+                                  "name"
+                                ]
                               }
                             },
                             "required": [
@@ -46110,7 +46275,8 @@
                                       "workflow",
                                       "linear",
                                       "jira",
-                                      "comb"
+                                      "comb",
+                                      "chat"
                                     ],
                                     "default": "mcp"
                                   },
@@ -51429,68 +51595,6 @@
         }
       }
     },
-    "/api/services": {
-      "get": {
-        "summary": "List all registered services",
-        "tags": [
-          "Stats"
-        ],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ],
-        "parameters": [
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": false,
-            "name": "status",
-            "in": "query"
-          },
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": false,
-            "name": "agentId",
-            "in": "query"
-          },
-          {
-            "schema": {
-              "type": "string"
-            },
-            "required": false,
-            "name": "name",
-            "in": "query"
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Service list",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "type": "object",
-                  "properties": {
-                    "services": {
-                      "type": "array",
-                      "items": {
-                        "$ref": "#/components/schemas/Service"
-                      }
-                    }
-                  },
-                  "required": [
-                    "services"
-                  ]
-                }
-              }
-            }
-          }
-        }
-      }
-    },
     "/api/scheduled-tasks": {
       "get": {
         "summary": "List scheduled tasks",
@@ -56515,6 +56619,81 @@
         }
       }
     },
+    "/api/integrations/chat/{adapter}/webhook": {
+      "post": {
+        "summary": "Handle Chat SDK platform webhooks (Telegram, Slack, Discord, Teams)",
+        "tags": [
+          "Webhooks"
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "description": "Chat SDK adapter name, e.g. telegram"
+            },
+            "required": true,
+            "description": "Chat SDK adapter name, e.g. telegram",
+            "name": "adapter",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Adapter response"
+          },
+          "401": {
+            "description": "Invalid platform signature or secret token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Teams activity whose serviceUrl is not a Bot Framework host",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Chat SDK disabled or adapter not configured",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "413": {
+            "description": "Body exceeds 1 MiB",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Adapter configured but failed to start",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/workflow-runs/{runId}/events": {
       "post": {
         "summary": "Fire a run-scoped event signal",