@desplega.ai/agent-swarm 1.78.1 → 1.79.1

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.78.0",
+    "version": "1.79.1",
     "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": [
@@ -3332,9 +3332,967 @@
         }
       }
     },
+    "/api/kv/{key}": {
+      "get": {
+        "summary": "Get a KV entry by key (namespace resolved from request headers)",
+        "tags": [
+          "KV"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 512,
+              "pattern": "^[a-zA-Z0-9._:/%-]{1,512}$"
+            },
+            "required": true,
+            "name": "key",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "KV entry"
+          },
+          "400": {
+            "description": "Validation error or unresolvable namespace"
+          },
+          "404": {
+            "description": "KV entry not found or expired"
+          }
+        }
+      },
+      "put": {
+        "summary": "Upsert a KV entry by key (namespace resolved from request headers)",
+        "tags": [
+          "KV"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 512,
+              "pattern": "^[a-zA-Z0-9._:/%-]{1,512}$"
+            },
+            "required": true,
+            "name": "key",
+            "in": "path"
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "value": {},
+                  "valueType": {
+                    "type": "string",
+                    "enum": [
+                      "json",
+                      "string",
+                      "integer"
+                    ]
+                  },
+                  "expiresInSec": {
+                    "type": "integer",
+                    "exclusiveMinimum": 0
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "KV entry stored"
+          },
+          "400": {
+            "description": "Validation error"
+          },
+          "403": {
+            "description": "Caller may not write this namespace"
+          },
+          "409": {
+            "description": "INCR collision: existing value_type is not 'integer'"
+          },
+          "413": {
+            "description": "Body exceeds 2 MiB"
+          }
+        }
+      },
+      "delete": {
+        "summary": "Delete a KV entry by key (namespace resolved from request headers)",
+        "tags": [
+          "KV"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 512,
+              "pattern": "^[a-zA-Z0-9._:/%-]{1,512}$"
+            },
+            "required": true,
+            "name": "key",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "KV entry deleted"
+          },
+          "400": {
+            "description": "Validation error or unresolvable namespace"
+          },
+          "403": {
+            "description": "Caller may not write this namespace"
+          },
+          "404": {
+            "description": "KV entry not found"
+          }
+        }
+      }
+    },
+    "/api/kv/{key}/incr": {
+      "post": {
+        "summary": "Atomically increment an integer KV entry (header-resolved namespace)",
+        "tags": [
+          "KV"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 512,
+              "pattern": "^[a-zA-Z0-9._:/%-]{1,512}$"
+            },
+            "required": true,
+            "name": "key",
+            "in": "path"
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": [
+                  "object",
+                  "null"
+                ],
+                "properties": {
+                  "by": {
+                    "type": "integer"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "KV entry stored"
+          },
+          "400": {
+            "description": "Validation error"
+          },
+          "403": {
+            "description": "Caller may not write this namespace"
+          },
+          "409": {
+            "description": "INCR collision: existing value_type is not 'integer'"
+          },
+          "413": {
+            "description": "Body exceeds 2 MiB"
+          }
+        }
+      }
+    },
+    "/api/kv": {
+      "get": {
+        "summary": "List KV entries in the header-resolved namespace",
+        "tags": [
+          "KV"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "prefix",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 1000
+            },
+            "required": false,
+            "name": "limit",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": [
+                "integer",
+                "null"
+              ],
+              "minimum": 0
+            },
+            "required": false,
+            "name": "offset",
+            "in": "query"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "KV entries in the resolved namespace"
+          },
+          "400": {
+            "description": "Validation error or unresolvable namespace"
+          }
+        }
+      }
+    },
+    "/api/kv/_/{namespace}/{key}": {
+      "get": {
+        "summary": "Get a KV entry by explicit namespace + key",
+        "tags": [
+          "KV"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 512,
+              "pattern": "^[a-zA-Z0-9._:/%-]{1,512}$"
+            },
+            "required": true,
+            "name": "namespace",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 512,
+              "pattern": "^[a-zA-Z0-9._:/%-]{1,512}$"
+            },
+            "required": true,
+            "name": "key",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "KV entry"
+          },
+          "400": {
+            "description": "Validation error or unresolvable namespace"
+          },
+          "404": {
+            "description": "KV entry not found or expired"
+          }
+        }
+      },
+      "put": {
+        "summary": "Upsert a KV entry by explicit namespace + key",
+        "tags": [
+          "KV"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 512,
+              "pattern": "^[a-zA-Z0-9._:/%-]{1,512}$"
+            },
+            "required": true,
+            "name": "namespace",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 512,
+              "pattern": "^[a-zA-Z0-9._:/%-]{1,512}$"
+            },
+            "required": true,
+            "name": "key",
+            "in": "path"
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "value": {},
+                  "valueType": {
+                    "type": "string",
+                    "enum": [
+                      "json",
+                      "string",
+                      "integer"
+                    ]
+                  },
+                  "expiresInSec": {
+                    "type": "integer",
+                    "exclusiveMinimum": 0
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "KV entry stored"
+          },
+          "400": {
+            "description": "Validation error"
+          },
+          "403": {
+            "description": "Caller may not write this namespace"
+          },
+          "409": {
+            "description": "INCR collision: existing value_type is not 'integer'"
+          },
+          "413": {
+            "description": "Body exceeds 2 MiB"
+          }
+        }
+      },
+      "delete": {
+        "summary": "Delete a KV entry by explicit namespace + key",
+        "tags": [
+          "KV"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 512,
+              "pattern": "^[a-zA-Z0-9._:/%-]{1,512}$"
+            },
+            "required": true,
+            "name": "namespace",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 512,
+              "pattern": "^[a-zA-Z0-9._:/%-]{1,512}$"
+            },
+            "required": true,
+            "name": "key",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "KV entry deleted"
+          },
+          "403": {
+            "description": "Caller may not write this namespace"
+          },
+          "404": {
+            "description": "KV entry not found"
+          }
+        }
+      }
+    },
+    "/api/kv/_/{namespace}/{key}/incr": {
+      "post": {
+        "summary": "Atomically increment an integer KV entry (explicit namespace)",
+        "tags": [
+          "KV"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 512,
+              "pattern": "^[a-zA-Z0-9._:/%-]{1,512}$"
+            },
+            "required": true,
+            "name": "namespace",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 512,
+              "pattern": "^[a-zA-Z0-9._:/%-]{1,512}$"
+            },
+            "required": true,
+            "name": "key",
+            "in": "path"
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": [
+                  "object",
+                  "null"
+                ],
+                "properties": {
+                  "by": {
+                    "type": "integer"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "KV entry stored"
+          },
+          "400": {
+            "description": "Validation error"
+          },
+          "403": {
+            "description": "Caller may not write this namespace"
+          },
+          "409": {
+            "description": "INCR collision: existing value_type is not 'integer'"
+          },
+          "413": {
+            "description": "Body exceeds 2 MiB"
+          }
+        }
+      }
+    },
+    "/api/kv/_/{namespace}": {
+      "get": {
+        "summary": "List KV entries in an explicit namespace",
+        "tags": [
+          "KV"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 512,
+              "pattern": "^[a-zA-Z0-9._:/%-]{1,512}$"
+            },
+            "required": true,
+            "name": "namespace",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "prefix",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 1000
+            },
+            "required": false,
+            "name": "limit",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": [
+                "integer",
+                "null"
+              ],
+              "minimum": 0
+            },
+            "required": false,
+            "name": "offset",
+            "in": "query"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "KV entries in the resolved namespace"
+          },
+          "400": {
+            "description": "Validation error or unresolvable namespace"
+          }
+        }
+      }
+    },
     "/api/memory/index": {
       "post": {
-        "summary": "Ingest content into memory system (async embedding)",
+        "summary": "Ingest content into memory system (async embedding)",
+        "tags": [
+          "Memory"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "agentId": {
+                    "type": "string",
+                    "format": "uuid"
+                  },
+                  "content": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "name": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "scope": {
+                    "type": "string",
+                    "enum": [
+                      "agent",
+                      "swarm"
+                    ]
+                  },
+                  "source": {
+                    "type": "string",
+                    "enum": [
+                      "manual",
+                      "file_index",
+                      "session_summary",
+                      "task_completion"
+                    ]
+                  },
+                  "sourceTaskId": {
+                    "type": "string",
+                    "format": "uuid"
+                  },
+                  "sourcePath": {
+                    "type": "string"
+                  },
+                  "tags": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                },
+                "required": [
+                  "content",
+                  "name",
+                  "scope",
+                  "source"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "202": {
+            "description": "Content queued for embedding"
+          },
+          "400": {
+            "description": "Validation error"
+          }
+        }
+      }
+    },
+    "/api/memory/search": {
+      "post": {
+        "summary": "Search memories by natural language query",
+        "tags": [
+          "Memory"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "query": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "limit": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 20,
+                    "default": 5
+                  }
+                },
+                "required": [
+                  "query"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Search results"
+          },
+          "400": {
+            "description": "Missing query or agent ID"
+          }
+        }
+      }
+    },
+    "/api/memory/re-embed": {
+      "post": {
+        "summary": "Re-embed all memories using the current embedding provider",
+        "tags": [
+          "Memory"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "agentId": {
+                    "type": "string",
+                    "format": "uuid",
+                    "description": "Re-embed only this agent's memories. Omit for all."
+                  },
+                  "batchSize": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 100,
+                    "default": 20,
+                    "description": "Memories per batch"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "202": {
+            "description": "Re-embedding started"
+          }
+        }
+      }
+    },
+    "/api/memory/list": {
+      "post": {
+        "summary": "List or semantically search memories across all agents (debug/admin)",
+        "tags": [
+          "Memory"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "query": {
+                    "type": "string",
+                    "description": "Natural-language query. If present, runs semantic search; otherwise lists by recency."
+                  },
+                  "agentId": {
+                    "type": "string",
+                    "format": "uuid",
+                    "description": "Filter to a single agent. Omit for all."
+                  },
+                  "scope": {
+                    "type": "string",
+                    "enum": [
+                      "agent",
+                      "swarm",
+                      "all"
+                    ],
+                    "default": "all"
+                  },
+                  "source": {
+                    "type": "string",
+                    "enum": [
+                      "manual",
+                      "file_index",
+                      "session_summary",
+                      "task_completion"
+                    ]
+                  },
+                  "sourcePath": {
+                    "type": "string",
+                    "description": "Substring match against sourcePath (case-insensitive). Useful for file_index memories."
+                  },
+                  "limit": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 100,
+                    "default": 20
+                  },
+                  "offset": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "default": 0
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Memory list / search results"
+          },
+          "400": {
+            "description": "Validation error"
+          }
+        }
+      }
+    },
+    "/api/memory/{id}": {
+      "delete": {
+        "summary": "Delete a single memory by ID (debug/admin)",
+        "tags": [
+          "Memory"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Memory deleted"
+          },
+          "404": {
+            "description": "Memory not found"
+          }
+        }
+      }
+    },
+    "/api/memory/rate": {
+      "post": {
+        "summary": "Submit RatingEvents to update memory usefulness posteriors",
+        "tags": [
+          "Memory"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "events": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "memoryId": {
+                          "type": "string",
+                          "minLength": 1
+                        },
+                        "signal": {
+                          "type": "number",
+                          "minimum": -1,
+                          "maximum": 1
+                        },
+                        "weight": {
+                          "type": "number",
+                          "minimum": 0,
+                          "maximum": 1
+                        },
+                        "source": {
+                          "type": "string",
+                          "enum": [
+                            "llm",
+                            "explicit-self"
+                          ]
+                        },
+                        "reasoning": {
+                          "type": "string",
+                          "maxLength": 500
+                        },
+                        "taskId": {
+                          "type": "string",
+                          "format": "uuid"
+                        },
+                        "referencesSource": {
+                          "type": "string",
+                          "minLength": 1,
+                          "maxLength": 512,
+                          "description": "Optional external source ID this memory references. Free-form string, convention \"<source>:<identifier>\" (e.g. \"github:owner/repo#N\", \"linear:KEY-N\", \"customer:<slug>\", \"slack:<channel>:<ts>\", \"agentmail:<thread-id>\"). Pick any prefix that fits — no closed enum. When present, an edge from this memory to the external source is created/updated."
+                        }
+                      },
+                      "required": [
+                        "memoryId",
+                        "signal",
+                        "weight",
+                        "source"
+                      ]
+                    },
+                    "minItems": 1,
+                    "maxItems": 50
+                  }
+                },
+                "required": [
+                  "events"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Ratings applied; per-event rejections returned in body"
+          },
+          "400": {
+            "description": "Validation error or explicit-self R6 spam-guard rejection"
+          },
+          "409": {
+            "description": "Duplicate explicit-self rating for (taskId, memoryId)"
+          }
+        }
+      }
+    },
+    "/api/memory/retrievals": {
+      "get": {
+        "summary": "List memories retrieved for a task or session (rater input)",
+        "tags": [
+          "Memory"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            },
+            "required": false,
+            "name": "taskId",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "sessionId",
+            "in": "query"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Retrieval rows joined with agent_memory"
+          },
+          "400": {
+            "description": "Missing taskId/sessionId or X-Agent-ID"
+          }
+        }
+      }
+    },
+    "/api/memory/edges": {
+      "get": {
+        "summary": "List references-source edges for a memory",
         "tags": [
           "Memory"
         ],
@@ -3343,48 +4301,153 @@
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            },
+            "required": true,
+            "name": "memoryId",
+            "in": "query"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Edges with computed usefulness scores"
+          },
+          "400": {
+            "description": "Missing memoryId or X-Agent-ID"
+          }
+        }
+      }
+    },
+    "/@swarm/api/{path}": {
+      "get": {
+        "summary": "Cookie-gated proxy to the swarm API (used by db-backed page iframes)",
+        "tags": [
+          "Pages"
+        ],
+        "responses": {
+          "200": {
+            "description": "Proxied response from the underlying /api/* endpoint"
+          },
+          "401": {
+            "description": "No or invalid page-session cookie"
+          },
+          "404": {
+            "description": "Page referenced by the cookie no longer exists"
+          }
+        }
+      },
+      "post": {
+        "summary": "Cookie-gated proxy to the swarm API (POST)",
+        "tags": [
+          "Pages"
+        ],
+        "responses": {
+          "200": {
+            "description": "Proxied response"
+          },
+          "401": {
+            "description": "No or invalid page-session cookie"
+          }
+        }
+      },
+      "put": {
+        "summary": "Cookie-gated proxy to the swarm API (PUT)",
+        "tags": [
+          "Pages"
+        ],
+        "responses": {
+          "200": {
+            "description": "Proxied response"
+          },
+          "401": {
+            "description": "No or invalid page-session cookie"
+          }
+        }
+      },
+      "delete": {
+        "summary": "Cookie-gated proxy to the swarm API (DELETE)",
+        "tags": [
+          "Pages"
+        ],
+        "responses": {
+          "200": {
+            "description": "Proxied response"
+          },
+          "401": {
+            "description": "No or invalid page-session cookie"
+          }
+        }
+      },
+      "patch": {
+        "summary": "Cookie-gated proxy to the swarm API (PATCH)",
+        "tags": [
+          "Pages"
+        ],
+        "responses": {
+          "200": {
+            "description": "Proxied response"
+          },
+          "401": {
+            "description": "No or invalid page-session cookie"
+          }
+        }
+      }
+    },
+    "/api/pages": {
+      "post": {
+        "summary": "Create a new page",
+        "tags": [
+          "Pages"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
         "requestBody": {
           "content": {
             "application/json": {
               "schema": {
                 "type": "object",
                 "properties": {
-                  "agentId": {
-                    "type": "string",
-                    "format": "uuid"
-                  },
-                  "content": {
+                  "slug": {
                     "type": "string",
                     "minLength": 1
                   },
-                  "name": {
+                  "title": {
                     "type": "string",
                     "minLength": 1
                   },
-                  "scope": {
+                  "description": {
+                    "type": "string"
+                  },
+                  "contentType": {
                     "type": "string",
                     "enum": [
-                      "agent",
-                      "swarm"
+                      "text/html",
+                      "application/json"
                     ]
                   },
-                  "source": {
+                  "authMode": {
                     "type": "string",
                     "enum": [
-                      "manual",
-                      "file_index",
-                      "session_summary",
-                      "task_completion"
+                      "public",
+                      "authed",
+                      "password"
                     ]
                   },
-                  "sourceTaskId": {
+                  "password": {
                     "type": "string",
-                    "format": "uuid"
+                    "minLength": 1
                   },
-                  "sourcePath": {
+                  "body": {
                     "type": "string"
                   },
-                  "tags": {
+                  "needsCredentials": {
                     "type": "array",
                     "items": {
                       "type": "string"
@@ -3392,169 +4455,176 @@
                   }
                 },
                 "required": [
-                  "content",
-                  "name",
-                  "scope",
-                  "source"
+                  "title",
+                  "contentType",
+                  "authMode",
+                  "body"
                 ]
               }
             }
           }
         },
         "responses": {
-          "202": {
-            "description": "Content queued for embedding"
+          "201": {
+            "description": "Page created"
           },
           "400": {
-            "description": "Validation error"
+            "description": "Invalid body"
+          },
+          "409": {
+            "description": "Slug already exists for this agent"
           }
         }
-      }
-    },
-    "/api/memory/search": {
-      "post": {
-        "summary": "Search memories by natural language query",
+      },
+      "get": {
+        "summary": "List pages",
         "tags": [
-          "Memory"
+          "Pages"
         ],
         "security": [
           {
             "bearerAuth": []
           }
         ],
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "type": "object",
-                "properties": {
-                  "query": {
-                    "type": "string",
-                    "minLength": 1
-                  },
-                  "limit": {
-                    "type": "integer",
-                    "minimum": 1,
-                    "maximum": 20,
-                    "default": 5
-                  }
-                },
-                "required": [
-                  "query"
-                ]
-              }
-            }
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            },
+            "required": false,
+            "name": "agentId",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 500
+            },
+            "required": false,
+            "name": "limit",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": [
+                "integer",
+                "null"
+              ],
+              "minimum": 0
+            },
+            "required": false,
+            "name": "offset",
+            "in": "query"
           }
-        },
+        ],
         "responses": {
           "200": {
-            "description": "Search results"
-          },
-          "400": {
-            "description": "Missing query or agent ID"
+            "description": "Page list with totals + share-URL pointers"
           }
         }
       }
     },
-    "/api/memory/re-embed": {
-      "post": {
-        "summary": "Re-embed all memories using the current embedding provider",
+    "/api/pages/{id}": {
+      "get": {
+        "summary": "Get a page by ID",
         "tags": [
-          "Memory"
+          "Pages"
         ],
         "security": [
           {
             "bearerAuth": []
           }
         ],
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "type": "object",
-                "properties": {
-                  "agentId": {
-                    "type": "string",
-                    "format": "uuid",
-                    "description": "Re-embed only this agent's memories. Omit for all."
-                  },
-                  "batchSize": {
-                    "type": "integer",
-                    "minimum": 1,
-                    "maximum": 100,
-                    "default": 20,
-                    "description": "Memories per batch"
-                  }
-                }
-              }
-            }
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
           }
-        },
+        ],
         "responses": {
-          "202": {
-            "description": "Re-embedding started"
+          "200": {
+            "description": "Page row"
+          },
+          "404": {
+            "description": "Page not found"
           }
         }
-      }
-    },
-    "/api/memory/list": {
-      "post": {
-        "summary": "List or semantically search memories across all agents (debug/admin)",
+      },
+      "put": {
+        "summary": "Update an existing page",
         "tags": [
-          "Memory"
+          "Pages"
         ],
         "security": [
           {
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
+          }
+        ],
         "requestBody": {
           "content": {
             "application/json": {
               "schema": {
                 "type": "object",
                 "properties": {
-                  "query": {
-                    "type": "string",
-                    "description": "Natural-language query. If present, runs semantic search; otherwise lists by recency."
-                  },
-                  "agentId": {
-                    "type": "string",
-                    "format": "uuid",
-                    "description": "Filter to a single agent. Omit for all."
+                  "title": {
+                    "type": "string",
+                    "minLength": 1
                   },
-                  "scope": {
+                  "description": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "contentType": {
                     "type": "string",
                     "enum": [
-                      "agent",
-                      "swarm",
-                      "all"
-                    ],
-                    "default": "all"
+                      "text/html",
+                      "application/json"
+                    ]
                   },
-                  "source": {
+                  "authMode": {
                     "type": "string",
                     "enum": [
-                      "manual",
-                      "file_index",
-                      "session_summary",
-                      "task_completion"
+                      "public",
+                      "authed",
+                      "password"
                     ]
                   },
-                  "sourcePath": {
-                    "type": "string",
-                    "description": "Substring match against sourcePath (case-insensitive). Useful for file_index memories."
+                  "password": {
+                    "type": [
+                      "string",
+                      "null"
+                    ],
+                    "minLength": 1
                   },
-                  "limit": {
-                    "type": "integer",
-                    "minimum": 1,
-                    "maximum": 100,
-                    "default": 20
+                  "body": {
+                    "type": "string"
                   },
-                  "offset": {
-                    "type": "integer",
-                    "minimum": 0,
-                    "default": 0
+                  "needsCredentials": {
+                    "type": [
+                      "array",
+                      "null"
+                    ],
+                    "items": {
+                      "type": "string"
+                    }
                   }
                 }
               }
@@ -3563,19 +4633,20 @@
         },
         "responses": {
           "200": {
-            "description": "Memory list / search results"
+            "description": "Page updated"
           },
-          "400": {
-            "description": "Validation error"
+          "404": {
+            "description": "Page not found"
+          },
+          "413": {
+            "description": "Payload too large"
           }
         }
-      }
-    },
-    "/api/memory/{id}": {
+      },
       "delete": {
-        "summary": "Delete a single memory by ID (debug/admin)",
+        "summary": "Delete a page (and all version history)",
         "tags": [
-          "Memory"
+          "Pages"
         ],
         "security": [
           {
@@ -3585,8 +4656,7 @@
         "parameters": [
           {
             "schema": {
-              "type": "string",
-              "format": "uuid"
+              "type": "string"
             },
             "required": true,
             "name": "id",
@@ -3594,109 +4664,72 @@
           }
         ],
         "responses": {
-          "200": {
-            "description": "Memory deleted"
+          "204": {
+            "description": "Page deleted"
           },
           "404": {
-            "description": "Memory not found"
+            "description": "Page not found"
           }
         }
       }
     },
-    "/api/memory/rate": {
+    "/api/pages/{id}/launch": {
       "post": {
-        "summary": "Submit RatingEvents to update memory usefulness posteriors",
+        "summary": "Launch a page session (issues HttpOnly cookie)",
         "tags": [
-          "Memory"
+          "Pages"
         ],
         "security": [
           {
             "bearerAuth": []
           }
         ],
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "type": "object",
-                "properties": {
-                  "events": {
-                    "type": "array",
-                    "items": {
-                      "type": "object",
-                      "properties": {
-                        "memoryId": {
-                          "type": "string",
-                          "minLength": 1
-                        },
-                        "signal": {
-                          "type": "number",
-                          "minimum": -1,
-                          "maximum": 1
-                        },
-                        "weight": {
-                          "type": "number",
-                          "minimum": 0,
-                          "maximum": 1
-                        },
-                        "source": {
-                          "type": "string",
-                          "enum": [
-                            "llm",
-                            "explicit-self"
-                          ]
-                        },
-                        "reasoning": {
-                          "type": "string",
-                          "maxLength": 500
-                        },
-                        "taskId": {
-                          "type": "string",
-                          "format": "uuid"
-                        },
-                        "referencesSource": {
-                          "type": "string",
-                          "minLength": 1,
-                          "maxLength": 512,
-                          "description": "Optional external source ID this memory references. Free-form string, convention \"<source>:<identifier>\" (e.g. \"github:owner/repo#N\", \"linear:KEY-N\", \"customer:<slug>\", \"slack:<channel>:<ts>\", \"agentmail:<thread-id>\"). Pick any prefix that fits — no closed enum. When present, an edge from this memory to the external source is created/updated."
-                        }
-                      },
-                      "required": [
-                        "memoryId",
-                        "signal",
-                        "weight",
-                        "source"
-                      ]
-                    },
-                    "minItems": 1,
-                    "maxItems": 50
-                  }
-                },
-                "required": [
-                  "events"
-                ]
-              }
-            }
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
           }
-        },
+        ],
         "responses": {
-          "200": {
-            "description": "Ratings applied; per-event rejections returned in body"
+          "204": {
+            "description": "Cookie issued"
           },
           "400": {
-            "description": "Validation error or explicit-self R6 spam-guard rejection"
+            "description": "Launch not supported for this page (e.g. password mode)"
           },
-          "409": {
-            "description": "Duplicate explicit-self rating for (taskId, memoryId)"
+          "404": {
+            "description": "Page not found"
           }
         }
       }
     },
-    "/api/memory/retrievals": {
+    "/api/pages/actions": {
       "get": {
-        "summary": "List memories retrieved for a task or session (rater input)",
+        "summary": "List JSON-page action allowlist (with param JSON Schemas)",
         "tags": [
-          "Memory"
+          "Pages"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Action allowlist"
+          }
+        }
+      }
+    },
+    "/api/pages/{id}/versions": {
+      "get": {
+        "summary": "List version snapshots for a page",
+        "tags": [
+          "Pages"
         ],
         "security": [
           {
@@ -3706,60 +4739,126 @@
         "parameters": [
           {
             "schema": {
-              "type": "string",
-              "format": "uuid"
+              "type": "string"
             },
-            "required": false,
-            "name": "taskId",
-            "in": "query"
+            "required": true,
+            "name": "id",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Version list (newest first)"
           },
+          "404": {
+            "description": "Page not found"
+          }
+        }
+      }
+    },
+    "/api/pages/{id}/versions/{version}": {
+      "get": {
+        "summary": "Get a single page-version snapshot",
+        "tags": [
+          "Pages"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
           {
             "schema": {
               "type": "string"
             },
-            "required": false,
-            "name": "sessionId",
-            "in": "query"
+            "required": true,
+            "name": "id",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "required": true,
+            "name": "version",
+            "in": "path"
           }
         ],
         "responses": {
           "200": {
-            "description": "Retrieval rows joined with agent_memory"
+            "description": "Version snapshot"
           },
-          "400": {
-            "description": "Missing taskId/sessionId or X-Agent-ID"
+          "404": {
+            "description": "Page or version not found"
           }
         }
       }
     },
-    "/api/memory/edges": {
+    "/p/{id}": {
       "get": {
-        "summary": "List references-source edges for a memory",
+        "summary": "Render a page (HTML inline; JSON redirects to SPA)",
         "tags": [
-          "Memory"
+          "Pages"
         ],
-        "security": [
+        "parameters": [
           {
-            "bearerAuth": []
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
           }
         ],
+        "responses": {
+          "200": {
+            "description": "Rendered HTML page"
+          },
+          "302": {
+            "description": "Redirect to SPA for JSON content"
+          },
+          "401": {
+            "description": "Page requires an authenticated session"
+          },
+          "403": {
+            "description": "Cookie does not match this page id"
+          },
+          "404": {
+            "description": "Page not found"
+          }
+        }
+      }
+    },
+    "/p/{id}.json": {
+      "get": {
+        "summary": "Page metadata + body as JSON (used by SPA renderer)",
+        "tags": [
+          "Pages"
+        ],
         "parameters": [
           {
             "schema": {
-              "type": "string",
-              "minLength": 1
+              "type": "string"
             },
             "required": true,
-            "name": "memoryId",
-            "in": "query"
+            "name": "id",
+            "in": "path"
           }
         ],
         "responses": {
           "200": {
-            "description": "Edges with computed usefulness scores"
+            "description": "Page JSON"
           },
-          "400": {
-            "description": "Missing memoryId or X-Agent-ID"
+          "401": {
+            "description": "Page requires an authenticated session"
+          },
+          "403": {
+            "description": "Cookie does not match this page id"
+          },
+          "404": {
+            "description": "Page not found"
           }
         }
       }