feat(backend/api): Add POST /graphs endpoint to external API (#12208)

- Resolves [SECRT-2031: Add upload agent to Library endpoint on external
API](https://linear.app/autogpt/issue/SECRT-2031)

### Changes 🏗️

- Add `POST /graphs` to v1 external API
- Add support for requiring multiple scopes in `require_permission`
middleware
- Add `WRITE_GRAPH` and `WRITE_LIBRARY` API permission scopes

### Checklist 📋

#### For code changes:
- [x] I have clearly listed my changes in the PR description
- [x] I have made a test plan
- [x] I have tested my changes according to the test plan:
  - [x] Test `POST /graphs` endpoint through `/docs` Swagger UI

autogpt_platform/backend/backend/api/external/middleware.py

@@ -88,20 +88,23 @@ async def require_auth(
     )
 
 
-def require_permission(permission: APIKeyPermission):
+def require_permission(*permissions: APIKeyPermission):
     """
-    Dependency function for checking specific permissions
+    Dependency function for checking required permissions.
+    All listed permissions must be present.
     (works with API keys and OAuth tokens)
     """
 
-    async def check_permission(
+    async def check_permissions(
         auth: APIAuthorizationInfo = Security(require_auth),
     ) -> APIAuthorizationInfo:
-        if permission not in auth.scopes:
+        missing = [p for p in permissions if p not in auth.scopes]
+        if missing:
             raise HTTPException(
                 status_code=status.HTTP_403_FORBIDDEN,
-                detail=f"Missing required permission: {permission.value}",
+                detail=f"Missing required permission(s): "
+                f"{', '.join(p.value for p in missing)}",
             )
         return auth
 
-    return check_permission
+    return check_permissions

autogpt_platform/backend/backend/api/external/v1/routes.py

@@ -18,6 +18,7 @@ from backend.data import user as user_db
 from backend.data.auth.base import APIAuthorizationInfo
 from backend.data.block import BlockInput, CompletedBlockOutput
 from backend.executor.utils import add_graph_execution
+from backend.integrations.webhooks.graph_lifecycle_hooks import on_graph_activate
 from backend.util.settings import Settings
 
 from .integrations import integrations_router
@@ -95,6 +96,43 @@ async def execute_graph_block(
     return output
 
 
+@v1_router.post(
+    path="/graphs",
+    tags=["graphs"],
+    status_code=201,
+    dependencies=[
+        Security(
+            require_permission(
+                APIKeyPermission.WRITE_GRAPH, APIKeyPermission.WRITE_LIBRARY
+            )
+        )
+    ],
+)
+async def create_graph(
+    graph: graph_db.Graph,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.WRITE_GRAPH, APIKeyPermission.WRITE_LIBRARY)
+    ),
+) -> graph_db.GraphModel:
+    """
+    Create a new agent graph.
+
+    The graph will be validated and assigned a new ID.
+    It is automatically added to the user's library.
+    """
+    from backend.api.features.library import db as library_db
+
+    graph_model = graph_db.make_graph_model(graph, auth.user_id)
+    graph_model.reassign_ids(user_id=auth.user_id, reassign_graph_id=True)
+    graph_model.validate_graph(for_run=False)
+
+    await graph_db.create_graph(graph_model, user_id=auth.user_id)
+    await library_db.create_library_agent(graph_model, auth.user_id)
+    activated_graph = await on_graph_activate(graph_model, user_id=auth.user_id)
+
+    return activated_graph
+
+
 @v1_router.post(
     path="/graphs/{graph_id}/execute/{graph_version}",
     tags=["graphs"],

autogpt_platform/backend/migrations/20260225163452_add_library_api_key_permission/migration.sql

@@ -0,0 +1,7 @@
+-- This migration adds more than one value to an enum.
+-- With PostgreSQL versions 11 and earlier, this is not possible
+-- in a single migration. This can be worked around by creating
+-- multiple migrations, each migration adding only one value to
+-- the enum.
+ALTER TYPE "APIKeyPermission" ADD VALUE 'WRITE_GRAPH';
+ALTER TYPE "APIKeyPermission" ADD VALUE 'WRITE_LIBRARY';

autogpt_platform/backend/schema.prisma

@@ -1130,9 +1130,11 @@ enum APIKeyPermission {
   IDENTITY // Info about the authenticated user
   EXECUTE_GRAPH // Can execute agent graphs
   READ_GRAPH // Can get graph versions and details
+  WRITE_GRAPH // Can create and update agent graphs
   EXECUTE_BLOCK // Can execute individual blocks
   READ_BLOCK // Can get block information
   READ_STORE // Can read store agents and creators
+  WRITE_LIBRARY // Can add agents to library
   USE_TOOLS // Can use chat tools via external API
   MANAGE_INTEGRATIONS // Can initiate OAuth flows and complete them
   READ_INTEGRATIONS // Can list credentials and providers

autogpt_platform/frontend/src/app/(platform)/auth/authorize/page.tsx

@@ -19,6 +19,8 @@ const SCOPE_DESCRIPTIONS: { [key in APIKeyPermission]: string } = {
   IDENTITY: "View your user ID, e-mail, and timezone",
   EXECUTE_GRAPH: "Run your agents",
   READ_GRAPH: "View your agents and their configurations",
+  WRITE_GRAPH: "Create agent graphs",
+  WRITE_LIBRARY: "Add agents to your library",
   EXECUTE_BLOCK: "Execute individual blocks",
   READ_BLOCK: "View available blocks",
   READ_STORE: "Access the Marketplace",

autogpt_platform/frontend/src/app/api/openapi.json

@@ -6654,9 +6654,11 @@
           "IDENTITY",
           "EXECUTE_GRAPH",
           "READ_GRAPH",
+          "WRITE_GRAPH",
           "EXECUTE_BLOCK",
           "READ_BLOCK",
           "READ_STORE",
+          "WRITE_LIBRARY",
           "USE_TOOLS",
           "MANAGE_INTEGRATIONS",
           "READ_INTEGRATIONS",