@arke-institute/sdk 2.1.0 → 2.2.0

package/openapi/spec.json

@@ -47,6 +47,10 @@
     {
       "name": "Agents",
       "description": "Agent management and invocation"
+    },
+    {
+      "name": "Events",
+      "description": "Entity change event stream"
     }
   ],
   "components": {
@@ -373,21 +377,35 @@
             "description": "Optional note describing this change",
             "example": "Added Chapter 42: The Whiteness of the Whale"
           },
-          "label": {
-            "type": "string",
-            "minLength": 1,
-            "description": "Updated display name",
-            "example": "Captain Ahab"
-          },
           "properties": {
             "type": "object",
             "additionalProperties": {
               "nullable": true
             },
-            "description": "Properties to merge with existing (partial update)",
-            "example": {
-              "bio": "Commander of the Pequod, hunter of the white whale"
-            }
+            "description": "Properties to add or update (deep merged)"
+          },
+          "properties_remove": {
+            "anyOf": [
+              {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Top-level property keys to remove",
+                "example": [
+                  "deprecated_field",
+                  "old_field"
+                ]
+              },
+              {
+                "type": "object",
+                "additionalProperties": {
+                  "nullable": true
+                },
+                "description": "Nested removal structure (recursive: values can be string[] or nested objects)"
+              }
+            ],
+            "description": "Properties to remove"
           },
           "relationships_add": {
             "type": "array",
@@ -450,7 +468,7 @@
               ],
               "description": "Relationship to add or update (upsert semantics)"
             },
-            "description": "Relationships to add or update"
+            "description": "Relationships to add or update (upsert semantics)"
           },
           "relationships_remove": {
             "type": "array",
@@ -475,6 +493,12 @@
               "description": "Relationship to remove"
             },
             "description": "Relationships to remove"
+          },
+          "label": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Updated display name",
+            "example": "Captain Ahab"
           }
         },
         "required": [
@@ -749,28 +773,35 @@
             "description": "Optional note describing this change",
             "example": "Added Chapter 42: The Whiteness of the Whale"
           },
-          "label": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 200,
-            "description": "Updated collection display name"
-          },
-          "description": {
-            "type": "string",
-            "maxLength": 2000,
-            "description": "Updated collection description"
-          },
-          "display_image_url": {
-            "type": "string",
-            "format": "uri",
-            "description": "Updated display image URL"
-          },
           "properties": {
             "type": "object",
             "additionalProperties": {
               "nullable": true
             },
-            "description": "Additional properties to merge"
+            "description": "Properties to add or update (deep merged)"
+          },
+          "properties_remove": {
+            "anyOf": [
+              {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Top-level property keys to remove",
+                "example": [
+                  "deprecated_field",
+                  "old_field"
+                ]
+              },
+              {
+                "type": "object",
+                "additionalProperties": {
+                  "nullable": true
+                },
+                "description": "Nested removal structure (recursive: values can be string[] or nested objects)"
+              }
+            ],
+            "description": "Properties to remove"
           },
           "relationships_add": {
             "type": "array",
@@ -833,7 +864,7 @@
               ],
               "description": "Relationship to add or update (upsert semantics)"
             },
-            "description": "Relationships to add or update"
+            "description": "Relationships to add or update (upsert semantics)"
           },
           "relationships_remove": {
             "type": "array",
@@ -858,6 +889,22 @@
               "description": "Relationship to remove"
             },
             "description": "Relationships to remove"
+          },
+          "label": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200,
+            "description": "Updated collection display name"
+          },
+          "description": {
+            "type": "string",
+            "maxLength": 2000,
+            "description": "Updated collection description"
+          },
+          "display_image_url": {
+            "type": "string",
+            "format": "uri",
+            "description": "Updated display image URL"
           }
         },
         "required": [
@@ -1509,13 +1556,7 @@
             "additionalProperties": {
               "nullable": true
             },
-            "description": "Properties to add or update (deep merged with existing)",
-            "example": {
-              "label": "Chapter 1: Loomings (Revised)",
-              "metadata": {
-                "status": "reviewed"
-              }
-            }
+            "description": "Properties to add or update (deep merged)"
           },
           "properties_remove": {
             "anyOf": [
@@ -1538,10 +1579,7 @@
                 "description": "Nested removal structure (recursive: values can be string[] or nested objects)"
               }
             ],
-            "description": "Properties to remove (string array or nested object)",
-            "example": [
-              "deprecated_field"
-            ]
+            "description": "Properties to remove"
           },
           "relationships_add": {
             "type": "array",
@@ -1629,26 +1667,6 @@
               "description": "Relationship to remove"
             },
             "description": "Relationships to remove"
-          },
-          "components": {
-            "type": "object",
-            "additionalProperties": {
-              "type": "string"
-            },
-            "description": "Components to add or update (key → CID)",
-            "example": {
-              "transcript.txt": "bafyrei..."
-            }
-          },
-          "components_remove": {
-            "type": "array",
-            "items": {
-              "type": "string"
-            },
-            "description": "Component keys to remove",
-            "example": [
-              "old_version.txt"
-            ]
           }
         },
         "required": [
@@ -2131,46 +2149,35 @@
             "description": "Optional note describing this change",
             "example": "Added Chapter 42: The Whiteness of the Whale"
           },
-          "key": {
-            "type": "string",
-            "minLength": 1,
-            "description": "New storage key. Must already exist in S3 (for regression to old version)."
-          },
-          "filename": {
-            "type": "string",
-            "minLength": 1,
-            "description": "New filename"
-          },
-          "content_type": {
-            "type": "string",
-            "minLength": 1,
-            "description": "New MIME type"
-          },
-          "size": {
-            "type": "integer",
-            "minimum": 0,
-            "description": "New file size in bytes"
-          },
-          "cid": {
-            "type": "string",
-            "description": "New content identifier"
-          },
-          "description": {
-            "type": "string",
-            "description": "New description"
-          },
           "properties": {
             "type": "object",
             "additionalProperties": {
               "nullable": true
             },
-            "description": "Additional properties to merge into the file metadata",
-            "example": {
-              "log_data": {
-                "status": "done",
-                "entries": []
+            "description": "Properties to add or update (deep merged)"
+          },
+          "properties_remove": {
+            "anyOf": [
+              {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Top-level property keys to remove",
+                "example": [
+                  "deprecated_field",
+                  "old_field"
+                ]
+              },
+              {
+                "type": "object",
+                "additionalProperties": {
+                  "nullable": true
+                },
+                "description": "Nested removal structure (recursive: values can be string[] or nested objects)"
               }
-            }
+            ],
+            "description": "Properties to remove"
           },
           "relationships_add": {
             "type": "array",
@@ -2233,7 +2240,7 @@
               ],
               "description": "Relationship to add or update (upsert semantics)"
             },
-            "description": "Relationships to add or update"
+            "description": "Relationships to add or update (upsert semantics)"
           },
           "relationships_remove": {
             "type": "array",
@@ -2258,6 +2265,34 @@
               "description": "Relationship to remove"
             },
             "description": "Relationships to remove"
+          },
+          "key": {
+            "type": "string",
+            "minLength": 1,
+            "description": "New storage key. Must already exist in S3 (for regression to old version)."
+          },
+          "filename": {
+            "type": "string",
+            "minLength": 1,
+            "description": "New filename"
+          },
+          "content_type": {
+            "type": "string",
+            "minLength": 1,
+            "description": "New MIME type"
+          },
+          "size": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "New file size in bytes"
+          },
+          "cid": {
+            "type": "string",
+            "description": "New content identifier"
+          },
+          "description": {
+            "type": "string",
+            "description": "New description"
           }
         },
         "required": [
@@ -2344,6 +2379,51 @@
           "size"
         ]
       },
+      "ConfirmUploadResponse": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/FileResponse"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "prev_cid": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Previous version CID. Not present if upload was already confirmed.",
+                "example": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy"
+              },
+              "already_confirmed": {
+                "type": "boolean",
+                "description": "True if upload was already confirmed. Entity was not modified.",
+                "example": false
+              }
+            },
+            "required": [
+              "already_confirmed"
+            ]
+          }
+        ]
+      },
+      "ConfirmUploadRequest": {
+        "type": "object",
+        "properties": {
+          "expect_tip": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Current tip CID for CAS validation. Request fails with 409 if this does not match.",
+            "example": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy"
+          },
+          "note": {
+            "type": "string",
+            "description": "Optional note describing this change",
+            "example": "Added Chapter 42: The Whiteness of the Whale"
+          }
+        },
+        "required": [
+          "expect_tip"
+        ]
+      },
       "CreateFolderResponse": {
         "type": "object",
         "properties": {
@@ -2590,32 +2670,35 @@
             "description": "Optional note describing this change",
             "example": "Added Chapter 42: The Whiteness of the Whale"
           },
-          "label": {
-            "type": "string",
-            "minLength": 1,
-            "description": "New display name"
-          },
-          "description": {
-            "type": "string",
-            "description": "New description"
-          },
-          "rich_description": {
-            "type": "string",
-            "description": "New rich description"
-          },
-          "metadata": {
-            "type": "object",
-            "additionalProperties": {
-              "nullable": true
-            },
-            "description": "New metadata (deep merged)"
-          },
           "properties": {
             "type": "object",
             "additionalProperties": {
               "nullable": true
             },
-            "description": "Additional properties to merge"
+            "description": "Properties to add or update (deep merged)"
+          },
+          "properties_remove": {
+            "anyOf": [
+              {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Top-level property keys to remove",
+                "example": [
+                  "deprecated_field",
+                  "old_field"
+                ]
+              },
+              {
+                "type": "object",
+                "additionalProperties": {
+                  "nullable": true
+                },
+                "description": "Nested removal structure (recursive: values can be string[] or nested objects)"
+              }
+            ],
+            "description": "Properties to remove"
           },
           "relationships_add": {
             "type": "array",
@@ -2678,7 +2761,7 @@
               ],
               "description": "Relationship to add or update (upsert semantics)"
             },
-            "description": "Relationships to add or update"
+            "description": "Relationships to add or update (upsert semantics)"
           },
           "relationships_remove": {
             "type": "array",
@@ -2703,6 +2786,26 @@
               "description": "Relationship to remove"
             },
             "description": "Relationships to remove"
+          },
+          "label": {
+            "type": "string",
+            "minLength": 1,
+            "description": "New display name"
+          },
+          "description": {
+            "type": "string",
+            "description": "New description"
+          },
+          "rich_description": {
+            "type": "string",
+            "description": "New rich description"
+          },
+          "metadata": {
+            "type": "object",
+            "additionalProperties": {
+              "nullable": true
+            },
+            "description": "New metadata (deep merged)"
           }
         },
         "required": [
@@ -2938,7 +3041,8 @@
               ]
             },
             "minItems": 1,
-            "description": "Children to add",
+            "maxItems": 50,
+            "description": "Children to add (max 50 per request)",
             "example": [
               {
                 "id": "01JFILE123ABCDEFGHJKMNPQRS"
@@ -3277,26 +3381,6 @@
                   }
                 }
               },
-              "components": {
-                "type": "object",
-                "additionalProperties": {
-                  "type": "object",
-                  "properties": {
-                    "/": {
-                      "type": "string",
-                      "minLength": 1
-                    }
-                  },
-                  "required": [
-                    "/"
-                  ],
-                  "description": "IPLD link object",
-                  "example": {
-                    "/": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy"
-                  }
-                },
-                "description": "IPLD links to components (files, chunks, etc.)"
-              },
               "edited_by": {
                 "type": "object",
                 "properties": {
@@ -3714,73 +3798,35 @@
             "description": "Optional note describing this change",
             "example": "Added Chapter 42: The Whiteness of the Whale"
           },
-          "label": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 200,
-            "description": "Updated agent display name"
-          },
-          "description": {
-            "type": "string",
-            "maxLength": 2000,
-            "description": "Updated agent description"
-          },
-          "endpoint": {
-            "type": "string",
-            "format": "uri",
-            "description": "Updated agent service URL"
-          },
-          "actions_required": {
-            "type": "array",
-            "items": {
-              "type": "string",
-              "pattern": "^[a-z_]+:[a-z_]+$"
-            },
-            "minItems": 1,
-            "description": "Actions this agent requires on target collections",
-            "example": [
-              "entity:view",
-              "entity:update",
-              "file:create"
-            ]
-          },
-          "status": {
-            "type": "string",
-            "enum": [
-              "development",
-              "active",
-              "disabled"
-            ],
-            "description": "Agent status",
-            "example": "development"
-          },
-          "uses_agents": {
-            "type": "array",
-            "items": {
-              "$ref": "#/components/schemas/SubAgentRef"
-            },
-            "description": "Updated sub-agents"
-          },
-          "input_schema": {
-            "type": "object",
-            "additionalProperties": {
-              "nullable": true
-            },
-            "description": "Updated input schema"
-          },
-          "output_schema": {
-            "type": "object",
-            "additionalProperties": {
-              "nullable": true
-            },
-            "description": "Updated output schema"
-          },
           "properties": {
             "type": "object",
             "additionalProperties": {
               "nullable": true
             },
-            "description": "Additional properties to merge"
+            "description": "Properties to add or update (deep merged)"
+          },
+          "properties_remove": {
+            "anyOf": [
+              {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Top-level property keys to remove",
+                "example": [
+                  "deprecated_field",
+                  "old_field"
+                ]
+              },
+              {
+                "type": "object",
+                "additionalProperties": {
+                  "nullable": true
+                },
+                "description": "Nested removal structure (recursive: values can be string[] or nested objects)"
+              }
+            ],
+            "description": "Properties to remove"
           },
           "relationships_add": {
             "type": "array",
@@ -3843,7 +3889,7 @@
               ],
               "description": "Relationship to add or update (upsert semantics)"
             },
-            "description": "Relationships to add or update"
+            "description": "Relationships to add or update (upsert semantics)"
           },
           "relationships_remove": {
             "type": "array",
@@ -3867,7 +3913,68 @@
               ],
               "description": "Relationship to remove"
             },
-            "description": "Relationships to remove"
+            "description": "Relationships to remove"
+          },
+          "label": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200,
+            "description": "Updated agent display name"
+          },
+          "description": {
+            "type": "string",
+            "maxLength": 2000,
+            "description": "Updated agent description"
+          },
+          "endpoint": {
+            "type": "string",
+            "format": "uri",
+            "description": "Updated agent service URL"
+          },
+          "actions_required": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^[a-z_]+:[a-z_]+$"
+            },
+            "minItems": 1,
+            "description": "Actions this agent requires on target collections",
+            "example": [
+              "entity:view",
+              "entity:update",
+              "file:create"
+            ]
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "development",
+              "active",
+              "disabled"
+            ],
+            "description": "Agent status",
+            "example": "development"
+          },
+          "uses_agents": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/SubAgentRef"
+            },
+            "description": "Updated sub-agents"
+          },
+          "input_schema": {
+            "type": "object",
+            "additionalProperties": {
+              "nullable": true
+            },
+            "description": "Updated input schema"
+          },
+          "output_schema": {
+            "type": "object",
+            "additionalProperties": {
+              "nullable": true
+            },
+            "description": "Updated output schema"
           }
         },
         "required": [
@@ -4258,6 +4365,101 @@
         "required": [
           "keys"
         ]
+      },
+      "EventItem": {
+        "type": "object",
+        "properties": {
+          "event_cid": {
+            "type": "string",
+            "minLength": 1,
+            "description": "CID of this event in the event chain",
+            "example": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy"
+          },
+          "type": {
+            "type": "string",
+            "enum": [
+              "create",
+              "update"
+            ],
+            "description": "Type of entity change event",
+            "example": "create"
+          },
+          "pi": {
+            "type": "string",
+            "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
+            "description": "Entity ID that was created or updated",
+            "example": "01KDETYWYWM0MJVKM8DK3AEXPY"
+          },
+          "ver": {
+            "type": "integer",
+            "minimum": 0,
+            "exclusiveMinimum": true,
+            "description": "Entity version number",
+            "example": 1
+          },
+          "tip_cid": {
+            "type": "string",
+            "minLength": 1,
+            "description": "CID of the entity manifest at this version",
+            "example": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy"
+          },
+          "ts": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the event was recorded",
+            "example": "2025-12-26T12:00:00.000Z"
+          }
+        },
+        "required": [
+          "event_cid",
+          "type",
+          "pi",
+          "ver",
+          "tip_cid",
+          "ts"
+        ]
+      },
+      "EventsListResponse": {
+        "type": "object",
+        "properties": {
+          "items": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/EventItem"
+            },
+            "description": "Events in reverse chronological order"
+          },
+          "total_events": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Total events in the event chain",
+            "example": 1542
+          },
+          "total_pis": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Total unique entity IDs across all events",
+            "example": 987
+          },
+          "has_more": {
+            "type": "boolean",
+            "description": "Whether more events exist beyond this page"
+          },
+          "next_cursor": {
+            "type": "string",
+            "nullable": true,
+            "minLength": 1,
+            "description": "CID to use as \"cursor\" parameter for next page",
+            "example": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy"
+          }
+        },
+        "required": [
+          "items",
+          "total_events",
+          "total_pis",
+          "has_more",
+          "next_cursor"
+        ]
       }
     },
     "parameters": {}
@@ -6309,7 +6511,7 @@
           "Files"
         ],
         "summary": "Create file entity",
-        "description": "Creates a new file entity and returns a presigned upload URL.\n\n## Flow\n1. Call this endpoint with file metadata (key, filename, content_type, size)\n2. Receive entity data + presigned S3 upload URL\n3. PUT the file content to the upload URL\n4. File is now stored and accessible\n\n## Key Best Practice\nUse the file's CID as the key for content-addressable storage.\nThe system does NOT verify the CID - it's just metadata.",
+        "description": "Creates a new file entity and returns a presigned upload URL.\n\n## Flow\n1. Call this endpoint with file metadata (key, filename, content_type, size)\n2. Receive entity data + presigned S3 upload URL (uploaded: false)\n3. PUT the file content to the upload URL\n4. Call POST /{id}/confirm-upload to verify and set uploaded: true\n\n## Key Best Practice\nUse the file's CID as the key for content-addressable storage.\nThe system does NOT verify the CID - it's just metadata.",
         "x-arke-action": "file:create",
         "x-arke-auth": "required",
         "security": [
@@ -6668,7 +6870,7 @@
           "Files"
         ],
         "summary": "Upload new file version",
-        "description": "Uploads a new version of a file.\n\n## Flow\n1. Call this endpoint with new key and file metadata\n2. Receive updated entity + presigned upload URL\n3. PUT the new file content to the upload URL\n4. Old file versions remain accessible via manifest history\n\n## Key Requirement\nThe new key must NOT already exist in S3 (no overwrites).\nPrevious file versions are preserved.",
+        "description": "Uploads a new version of a file.\n\n## Flow\n1. Call this endpoint with new key and file metadata\n2. Receive updated entity + presigned upload URL (uploaded: false)\n3. PUT the new file content to the upload URL\n4. Call POST /{id}/confirm-upload to verify and set uploaded: true\n5. Old file versions remain accessible via manifest history\n\n## Key Requirement\nThe new key must NOT already exist in S3 (no overwrites).\nPrevious file versions are preserved.",
         "x-arke-action": "file:reupload",
         "x-arke-auth": "required",
         "security": [
@@ -6793,6 +6995,137 @@
         }
       }
     },
+    "/files/{id}/confirm-upload": {
+      "post": {
+        "tags": [
+          "Files"
+        ],
+        "summary": "Confirm upload completed",
+        "description": "Confirms that file content has been uploaded to S3.\n\n## Flow\n1. Create file entity (POST /files) - sets uploaded: false\n2. PUT file content to the presigned upload URL\n3. Call this endpoint to confirm - verifies file exists in S3, sets uploaded: true\n\n## Verification\nThe server verifies the file exists in S3 before setting uploaded: true.\nIf the file doesn't exist, returns 400 error.\n\n## Idempotency\nIf already uploaded: true, returns success without modification.",
+        "x-arke-action": "file:update",
+        "x-arke-auth": "required",
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
+              "description": "Entity ID (ULID format)",
+              "example": "01KDETYWYWM0MJVKM8DK3AEXPY"
+            },
+            "required": true,
+            "description": "Entity ID (ULID)",
+            "name": "id",
+            "in": "path"
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ConfirmUploadRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Upload confirmed",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ConfirmUploadResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request - Invalid input",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ValidationErrorResponse"
+                },
+                "example": {
+                  "error": "Validation failed",
+                  "details": {
+                    "issues": [
+                      {
+                        "path": [
+                          "properties",
+                          "label"
+                        ],
+                        "message": "Required"
+                      }
+                    ]
+                  }
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized - Missing or invalid authentication",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "example": {
+                  "error": "Unauthorized: Missing or invalid authentication token"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Forbidden - Insufficient permissions",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "example": {
+                  "error": "Forbidden: You do not have permission to perform this action"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not Found - Resource does not exist",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "example": {
+                  "error": "Entity not found"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "Conflict - CAS validation failed (entity was modified)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CASErrorResponse"
+                },
+                "example": {
+                  "error": "Conflict: entity was modified",
+                  "details": {
+                    "expected": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
+                    "actual": "bafyreinewabc123456789defghijklmnopqrstuvwxyz"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/folders": {
       "post": {
         "tags": [
@@ -7352,7 +7685,7 @@
           "Folders"
         ],
         "summary": "Bulk add children to folder",
-        "description": "Efficiently adds multiple children to a folder.\n\n**Strategy**:\n1. Updates folder once with all 'contains' relationships\n2. Updates each child in parallel with 'in' back-link\n\n**Idempotent**: skips children that already have the relationship.\nReturns both added and skipped children in the response.",
+        "description": "Efficiently adds multiple children to a folder.\n\n**Limit**: Maximum 50 children per request. For larger batches, make multiple\nrequests, refetching the folder's CID between each to satisfy the CAS guard.\n\n**Strategy**:\n1. Updates folder once with all 'contains' relationships\n2. Updates each child in parallel with 'in' back-link\n\n**Idempotent**: skips children that already have the relationship.\nReturns both added and skipped children in the response.",
         "x-arke-action": "folder:update",
         "x-arke-auth": "required",
         "security": [
@@ -8643,6 +8976,56 @@
           }
         }
       }
+    },
+    "/events": {
+      "get": {
+        "tags": [
+          "Events"
+        ],
+        "summary": "List events",
+        "description": "Returns entity change events in reverse chronological order (newest first).\n\nEach event represents a create or update operation on an entity. Use cursor-based pagination to walk through the event history.\n\n**Use cases:**\n- Syncing entity changes to external systems\n- Building search indexes\n- Change tracking and audit logs\n\n**Note:** This endpoint is public. Access control is enforced at the entity level - if you don't have permission to view an entity, you won't be able to fetch its manifest even if you see an event for it.",
+        "x-arke-action": "events:list",
+        "x-arke-auth": "none",
+        "parameters": [
+          {
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 100,
+              "default": 50,
+              "example": 50
+            },
+            "required": false,
+            "description": "Maximum events to return (1-100, default 50)",
+            "name": "limit",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "description": "IPFS Content Identifier (CID)",
+              "example": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy"
+            },
+            "required": false,
+            "description": "Event CID to continue from (for pagination)",
+            "name": "cursor",
+            "in": "query"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Event list",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/EventsListResponse"
+                }
+              }
+            }
+          }
+        }
+      }
     }
   }
 }