@1claw/openapi-spec 0.44.0 → 0.44.3

package/openapi.json

@@ -158,6 +158,10 @@
     {
       "name": "Agent Channels",
       "description": "External messaging channels (Telegram, WhatsApp, Discord)"
+    },
+    {
+      "name": "OAuth Connect",
+      "description": "OAuth connected accounts for agents (provider registry, connect flows, app credentials)"
     }
   ],
   "paths": {
@@ -12080,6 +12084,66 @@
         }
       }
     },
+    "/v1/agents/org-directory": {
+      "get": {
+        "tags": [
+          "agents",
+          "discovery"
+        ],
+        "summary": "List org agents",
+        "description": "List agents within the caller's organization for sub-agent discovery.\nReturns agents with their capabilities, enabling agent-to-agent\ncoordination and discovery within an org. Requires authentication.\n",
+        "operationId": "listOrgDirectory",
+        "parameters": [
+          {
+            "name": "q",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            },
+            "description": "Search query to filter agents by name or description"
+          },
+          {
+            "name": "tags",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            },
+            "description": "Comma-separated tag filter"
+          },
+          {
+            "name": "page",
+            "in": "query",
+            "schema": {
+              "type": "integer",
+              "default": 1
+            }
+          },
+          {
+            "name": "page_size",
+            "in": "query",
+            "schema": {
+              "type": "integer",
+              "default": 20
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Org agent directory listing",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/OrgDirectoryResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          }
+        }
+      }
+    },
     "/v1/agents/{agent_id}/discovery": {
       "patch": {
         "tags": [
@@ -12180,7 +12244,7 @@
           "Agent Chat"
         ],
         "summary": "Send chat message",
-        "description": "Send a message to an agent and receive a response via Shroud LLM.\nSupports SSE streaming when Accept: text/event-stream is set.\n",
+        "description": "Send a message to an agent and receive a response via Shroud LLM.\nSupports SSE streaming when Accept: text/event-stream is set.\n\nAgents can call this endpoint on other agents within the same\norganization for inter-agent communication (agent-to-agent chat).\nThe caller must be authenticated and belong to the same org as\nthe target agent.\n",
         "operationId": "sendChatMessage",
         "parameters": [
           {
@@ -12818,142 +12882,427 @@
           }
         }
       }
-    }
-  },
-  "components": {
-    "securitySchemes": {
-      "BearerAuth": {
-        "type": "http",
-        "scheme": "bearer",
-        "bearerFormat": "JWT"
-      },
-      "ApiKeyAuth": {
-        "type": "http",
-        "scheme": "bearer",
-        "description": "1ck_ prefixed API key used as Bearer token"
-      }
     },
-    "parameters": {
-      "VaultId": {
-        "name": "vault_id",
-        "in": "path",
-        "required": true,
-        "schema": {
-          "type": "string",
-          "format": "uuid"
-        }
-      },
-      "SecretPath": {
-        "name": "path",
-        "in": "path",
-        "required": true,
-        "schema": {
-          "type": "string"
-        },
-        "description": "Secret path (e.g. \"db/credentials\")"
-      },
-      "AgentId": {
-        "name": "agent_id",
-        "in": "path",
-        "required": true,
-        "schema": {
-          "type": "string",
-          "format": "uuid"
-        }
-      },
-      "PolicyId": {
-        "name": "policy_id",
-        "in": "path",
-        "required": true,
-        "schema": {
-          "type": "string",
-          "format": "uuid"
-        }
-      },
-      "CardId": {
-        "name": "card_id",
-        "in": "path",
-        "required": true,
-        "schema": {
-          "type": "string",
-          "format": "uuid"
-        }
-      },
-      "IncludeSignedTx": {
-        "name": "include_signed_tx",
-        "in": "query",
-        "required": false,
-        "description": "Set to `true` or `1` to include the raw signed transaction hex in the response. Omitted by default to reduce key exfiltration risk. Only the literal values \"true\" or \"1\" enable inclusion; any other value or omission returns responses without signed_tx. Applies to GET /v1/agents/{agent_id}/transactions and GET /v1/agents/{agent_id}/transactions/{tx_id}.\n",
-        "schema": {
-          "type": "boolean",
-          "default": false,
-          "example": false
+    "/v1/oauth/providers": {
+      "get": {
+        "tags": [
+          "OAuth Connect"
+        ],
+        "summary": "List OAuth providers",
+        "description": "Returns the list of supported OAuth providers with their metadata,\navailable scopes, and authorization URLs. No authentication required.\n",
+        "operationId": "listOAuthProviders",
+        "security": [],
+        "responses": {
+          "200": {
+            "description": "Provider list",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/OAuthProviderListResponse"
+                }
+              }
+            }
+          }
         }
       }
     },
-    "responses": {
-      "BadRequest": {
-        "description": "Invalid request",
-        "content": {
-          "application/json": {
-            "schema": {
-              "$ref": "#/components/schemas/ProblemDetails"
-            }
+    "/v1/agents/{agent_id}/oauth/connect": {
+      "post": {
+        "tags": [
+          "OAuth Connect"
+        ],
+        "summary": "Initiate OAuth connection",
+        "description": "Start an OAuth authorization flow for the specified agent and provider.\nReturns the authorization URL to redirect the user to. Human-only.\n",
+        "operationId": "connectOAuth",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
           }
-        }
-      },
-      "Unauthorized": {
-        "description": "Authentication required or invalid",
-        "content": {
-          "application/json": {
-            "schema": {
-              "$ref": "#/components/schemas/ProblemDetails"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ConnectOAuthRequest"
+              }
             }
           }
-        }
-      },
-      "Forbidden": {
-        "description": "Insufficient permissions",
-        "content": {
-          "application/json": {
-            "schema": {
-              "$ref": "#/components/schemas/ProblemDetails"
+        },
+        "responses": {
+          "200": {
+            "description": "Authorization URL generated",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ConnectOAuthResponse"
+                }
+              }
             }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
           }
         }
-      },
-      "NotFound": {
-        "description": "Resource not found",
-        "content": {
-          "application/json": {
-            "schema": {
-              "$ref": "#/components/schemas/ProblemDetails"
-            }
+      }
+    },
+    "/v1/agents/{agent_id}/oauth/connections": {
+      "get": {
+        "tags": [
+          "OAuth Connect"
+        ],
+        "summary": "List OAuth connections",
+        "description": "List all active OAuth connections for the specified agent.",
+        "operationId": "listOAuthConnections",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
           }
-        }
-      },
-      "PaymentRequired": {
-        "description": "x402 payment required",
-        "content": {
-          "application/json": {
-            "schema": {
-              "$ref": "#/components/schemas/PaymentRequirement"
+        ],
+        "responses": {
+          "200": {
+            "description": "Connection list",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/OAuthConnectionListResponse"
+                }
+              }
             }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
           }
         }
-      },
-      "Conflict": {
-        "description": "Resource already exists or conflict",
-        "content": {
-          "application/json": {
+      }
+    },
+    "/v1/agents/{agent_id}/oauth/disconnect/{binding_id}": {
+      "post": {
+        "tags": [
+          "OAuth Connect"
+        ],
+        "summary": "Disconnect OAuth connection",
+        "description": "Disconnect an OAuth connection by revoking tokens and removing the binding.\nHuman-only.\n",
+        "operationId": "disconnectOAuth",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          },
+          {
+            "name": "binding_id",
+            "in": "path",
+            "required": true,
             "schema": {
-              "$ref": "#/components/schemas/ProblemDetails"
+              "type": "string",
+              "format": "uuid"
             }
           }
+        ],
+        "responses": {
+          "204": {
+            "description": "Connection disconnected"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
         }
       }
     },
-    "schemas": {
+    "/v1/agents/{agent_id}/oauth/app-credentials": {
+      "post": {
+        "tags": [
+          "OAuth Connect"
+        ],
+        "summary": "Save OAuth app credentials",
+        "description": "Store custom OAuth app credentials (client ID/secret) for a provider.\nAllows the agent to use a BYOA (Bring Your Own App) OAuth application\ninstead of 1Claw's shared credentials. Human-only.\n",
+        "operationId": "saveOAuthAppCredentials",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SaveOAuthAppCredentialsRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Credentials saved",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/OAuthAppCredentialResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      },
+      "get": {
+        "tags": [
+          "OAuth Connect"
+        ],
+        "summary": "List OAuth app credentials",
+        "description": "List stored OAuth app credentials for the agent. Client secrets\nare never returned in the response.\n",
+        "operationId": "listOAuthAppCredentials",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Credential list",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/OAuthAppCredentialListResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}/oauth/app-credentials/{provider_slug}": {
+      "delete": {
+        "tags": [
+          "OAuth Connect"
+        ],
+        "summary": "Delete OAuth app credentials",
+        "description": "Remove stored OAuth app credentials for a specific provider. Human-only.\n",
+        "operationId": "deleteOAuthAppCredentials",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          },
+          {
+            "name": "provider_slug",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Provider identifier (e.g. \"github\", \"google\", \"slack\")"
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Credentials deleted"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/oauth/callback": {
+      "get": {
+        "tags": [
+          "OAuth Connect"
+        ],
+        "summary": "OAuth callback",
+        "description": "Public callback URL that OAuth providers redirect to after user authorization.\nExchanges the authorization code for tokens and redirects to the dashboard.\n",
+        "operationId": "oauthConnectCallback",
+        "security": [],
+        "parameters": [
+          {
+            "name": "code",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            },
+            "description": "Authorization code from the OAuth provider"
+          },
+          {
+            "name": "state",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            },
+            "description": "Opaque state parameter for CSRF protection and session binding"
+          },
+          {
+            "name": "error",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            },
+            "description": "Error code if the authorization was denied or failed"
+          }
+        ],
+        "responses": {
+          "302": {
+            "description": "Redirect to dashboard with success or error status"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "BearerAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "bearerFormat": "JWT"
+      },
+      "ApiKeyAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "description": "1ck_ prefixed API key used as Bearer token"
+      }
+    },
+    "parameters": {
+      "VaultId": {
+        "name": "vault_id",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string",
+          "format": "uuid"
+        }
+      },
+      "SecretPath": {
+        "name": "path",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string"
+        },
+        "description": "Secret path (e.g. \"db/credentials\")"
+      },
+      "AgentId": {
+        "name": "agent_id",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string",
+          "format": "uuid"
+        }
+      },
+      "PolicyId": {
+        "name": "policy_id",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string",
+          "format": "uuid"
+        }
+      },
+      "CardId": {
+        "name": "card_id",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string",
+          "format": "uuid"
+        }
+      },
+      "IncludeSignedTx": {
+        "name": "include_signed_tx",
+        "in": "query",
+        "required": false,
+        "description": "Set to `true` or `1` to include the raw signed transaction hex in the response. Omitted by default to reduce key exfiltration risk. Only the literal values \"true\" or \"1\" enable inclusion; any other value or omission returns responses without signed_tx. Applies to GET /v1/agents/{agent_id}/transactions and GET /v1/agents/{agent_id}/transactions/{tx_id}.\n",
+        "schema": {
+          "type": "boolean",
+          "default": false,
+          "example": false
+        }
+      }
+    },
+    "responses": {
+      "BadRequest": {
+        "description": "Invalid request",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ProblemDetails"
+            }
+          }
+        }
+      },
+      "Unauthorized": {
+        "description": "Authentication required or invalid",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ProblemDetails"
+            }
+          }
+        }
+      },
+      "Forbidden": {
+        "description": "Insufficient permissions",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ProblemDetails"
+            }
+          }
+        }
+      },
+      "NotFound": {
+        "description": "Resource not found",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ProblemDetails"
+            }
+          }
+        }
+      },
+      "PaymentRequired": {
+        "description": "x402 payment required",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/PaymentRequirement"
+            }
+          }
+        }
+      },
+      "Conflict": {
+        "description": "Resource already exists or conflict",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ProblemDetails"
+            }
+          }
+        }
+      }
+    },
+    "schemas": {
       "OrderCardRequest": {
         "type": "object",
         "required": [
@@ -21762,6 +22111,82 @@
           }
         }
       },
+      "OrgDirectoryAgent": {
+        "type": "object",
+        "required": [
+          "id",
+          "name",
+          "intents_api_enabled",
+          "execution_intents_enabled",
+          "memory_enabled",
+          "shroud_enabled"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "name": {
+            "type": "string"
+          },
+          "public_description": {
+            "type": "string",
+            "nullable": true
+          },
+          "public_tags": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "a2a_url": {
+            "type": "string",
+            "nullable": true
+          },
+          "mcp_url": {
+            "type": "string",
+            "nullable": true
+          },
+          "intents_api_enabled": {
+            "type": "boolean"
+          },
+          "execution_intents_enabled": {
+            "type": "boolean"
+          },
+          "memory_enabled": {
+            "type": "boolean"
+          },
+          "shroud_enabled": {
+            "type": "boolean"
+          }
+        }
+      },
+      "OrgDirectoryResponse": {
+        "type": "object",
+        "required": [
+          "agents",
+          "total",
+          "page",
+          "page_size"
+        ],
+        "properties": {
+          "agents": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/OrgDirectoryAgent"
+            }
+          },
+          "total": {
+            "type": "integer"
+          },
+          "page": {
+            "type": "integer"
+          },
+          "page_size": {
+            "type": "integer"
+          }
+        }
+      },
       "UpdateDiscoveryRequest": {
         "type": "object",
         "properties": {
@@ -22085,6 +22510,231 @@
             }
           }
         }
+      },
+      "OAuthProviderScope": {
+        "type": "object",
+        "properties": {
+          "scope": {
+            "type": "string"
+          },
+          "label": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "default": {
+            "type": "boolean"
+          }
+        }
+      },
+      "OAuthProvider": {
+        "type": "object",
+        "properties": {
+          "slug": {
+            "type": "string",
+            "description": "Unique provider identifier (e.g. \"github\", \"google\", \"slack\")"
+          },
+          "display_name": {
+            "type": "string"
+          },
+          "icon_url": {
+            "type": "string",
+            "format": "uri"
+          },
+          "authorization_url": {
+            "type": "string",
+            "format": "uri"
+          },
+          "token_url": {
+            "type": "string",
+            "format": "uri"
+          },
+          "scopes_available": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/OAuthProviderScope"
+            }
+          },
+          "default_scopes": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "extra_auth_params": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "nullable": true
+          },
+          "requires_app_credentials": {
+            "type": "boolean",
+            "description": "Whether custom app credentials are required (vs. shared 1Claw app)"
+          },
+          "documentation_url": {
+            "type": "string",
+            "format": "uri",
+            "nullable": true
+          }
+        }
+      },
+      "OAuthProviderListResponse": {
+        "type": "object",
+        "properties": {
+          "providers": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/OAuthProvider"
+            }
+          }
+        }
+      },
+      "ConnectOAuthRequest": {
+        "type": "object",
+        "required": [
+          "provider_slug"
+        ],
+        "properties": {
+          "provider_slug": {
+            "type": "string",
+            "description": "Provider to connect (e.g. \"github\", \"google\", \"slack\")"
+          },
+          "scopes": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Override default scopes for this connection"
+          },
+          "redirect_after": {
+            "type": "string",
+            "description": "URL to redirect to after the OAuth flow completes"
+          }
+        }
+      },
+      "ConnectOAuthResponse": {
+        "type": "object",
+        "properties": {
+          "authorization_url": {
+            "type": "string",
+            "format": "uri",
+            "description": "Redirect the user to this URL to authorize the connection"
+          }
+        }
+      },
+      "OAuthConnectionResponse": {
+        "type": "object",
+        "properties": {
+          "binding_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "provider_slug": {
+            "type": "string"
+          },
+          "provider_name": {
+            "type": "string"
+          },
+          "scopes": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "active",
+              "expired",
+              "revoked"
+            ]
+          },
+          "needs_reauth": {
+            "type": "boolean"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "OAuthConnectionListResponse": {
+        "type": "object",
+        "properties": {
+          "connections": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/OAuthConnectionResponse"
+            }
+          }
+        }
+      },
+      "SaveOAuthAppCredentialsRequest": {
+        "type": "object",
+        "required": [
+          "provider_slug",
+          "client_id",
+          "client_secret"
+        ],
+        "properties": {
+          "provider_slug": {
+            "type": "string",
+            "description": "Provider this credential is for"
+          },
+          "client_id": {
+            "type": "string"
+          },
+          "client_secret": {
+            "type": "string",
+            "description": "Write-only; never returned in responses"
+          },
+          "redirect_uri": {
+            "type": "string",
+            "format": "uri",
+            "description": "Custom redirect URI override"
+          }
+        }
+      },
+      "OAuthAppCredentialResponse": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "provider_slug": {
+            "type": "string"
+          },
+          "client_id": {
+            "type": "string"
+          },
+          "redirect_uri": {
+            "type": "string",
+            "format": "uri",
+            "nullable": true
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "OAuthAppCredentialListResponse": {
+        "type": "object",
+        "properties": {
+          "credentials": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/OAuthAppCredentialResponse"
+            }
+          }
+        }
       }
     }
   }