@arke-institute/sdk 3.6.4 → 3.6.9

package/openapi/spec.json

@@ -116,13 +116,13 @@
         "type": "http",
         "scheme": "bearer",
         "bearerFormat": "JWT",
-        "description": "Supabase JWT token"
+        "description": "Supabase JWT token. Use `Authorization: Bearer <jwt>`. Only for JWT tokens from Supabase auth - do NOT use Bearer with API keys."
       },
       "apiKeyAuth": {
         "type": "apiKey",
         "in": "header",
         "name": "Authorization",
-        "description": "API Key authentication. Format: `ApiKey ak_xxx` (agent) or `ApiKey uk_xxx` (user)"
+        "description": "API Key authentication. **Important:** Use `Authorization: ApiKey <key>` (NOT Bearer). Format: `ApiKey uk_xxx` (user keys) or `ApiKey ak_xxx` (agent keys). Using Bearer with API keys will fail."
       }
     },
     "parameters": {
@@ -237,10 +237,10 @@
             ],
             "description": "Identity type"
           },
-          "pi": {
+          "id": {
             "type": "string",
             "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
-            "description": "User entity PI (persistent identifier)",
+            "description": "User entity ID",
             "example": "01J1SHMAE10000000000000000"
           },
           "auth_method": {
@@ -281,7 +281,7 @@
         },
         "required": [
           "type",
-          "pi",
+          "id",
           "auth_method"
         ]
       },
@@ -295,10 +295,10 @@
             ],
             "description": "Identity type"
           },
-          "pi": {
+          "id": {
             "type": "string",
             "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
-            "description": "Agent entity PI (persistent identifier)",
+            "description": "Agent entity ID",
             "example": "01J1AGENTID000000000000000"
           },
           "auth_method": {
@@ -309,10 +309,10 @@
             "description": "How this identity was authenticated",
             "example": "api_key"
           },
-          "owner_pi": {
+          "owner_id": {
             "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 PI of the agent owner",
+            "description": "Entity ID of the agent owner",
             "example": "01J1OWNERID0000000000000000"
           },
           "key_prefix": {
@@ -328,9 +328,9 @@
         },
         "required": [
           "type",
-          "pi",
+          "id",
           "auth_method",
-          "owner_pi",
+          "owner_id",
           "key_prefix",
           "key_expires_at"
         ]
@@ -710,9 +710,9 @@
       "UserCollectionItem": {
         "type": "object",
         "properties": {
-          "pi": {
+          "id": {
             "type": "string",
-            "description": "Collection persistent identifier",
+            "description": "Collection ID",
             "example": "01JCOLLECTION123456789AB"
           },
           "label": {
@@ -732,7 +732,7 @@
           }
         },
         "required": [
-          "pi",
+          "id",
           "label",
           "predicate",
           "created_at"
@@ -806,7 +806,7 @@
             "description": "Entity label (from properties.label, filename, or name)",
             "example": "Research Paper.pdf"
           },
-          "collection_pi": {
+          "collection_id": {
             "type": "string",
             "description": "Collection ID this entity belongs to",
             "example": "01JCOLLECTION123456789ABCD"
@@ -844,7 +844,7 @@
           "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
           "type": "file",
           "label": "Research Paper.pdf",
-          "collection_pi": "01JCOLLECTION123456789AB",
+          "collection_id": "01JCOLLECTION123456789AB",
           "description_preview": "A comprehensive study on distributed systems architecture...",
           "created_at": "2026-01-12T00:00:00.000Z",
           "updated_at": "2026-01-12T10:30:00.000Z"
@@ -853,10 +853,10 @@
       "SearchResultItem": {
         "type": "object",
         "properties": {
-          "pi": {
+          "id": {
             "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 persistent identifier",
+            "description": "Entity ID",
             "example": "01KDETYWYWM0MJVKM8DK3AEXPY"
           },
           "type": {
@@ -869,7 +869,7 @@
             "description": "Entity label/name",
             "example": "Research Paper.pdf"
           },
-          "collection_pi": {
+          "collection_id": {
             "type": "string",
             "nullable": true,
             "description": "Collection this entity belongs to (null for public-domain)",
@@ -905,10 +905,10 @@
           }
         },
         "required": [
-          "pi",
+          "id",
           "type",
           "label",
-          "collection_pi",
+          "collection_id",
           "score"
         ]
       },
@@ -1120,6 +1120,12 @@
             "format": "uri",
             "description": "URL for collection display image"
           },
+          "use_roles_default": {
+            "type": "boolean",
+            "default": true,
+            "description": "Whether to merge with default roles (true) or use only provided roles (false). Public role with *:view is always ensured.",
+            "example": true
+          },
           "roles": {
             "type": "object",
             "additionalProperties": {
@@ -1128,26 +1134,11 @@
                 "type": "string"
               }
             },
-            "description": "Custom role definitions (defaults to owner/editor/viewer/public)",
+            "description": "Role definitions. When use_roles_default is true (default), these merge with defaults. When false, these replace defaults entirely.",
             "example": {
-              "captain": [
-                "*:view",
-                "*:update",
-                "*:create",
-                "collection:manage"
-              ],
-              "harpooner": [
-                "*:view",
-                "*:update",
-                "*:create"
-              ],
-              "crew": [
-                "*:view",
-                "entity:create"
-              ],
               "public": [
-                "entity:view",
-                "collection:view"
+                "*:view",
+                "*:invoke"
               ]
             }
           },
@@ -1836,10 +1827,10 @@
       "CollectionEntitySummary": {
         "type": "object",
         "properties": {
-          "pi": {
+          "id": {
             "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 persistent identifier"
+            "description": "Entity ID"
           },
           "type": {
             "type": "string",
@@ -1883,7 +1874,7 @@
           }
         },
         "required": [
-          "pi",
+          "id",
           "type",
           "label",
           "created_at",
@@ -2258,6 +2249,11 @@
             "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
             "description": "Parent collection ID (creates collection relationship)",
             "example": "01KDETYWYWM0MJVKM8DK3AEXPY"
+          },
+          "sync_index": {
+            "type": "boolean",
+            "default": false,
+            "description": "Wait for collection index update before returning. Use when checking for duplicates immediately after creation. Adds ~1-5ms latency per collection."
           }
         },
         "required": [
@@ -2699,6 +2695,11 @@
               "description": "Relationship to remove"
             },
             "description": "Relationships to remove"
+          },
+          "sync_index": {
+            "type": "boolean",
+            "default": false,
+            "description": "Wait for collection index update before returning. Use when checking index immediately after update."
           }
         },
         "required": [
@@ -2766,6 +2767,11 @@
             "maxLength": 500,
             "description": "Reason for deleting the entity",
             "example": "Duplicate entry"
+          },
+          "sync_index": {
+            "type": "boolean",
+            "default": false,
+            "description": "Wait for collection index removal before returning. Use when checking index immediately after deletion."
           }
         },
         "required": [
@@ -3038,7 +3044,7 @@
       "TreeNode": {
         "type": "object",
         "properties": {
-          "pi": {
+          "id": {
             "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)",
@@ -3065,7 +3071,7 @@
           }
         },
         "required": [
-          "pi",
+          "id",
           "label",
           "type",
           "depth",
@@ -5775,29 +5781,54 @@
               "type": "object",
               "properties": {
                 "klados": {
-                  "type": "object",
-                  "properties": {
-                    "pi": {
-                      "type": "string",
-                      "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$"
-                    },
-                    "type": {
-                      "type": "string"
-                    },
-                    "label": {
-                      "type": "string"
+                  "anyOf": [
+                    {
+                      "type": "object",
+                      "properties": {
+                        "id": {
+                          "type": "string",
+                          "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$"
+                        },
+                        "type": {
+                          "type": "string"
+                        },
+                        "label": {
+                          "type": "string"
+                        },
+                        "description": {
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "id"
+                      ]
                     },
-                    "description": {
-                      "type": "string"
+                    {
+                      "type": "object",
+                      "properties": {
+                        "pi": {
+                          "type": "string",
+                          "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$"
+                        },
+                        "type": {
+                          "type": "string"
+                        },
+                        "label": {
+                          "type": "string"
+                        },
+                        "description": {
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "pi"
+                      ]
                     }
-                  },
-                  "required": [
-                    "pi"
                   ],
                   "description": "Reference to the klados entity to invoke for this step",
                   "title": "KladosRef",
                   "example": {
-                    "pi": "01KEXAMPLE123456789012345",
+                    "id": "01KEXAMPLE123456789012345",
                     "type": "klados",
                     "label": "OCR Processor"
                   }
@@ -5944,7 +5975,7 @@
             "example": {
               "extract": {
                 "klados": {
-                  "pi": "01KKLADOSA12345678901234",
+                  "id": "01KKLADOSA12345678901234",
                   "type": "klados"
                 },
                 "then": {
@@ -5953,7 +5984,7 @@
               },
               "summarize": {
                 "klados": {
-                  "pi": "01KKLADOSB12345678901234",
+                  "id": "01KKLADOSB12345678901234",
                   "type": "klados"
                 },
                 "then": {
@@ -6217,29 +6248,54 @@
               "type": "object",
               "properties": {
                 "klados": {
-                  "type": "object",
-                  "properties": {
-                    "pi": {
-                      "type": "string",
-                      "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$"
-                    },
-                    "type": {
-                      "type": "string"
-                    },
-                    "label": {
-                      "type": "string"
+                  "anyOf": [
+                    {
+                      "type": "object",
+                      "properties": {
+                        "id": {
+                          "type": "string",
+                          "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$"
+                        },
+                        "type": {
+                          "type": "string"
+                        },
+                        "label": {
+                          "type": "string"
+                        },
+                        "description": {
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "id"
+                      ]
                     },
-                    "description": {
-                      "type": "string"
+                    {
+                      "type": "object",
+                      "properties": {
+                        "pi": {
+                          "type": "string",
+                          "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$"
+                        },
+                        "type": {
+                          "type": "string"
+                        },
+                        "label": {
+                          "type": "string"
+                        },
+                        "description": {
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "pi"
+                      ]
                     }
-                  },
-                  "required": [
-                    "pi"
                   ],
                   "description": "Reference to the klados entity to invoke for this step",
                   "title": "KladosRef",
                   "example": {
-                    "pi": "01KEXAMPLE123456789012345",
+                    "id": "01KEXAMPLE123456789012345",
                     "type": "klados",
                     "label": "OCR Processor"
                   }
@@ -6386,7 +6442,7 @@
             "example": {
               "extract": {
                 "klados": {
-                  "pi": "01KKLADOSA12345678901234",
+                  "id": "01KKLADOSA12345678901234",
                   "type": "klados"
                 },
                 "then": {
@@ -6395,7 +6451,7 @@
               },
               "summarize": {
                 "klados": {
-                  "pi": "01KKLADOSB12345678901234",
+                  "id": "01KKLADOSB12345678901234",
                   "type": "klados"
                 },
                 "then": {
@@ -6852,7 +6908,7 @@
             "description": "Auto-increment event ID (use as cursor)",
             "example": 12346
           },
-          "pi": {
+          "entity_id": {
             "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 changed",
@@ -6872,7 +6928,7 @@
         },
         "required": [
           "id",
-          "pi",
+          "entity_id",
           "cid",
           "ts"
         ]
@@ -6907,7 +6963,7 @@
       "PathEdge": {
         "type": "object",
         "properties": {
-          "subject_pi": {
+          "subject_id": {
             "type": "string",
             "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
             "description": "Source entity PI",
@@ -6945,7 +7001,7 @@
             "type": "string",
             "description": "Relationship predicate"
           },
-          "object_pi": {
+          "object_id": {
             "type": "string",
             "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
             "description": "Target entity PI",
@@ -6981,36 +7037,36 @@
           }
         },
         "required": [
-          "subject_pi",
+          "subject_id",
           "subject_label",
           "subject_type",
           "predicate",
-          "object_pi",
+          "object_id",
           "object_label",
           "object_type"
         ],
         "example": {
-          "subject_pi": "01KE4ZY69F9R40E88PK9S0TQRQ",
+          "subject_id": "01KE4ZY69F9R40E88PK9S0TQRQ",
           "subject_label": "Project Folder",
           "subject_type": "folder",
           "subject_preview": {
             "id": "01KE4ZY69F9R40E88PK9S0TQRQ",
             "type": "folder",
             "label": "Project Folder",
-            "collection_pi": "01JCOLLECTION123456789ABCD",
+            "collection_id": "01JCOLLECTION123456789ABCD",
             "description_preview": "Main project folder containing research documents...",
             "created_at": "2025-01-10T08:00:00.000Z",
             "updated_at": "2025-01-18T16:45:00.000Z"
           },
           "predicate": "contains",
-          "object_pi": "01KE506KZGD8M2P1XK3VNQT4YR",
+          "object_id": "01KE506KZGD8M2P1XK3VNQT4YR",
           "object_label": "Research Paper.pdf",
           "object_type": "file",
           "object_preview": {
             "id": "01KE506KZGD8M2P1XK3VNQT4YR",
             "type": "file",
             "label": "Research Paper.pdf",
-            "collection_pi": "01JCOLLECTION123456789ABCD",
+            "collection_id": "01JCOLLECTION123456789ABCD",
             "description_preview": "Analysis of entity management patterns and best practices...",
             "created_at": "2025-01-15T10:00:00.000Z",
             "updated_at": "2025-01-20T14:30:00.000Z"
@@ -7020,13 +7076,13 @@
       "PathResult": {
         "type": "object",
         "properties": {
-          "source_pi": {
+          "source_id": {
             "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"
           },
-          "target_pi": {
+          "target_id": {
             "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)",
@@ -7044,8 +7100,8 @@
           }
         },
         "required": [
-          "source_pi",
-          "target_pi",
+          "source_id",
+          "target_id",
           "length",
           "edges"
         ]
@@ -7072,7 +7128,7 @@
       "PathsBetweenRequest": {
         "type": "object",
         "properties": {
-          "source_pis": {
+          "source_ids": {
             "type": "array",
             "items": {
               "type": "string",
@@ -7086,7 +7142,7 @@
               "01KE4ZY69F9R40E88PK9S0TQRQ"
             ]
           },
-          "target_pis": {
+          "target_ids": {
             "type": "array",
             "items": {
               "type": "string",
@@ -7129,20 +7185,20 @@
           }
         },
         "required": [
-          "source_pis",
-          "target_pis"
+          "source_ids",
+          "target_ids"
         ]
       },
       "ReachableResult": {
         "type": "object",
         "properties": {
-          "source_pi": {
+          "source_id": {
             "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"
           },
-          "target_pi": {
+          "target_id": {
             "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)",
@@ -7186,16 +7242,16 @@
           }
         },
         "required": [
-          "source_pi",
-          "target_pi",
+          "source_id",
+          "target_id",
           "target_label",
           "target_type",
           "length",
           "edges"
         ],
         "example": {
-          "source_pi": "01KE4ZY69F9R40E88PK9S0TQRQ",
-          "target_pi": "01KE506KZGD8M2P1XK3VNQT4YR",
+          "source_id": "01KE4ZY69F9R40E88PK9S0TQRQ",
+          "target_id": "01KE506KZGD8M2P1XK3VNQT4YR",
           "target_label": "Research Paper.pdf",
           "target_type": "file",
           "length": 1,
@@ -7204,7 +7260,7 @@
             "id": "01KE506KZGD8M2P1XK3VNQT4YR",
             "type": "file",
             "label": "Research Paper.pdf",
-            "collection_pi": "01JCOLLECTION123456789ABCD",
+            "collection_id": "01JCOLLECTION123456789ABCD",
             "description_preview": "Analysis of entity management patterns and best practices...",
             "created_at": "2025-01-15T10:00:00.000Z",
             "updated_at": "2025-01-20T14:30:00.000Z"
@@ -7233,7 +7289,7 @@
       "PathsReachableRequest": {
         "type": "object",
         "properties": {
-          "source_pis": {
+          "source_ids": {
             "type": "array",
             "items": {
               "type": "string",
@@ -7282,7 +7338,7 @@
           }
         },
         "required": [
-          "source_pis",
+          "source_ids",
           "target_type"
         ]
       },
@@ -7299,7 +7355,7 @@
           "predicate": {
             "type": "string"
           },
-          "peer_pi": {
+          "peer_id": {
             "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)",
@@ -7341,7 +7397,7 @@
         "required": [
           "direction",
           "predicate",
-          "peer_pi",
+          "peer_id",
           "peer_type",
           "peer_label",
           "properties"
@@ -7349,7 +7405,7 @@
         "example": {
           "direction": "outgoing",
           "predicate": "contains",
-          "peer_pi": "01KE506KZGD8M2P1XK3VNQT4YR",
+          "peer_id": "01KE506KZGD8M2P1XK3VNQT4YR",
           "peer_type": "file",
           "peer_label": "Research Paper.pdf",
           "properties": {},
@@ -7357,7 +7413,7 @@
             "id": "01KE506KZGD8M2P1XK3VNQT4YR",
             "type": "file",
             "label": "Research Paper.pdf",
-            "collection_pi": "01KE4ZY69F9R40E88PK9S0TQRQ",
+            "collection_id": "01KE4ZY69F9R40E88PK9S0TQRQ",
             "description_preview": "Analysis of entity management patterns and best practices...",
             "created_at": "2025-01-15T10:00:00.000Z",
             "updated_at": "2025-01-20T14:30:00.000Z"
@@ -7367,7 +7423,7 @@
       "GraphEntityResponse": {
         "type": "object",
         "properties": {
-          "pi": {
+          "id": {
             "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)",
@@ -7379,7 +7435,7 @@
           "label": {
             "type": "string"
           },
-          "collection_pi": {
+          "collection_id": {
             "type": "string",
             "nullable": true
           },
@@ -7399,26 +7455,26 @@
           }
         },
         "required": [
-          "pi",
+          "id",
           "type",
           "label",
-          "collection_pi",
+          "collection_id",
           "created_at",
           "updated_at",
           "relationships"
         ],
         "example": {
-          "pi": "01KE4ZY69F9R40E88PK9S0TQRQ",
+          "id": "01KE4ZY69F9R40E88PK9S0TQRQ",
           "type": "folder",
           "label": "Project Folder",
-          "collection_pi": "01JCOLLECTION123456789ABCD",
+          "collection_id": "01JCOLLECTION123456789ABCD",
           "created_at": "2025-01-10T08:00:00.000Z",
           "updated_at": "2025-01-18T16:45:00.000Z",
           "relationships": [
             {
               "direction": "outgoing",
               "predicate": "contains",
-              "peer_pi": "01KE506KZGD8M2P1XK3VNQT4YR",
+              "peer_id": "01KE506KZGD8M2P1XK3VNQT4YR",
               "peer_type": "file",
               "peer_label": "Research Paper.pdf",
               "properties": {},
@@ -7426,7 +7482,7 @@
                 "id": "01KE506KZGD8M2P1XK3VNQT4YR",
                 "type": "file",
                 "label": "Research Paper.pdf",
-                "collection_pi": "01JCOLLECTION123456789ABCD",
+                "collection_id": "01JCOLLECTION123456789ABCD",
                 "description_preview": "Analysis of entity management patterns and best practices...",
                 "created_at": "2025-01-15T10:00:00.000Z",
                 "updated_at": "2025-01-20T14:30:00.000Z"
@@ -7585,7 +7641,7 @@
                 "entity": {
                   "type": "object",
                   "properties": {
-                    "pi": {
+                    "id": {
                       "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)",
@@ -7599,7 +7655,7 @@
                       "type": "string",
                       "example": "Albert Einstein"
                     },
-                    "collection_pi": {
+                    "collection_id": {
                       "type": "string",
                       "nullable": true,
                       "example": "01JCOLL_RESEARCH"
@@ -7626,22 +7682,22 @@
                     }
                   },
                   "required": [
-                    "pi",
+                    "id",
                     "type",
                     "label",
-                    "collection_pi"
+                    "collection_id"
                   ],
                   "description": "Query result entity with optional expansion data",
                   "example": {
-                    "pi": "01KE4ZY69F9R40E88PK9S0TQRQ",
+                    "id": "01KE4ZY69F9R40E88PK9S0TQRQ",
                     "type": "person",
                     "label": "Albert Einstein",
-                    "collection_pi": "01JCOLL_RESEARCH",
+                    "collection_id": "01JCOLL_RESEARCH",
                     "preview_data": {
                       "id": "01KE4ZY69F9R40E88PK9S0TQRQ",
                       "type": "person",
                       "label": "Albert Einstein",
-                      "collection_pi": "01JCOLL_RESEARCH",
+                      "collection_id": "01JCOLL_RESEARCH",
                       "description_preview": "German-born theoretical physicist who developed the theory of relativity...",
                       "created_at": "2025-01-15T10:00:00.000Z",
                       "updated_at": "2025-01-20T14:30:00.000Z"
@@ -7669,15 +7725,15 @@
               "description": "A single query result with entity, path, and score",
               "example": {
                 "entity": {
-                  "pi": "01KE4ZY69F9R40E88PK9S0TQRQ",
+                  "id": "01KE4ZY69F9R40E88PK9S0TQRQ",
                   "type": "file",
                   "label": "Theory of Relativity.pdf",
-                  "collection_pi": "01JCOLL_RESEARCH",
+                  "collection_id": "01JCOLL_RESEARCH",
                   "preview_data": {
                     "id": "01KE4ZY69F9R40E88PK9S0TQRQ",
                     "type": "file",
                     "label": "Theory of Relativity.pdf",
-                    "collection_pi": "01JCOLL_RESEARCH",
+                    "collection_id": "01JCOLL_RESEARCH",
                     "description_preview": "Seminal paper on special and general relativity...",
                     "created_at": "2025-01-10T08:00:00.000Z",
                     "updated_at": "2025-01-10T08:00:00.000Z"
@@ -7752,6 +7808,18 @@
             ],
             "description": "Control entity expansion in results and path steps.\n- **omitted/preview** (default): Attach lightweight preview data (label, timestamps, truncated description/text)\n- **full**: Attach complete entity manifest (all properties, relationships, version info)\n- **none**: No expansion - return only Pinecone metadata (fastest, smallest payload)",
             "example": "preview"
+          },
+          "filter": {
+            "type": "object",
+            "additionalProperties": {
+              "nullable": true
+            },
+            "description": "Filter by indexed metadata properties during semantic search.\n\nOnly underscore-prefixed properties (`_year`, `_class`, etc.) are indexed as filterable metadata.\n\n**Operators:** `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$exists`, `$and`, `$or`\n\n**Example - Find letters from the 1800s:**\n```json\n{ \"_year\": { \"$gte\": 1800, \"$lte\": 1899 } }\n```",
+            "example": {
+              "_year": {
+                "$gt": 1800
+              }
+            }
           }
         },
         "required": [
@@ -8156,7 +8224,7 @@
       "AttestationResponse": {
         "type": "object",
         "properties": {
-          "pi": {
+          "id": {
             "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)",
@@ -8193,7 +8261,7 @@
           }
         },
         "required": [
-          "pi",
+          "id",
           "ver",
           "cid",
           "arweave_tx",
@@ -8204,7 +8272,7 @@
       "AttestationPendingResponse": {
         "type": "object",
         "properties": {
-          "pi": {
+          "id": {
             "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)",
@@ -8237,7 +8305,7 @@
           }
         },
         "required": [
-          "pi",
+          "id",
           "ver",
           "cid",
           "attestation_status",
@@ -8279,7 +8347,7 @@
           "attestation": {
             "type": "object",
             "properties": {
-              "pi": {
+              "id": {
                 "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)",
@@ -8327,7 +8395,7 @@
               }
             },
             "required": [
-              "pi",
+              "id",
               "ver",
               "cid",
               "op",
@@ -8401,6 +8469,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "responses": {
@@ -8479,6 +8550,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "responses": {
@@ -8717,6 +8791,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "responses": {
@@ -8763,6 +8840,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "requestBody": {
@@ -8813,6 +8893,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "responses": {
@@ -8856,6 +8939,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -9029,6 +9115,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "requestBody": {
@@ -9100,13 +9189,16 @@
           "Collections"
         ],
         "summary": "Create a new collection",
-        "description": "Creates a collection with the authenticated user as owner.\n\n---\n**Permission:** `collection:create`  \n**Auth:** required",
+        "description": "Creates a collection with the authenticated user as owner.\n\n**Default Roles:**\n\nBy default (`use_roles_default: true`), collections include these standard roles:\n- `owner`: Full control including collection management\n- `editor`: Can modify entities but not collection settings\n- `viewer`: Read-only access\n- `public`: Public read access (`*:view`)\n\n**Customizing Roles:**\n\nPass custom `roles` to override specific defaults while keeping others. For example, to make entities publicly invokable (for agents):\n```json\n{ \"roles\": { \"public\": [\"*:view\", \"*:invoke\"] } }\n```\n\nSet `use_roles_default: false` to define all roles from scratch.\n\n**Platform Requirement:** The `public` role with `*:view` is always automatically ensured, guaranteeing all collections are publicly readable.\n\n---\n**Permission:** `collection:create`  \n**Auth:** required",
         "x-arke-action": "collection:create",
         "x-arke-auth": "required",
         "x-arke-tier": "standard",
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "requestBody": {
@@ -9257,6 +9349,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -9403,6 +9498,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -9518,6 +9616,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -9643,6 +9744,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -9813,6 +9917,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -9928,6 +10035,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -10057,6 +10167,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -10182,7 +10295,7 @@
           "Collections"
         ],
         "summary": "List entities in a collection",
-        "description": "Returns entities belonging to this collection from the graph database.\n\nSupports pagination and optional type filtering. Results are ordered by creation date (newest first).\n\n**Expansion Modes:**\n\nBy default, returns lightweight summaries from GraphDB (pi, type, label, timestamps).\n\nUse the `expand` parameter to hydrate entity data from storage:\n\n- **`?expand=preview`**: Adds `preview` field with fresh lightweight data (label, truncated description/text, timestamps). ~5-10KB per entity.\n\n- **`?expand=full`**: Adds `entity` field with complete manifest (all properties, relationships, version history). ~20-50KB per entity.\n\n**Performance Note:** Expansion requires fetching each entity from storage. Limited to 100 entities per request. Use smaller `limit` values when expanding.\n\n---\n**Permission:** `collection:view`  \n**Auth:** optional",
+        "description": "Returns entities belonging to this collection.\n\nSupports pagination and optional type filtering. Results are ordered by creation date (newest first).\n\n**Expansion Modes:**\n\nBy default, returns lightweight summaries (pi, type, label, timestamps).\n\nUse the `expand` parameter to hydrate entity data from storage:\n\n- **`?expand=preview`**: Adds `preview` field with fresh lightweight data (label, truncated description/text, timestamps). ~5-10KB per entity.\n\n- **`?expand=full`**: Adds `entity` field with complete manifest (all properties, relationships, version history). ~20-50KB per entity.\n\n**Performance Note:** Expansion requires fetching each entity from storage. Limited to 100 entities per request. Use smaller `limit` values when expanding.\n\n---\n**Permission:** `collection:view`  \n**Auth:** optional",
         "x-arke-action": "collection:view",
         "x-arke-auth": "optional",
         "x-arke-tier": "external",
@@ -10209,6 +10322,16 @@
             "name": "type",
             "in": "query"
           },
+          {
+            "schema": {
+              "type": "string",
+              "description": "JSON-encoded filter for custom properties (underscore-prefixed). Supports direct equality {\"_year\": 1850} or operators {\"_year\": {\"$gte\": 1800}}. Operators: $eq, $ne, $gt, $gte, $lt, $lte.",
+              "example": "{\"_year\":{\"$gte\":1800,\"$lte\":1900}}"
+            },
+            "required": false,
+            "name": "filter",
+            "in": "query"
+          },
           {
             "schema": {
               "type": "integer",
@@ -10288,7 +10411,7 @@
             }
           },
           "503": {
-            "description": "GraphDB service unavailable"
+            "description": "Collection index service unavailable"
           }
         }
       }
@@ -10507,6 +10630,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -10629,6 +10755,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -10885,6 +11014,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -11029,6 +11161,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -11279,6 +11414,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -11412,6 +11550,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -11849,6 +11990,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -11931,6 +12075,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -12168,6 +12315,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -12321,6 +12471,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -12453,6 +12606,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -12568,6 +12724,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -12701,6 +12860,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "requestBody": {
@@ -12977,6 +13139,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "requestBody": {
@@ -13140,6 +13305,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -13272,6 +13440,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -13397,6 +13568,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -13522,6 +13696,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -13647,6 +13824,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -13760,6 +13940,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -13842,6 +14025,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -13929,6 +14115,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "requestBody": {
@@ -14092,6 +14281,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -14224,6 +14416,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -14409,6 +14604,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -14596,6 +14794,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -14675,6 +14876,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -14754,6 +14958,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -14825,6 +15032,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "requestBody": {
@@ -14887,6 +15097,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "requestBody": {
@@ -14895,9 +15108,9 @@
               "schema": {
                 "type": "object",
                 "properties": {
-                  "pi": {
+                  "id": {
                     "type": "string",
-                    "description": "Collection PI to find similar collections for"
+                    "description": "Collection ID to find similar collections for"
                   },
                   "limit": {
                     "type": "number",
@@ -14923,7 +15136,7 @@
                   }
                 },
                 "required": [
-                  "pi"
+                  "id"
                 ]
               }
             }
@@ -14942,7 +15155,7 @@
                       "items": {
                         "type": "object",
                         "properties": {
-                          "pi": {
+                          "id": {
                             "type": "string"
                           },
                           "label": {
@@ -14987,7 +15200,7 @@
                           }
                         },
                         "required": [
-                          "pi",
+                          "id",
                           "label",
                           "score"
                         ]
@@ -14996,7 +15209,7 @@
                     "metadata": {
                       "type": "object",
                       "properties": {
-                        "source_pi": {
+                        "source_id": {
                           "type": "string"
                         },
                         "result_count": {
@@ -15010,7 +15223,7 @@
                         }
                       },
                       "required": [
-                        "source_pi",
+                        "source_id",
                         "result_count"
                       ]
                     }
@@ -15092,6 +15305,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "requestBody": {
@@ -15100,13 +15316,13 @@
               "schema": {
                 "type": "object",
                 "properties": {
-                  "pi": {
+                  "id": {
                     "type": "string",
-                    "description": "Entity PI to find similar items for"
+                    "description": "Entity ID to find similar items for"
                   },
-                  "collection_pi": {
+                  "collection_id": {
                     "type": "string",
-                    "description": "Entity's collection PI"
+                    "description": "Entity's collection ID"
                   },
                   "limit": {
                     "type": "number",
@@ -15151,8 +15367,8 @@
                   }
                 },
                 "required": [
-                  "pi",
-                  "collection_pi"
+                  "id",
+                  "collection_id"
                 ]
               }
             }
@@ -15171,7 +15387,7 @@
                       "items": {
                         "type": "object",
                         "properties": {
-                          "pi": {
+                          "id": {
                             "type": "string"
                           },
                           "type": {
@@ -15180,7 +15396,7 @@
                           "label": {
                             "type": "string"
                           },
-                          "collection_pi": {
+                          "collection_id": {
                             "type": "string",
                             "nullable": true
                           },
@@ -15204,7 +15420,7 @@
                                   "id": "01KENTITY123456789ABCDEFGH",
                                   "type": "document",
                                   "label": "Similar Research Paper",
-                                  "collection_pi": "01JCOLLECTION123456789AB",
+                                  "collection_id": "01JCOLLECTION123456789AB",
                                   "description_preview": "Related findings on distributed systems...",
                                   "created_at": "2026-01-08T00:00:00.000Z",
                                   "updated_at": "2026-01-12T10:00:00.000Z"
@@ -15224,10 +15440,10 @@
                           }
                         },
                         "required": [
-                          "pi",
+                          "id",
                           "type",
                           "label",
-                          "collection_pi",
+                          "collection_id",
                           "score"
                         ]
                       }
@@ -15235,7 +15451,7 @@
                     "metadata": {
                       "type": "object",
                       "properties": {
-                        "source_pi": {
+                        "source_id": {
                           "type": "string"
                         },
                         "collections_searched": {
@@ -15252,7 +15468,7 @@
                         }
                       },
                       "required": [
-                        "source_pi",
+                        "source_id",
                         "collections_searched",
                         "result_count"
                       ]
@@ -15335,6 +15551,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "requestBody": {
@@ -15363,6 +15582,19 @@
                     },
                     "description": "Filter by collection types"
                   },
+                  "filter": {
+                    "type": "object",
+                    "additionalProperties": {
+                      "nullable": true
+                    },
+                    "description": "Filter by indexed metadata properties.\n\n**Filterable Properties:**\nOnly underscore-prefixed properties (`_year`, `_class`, etc.) are indexed as filterable metadata.\n\n**Operators:**\n| Operator | Description | Example |\n|----------|-------------|---------|\n| `$eq` | Equals | `{ \"_year\": { \"$eq\": 1905 } }` |\n| `$ne` | Not equals | `{ \"_class\": { \"$ne\": \"draft\" } }` |\n| `$gt` | Greater than | `{ \"_year\": { \"$gt\": 1900 } }` |\n| `$gte` | Greater than or equal | `{ \"_year\": { \"$gte\": 1900 } }` |\n| `$lt` | Less than | `{ \"_year\": { \"$lt\": 2000 } }` |\n| `$lte` | Less than or equal | `{ \"_year\": { \"$lte\": 2000 } }` |\n| `$in` | In array | `{ \"_class\": { \"$in\": [\"letter\", \"memo\"] } }` |\n| `$nin` | Not in array | `{ \"_class\": { \"$nin\": [\"draft\"] } }` |\n| `$exists` | Property exists | `{ \"_ocr_text\": { \"$exists\": true } }` |\n\n**Logical Operators:**\n| Operator | Description | Example |\n|----------|-------------|---------|\n| `$and` | All conditions must match | `{ \"$and\": [{ \"_year\": { \"$gt\": 1900 } }, { \"_year\": { \"$lt\": 2000 } }] }` |\n| `$or` | Any condition must match | `{ \"$or\": [{ \"_class\": \"letter\" }, { \"_class\": \"memo\" }] }` |\n\n**Built-in Fields (always available):**\n- `type` - Entity type\n- `created_at` - ISO timestamp string\n- `updated_at` - ISO timestamp string\n\n**Example - Find letters from 1800-1900:**\n```json\n{\n  \"$and\": [\n    { \"type\": { \"$eq\": \"letter\" } },\n    { \"_year\": { \"$gte\": 1800 } },\n    { \"_year\": { \"$lte\": 1900 } }\n  ]\n}\n```",
+                    "example": {
+                      "_year": {
+                        "$gt": 1800
+                      },
+                      "type": "letter"
+                    }
+                  },
                   "expand": {
                     "type": "string",
                     "enum": [
@@ -15394,7 +15626,7 @@
                       "items": {
                         "type": "object",
                         "properties": {
-                          "pi": {
+                          "id": {
                             "type": "string"
                           },
                           "label": {
@@ -15442,7 +15674,7 @@
                           }
                         },
                         "required": [
-                          "pi",
+                          "id",
                           "label",
                           "type",
                           "score"
@@ -15529,6 +15761,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "requestBody": {
@@ -15550,6 +15785,19 @@
                     "default": 10,
                     "description": "Maximum results to return"
                   },
+                  "filter": {
+                    "type": "object",
+                    "additionalProperties": {
+                      "nullable": true
+                    },
+                    "description": "Filter by indexed metadata properties.\n\n**Filterable Properties:**\nOnly underscore-prefixed properties (`_year`, `_class`, etc.) are indexed as filterable metadata.\n\n**Operators:**\n| Operator | Description | Example |\n|----------|-------------|---------|\n| `$eq` | Equals | `{ \"_year\": { \"$eq\": 1905 } }` |\n| `$ne` | Not equals | `{ \"_class\": { \"$ne\": \"draft\" } }` |\n| `$gt` | Greater than | `{ \"_year\": { \"$gt\": 1900 } }` |\n| `$gte` | Greater than or equal | `{ \"_year\": { \"$gte\": 1900 } }` |\n| `$lt` | Less than | `{ \"_year\": { \"$lt\": 2000 } }` |\n| `$lte` | Less than or equal | `{ \"_year\": { \"$lte\": 2000 } }` |\n| `$in` | In array | `{ \"_class\": { \"$in\": [\"letter\", \"memo\"] } }` |\n| `$nin` | Not in array | `{ \"_class\": { \"$nin\": [\"draft\"] } }` |\n| `$exists` | Property exists | `{ \"_ocr_text\": { \"$exists\": true } }` |\n\n**Logical Operators:**\n| Operator | Description | Example |\n|----------|-------------|---------|\n| `$and` | All conditions must match | `{ \"$and\": [{ \"_year\": { \"$gt\": 1900 } }, { \"_year\": { \"$lt\": 2000 } }] }` |\n| `$or` | Any condition must match | `{ \"$or\": [{ \"_class\": \"letter\" }, { \"_class\": \"memo\" }] }` |\n\n**Built-in Fields (always available):**\n- `type` - Entity type\n- `created_at` - ISO timestamp string\n- `updated_at` - ISO timestamp string\n\n**Example - Find letters from 1800-1900:**\n```json\n{\n  \"$and\": [\n    { \"type\": { \"$eq\": \"letter\" } },\n    { \"_year\": { \"$gte\": 1800 } },\n    { \"_year\": { \"$lte\": 1900 } }\n  ]\n}\n```",
+                    "example": {
+                      "_year": {
+                        "$gt": 1800
+                      },
+                      "type": "letter"
+                    }
+                  },
                   "expand": {
                     "type": "string",
                     "enum": [
@@ -15590,7 +15838,7 @@
                       "items": {
                         "type": "object",
                         "properties": {
-                          "pi": {
+                          "id": {
                             "type": "string"
                           },
                           "label": {
@@ -15599,7 +15847,7 @@
                           "score": {
                             "type": "number"
                           },
-                          "collection_pi": {
+                          "collection_id": {
                             "type": "string",
                             "nullable": true
                           },
@@ -15623,7 +15871,7 @@
                                   "id": "01KAGENT123456789ABCDEFGHI",
                                   "type": "agent",
                                   "label": "Document Analyzer Agent",
-                                  "collection_pi": "01JCOLLECTION123456789AB",
+                                  "collection_id": "01JCOLLECTION123456789AB",
                                   "description_preview": "An AI agent that analyzes documents and extracts key insights...",
                                   "created_at": "2026-01-01T00:00:00.000Z",
                                   "updated_at": "2026-01-15T16:00:00.000Z"
@@ -15643,10 +15891,10 @@
                           }
                         },
                         "required": [
-                          "pi",
+                          "id",
                           "label",
                           "score",
-                          "collection_pi"
+                          "collection_id"
                         ]
                       }
                     },
@@ -15723,13 +15971,16 @@
           "Search"
         ],
         "summary": "Search entities within collection(s)",
-        "description": "Search for entities within one or more collections using semantic text search.\n\nProvide either `collection_pi` for a single collection or `collection_pis` for multiple collections (searched in parallel).\n\nUse `per_collection_limit` to ensure result diversity when searching multiple collections.\n\n**Entity Expansion:**\n\nUse `expand` in the request body to fetch entity data inline with search results:\n\n- **`expand: \"preview\"` (default)**: Adds `entity_preview` with fresh lightweight data (id, type, label, timestamps)\n- **`expand: \"full\"`**: Adds `entity` with complete manifest including all properties and relationships\n- **`expand: \"none\"`**: Returns search metadata only (fastest, lowest bandwidth)\n\nPreview mode is recommended for most use cases. Full expansion can result in large payloads.\nGracefully handles deleted or inaccessible entities (returns results without expansion data).\n\n---\n**Permission:** `search:query`  \n**Auth:** required",
+        "description": "Search for entities within one or more collections using semantic text search.\n\nProvide either `collection_pi` for a single collection or `collection_ids` for multiple collections (searched in parallel).\n\nUse `per_collection_limit` to ensure result diversity when searching multiple collections.\n\n**Entity Expansion:**\n\nUse `expand` in the request body to fetch entity data inline with search results:\n\n- **`expand: \"preview\"` (default)**: Adds `entity_preview` with fresh lightweight data (id, type, label, timestamps)\n- **`expand: \"full\"`**: Adds `entity` with complete manifest including all properties and relationships\n- **`expand: \"none\"`**: Returns search metadata only (fastest, lowest bandwidth)\n\nPreview mode is recommended for most use cases. Full expansion can result in large payloads.\nGracefully handles deleted or inaccessible entities (returns results without expansion data).\n\n---\n**Permission:** `search:query`  \n**Auth:** required",
         "x-arke-action": "search:query",
         "x-arke-auth": "required",
         "x-arke-tier": "external",
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "requestBody": {
@@ -15738,17 +15989,17 @@
               "schema": {
                 "type": "object",
                 "properties": {
-                  "collection_pi": {
+                  "collection_id": {
                     "type": "string",
-                    "description": "Single collection PI to search within"
+                    "description": "Single collection ID to search within"
                   },
-                  "collection_pis": {
+                  "collection_ids": {
                     "type": "array",
                     "items": {
                       "type": "string"
                     },
                     "maxItems": 20,
-                    "description": "Multiple collection PIs to search (max 20)"
+                    "description": "Multiple collection IDs to search (max 20)"
                   },
                   "query": {
                     "type": "string",
@@ -15770,6 +16021,19 @@
                     },
                     "description": "Filter by entity types"
                   },
+                  "filter": {
+                    "type": "object",
+                    "additionalProperties": {
+                      "nullable": true
+                    },
+                    "description": "Filter by indexed metadata properties.\n\n**Filterable Properties:**\nOnly underscore-prefixed properties (`_year`, `_class`, etc.) are indexed as filterable metadata.\n\n**Operators:**\n| Operator | Description | Example |\n|----------|-------------|---------|\n| `$eq` | Equals | `{ \"_year\": { \"$eq\": 1905 } }` |\n| `$ne` | Not equals | `{ \"_class\": { \"$ne\": \"draft\" } }` |\n| `$gt` | Greater than | `{ \"_year\": { \"$gt\": 1900 } }` |\n| `$gte` | Greater than or equal | `{ \"_year\": { \"$gte\": 1900 } }` |\n| `$lt` | Less than | `{ \"_year\": { \"$lt\": 2000 } }` |\n| `$lte` | Less than or equal | `{ \"_year\": { \"$lte\": 2000 } }` |\n| `$in` | In array | `{ \"_class\": { \"$in\": [\"letter\", \"memo\"] } }` |\n| `$nin` | Not in array | `{ \"_class\": { \"$nin\": [\"draft\"] } }` |\n| `$exists` | Property exists | `{ \"_ocr_text\": { \"$exists\": true } }` |\n\n**Logical Operators:**\n| Operator | Description | Example |\n|----------|-------------|---------|\n| `$and` | All conditions must match | `{ \"$and\": [{ \"_year\": { \"$gt\": 1900 } }, { \"_year\": { \"$lt\": 2000 } }] }` |\n| `$or` | Any condition must match | `{ \"$or\": [{ \"_class\": \"letter\" }, { \"_class\": \"memo\" }] }` |\n\n**Built-in Fields (always available):**\n- `type` - Entity type\n- `created_at` - ISO timestamp string\n- `updated_at` - ISO timestamp string\n\n**Example - Find letters from 1800-1900:**\n```json\n{\n  \"$and\": [\n    { \"type\": { \"$eq\": \"letter\" } },\n    { \"_year\": { \"$gte\": 1800 } },\n    { \"_year\": { \"$lte\": 1900 } }\n  ]\n}\n```",
+                    "example": {
+                      "_year": {
+                        "$gt": 1800
+                      },
+                      "type": "letter"
+                    }
+                  },
                   "per_collection_limit": {
                     "type": "number",
                     "minimum": 1,
@@ -15807,7 +16071,7 @@
                       "items": {
                         "type": "object",
                         "properties": {
-                          "pi": {
+                          "id": {
                             "type": "string"
                           },
                           "label": {
@@ -15819,7 +16083,7 @@
                           "score": {
                             "type": "number"
                           },
-                          "collection_pi": {
+                          "collection_id": {
                             "type": "string"
                           },
                           "created_at": {
@@ -15839,7 +16103,7 @@
                                   "id": "01KENTITY123456789ABCDEFGH",
                                   "type": "document",
                                   "label": "Research Findings Report",
-                                  "collection_pi": "01JCOLLECTION123456789AB",
+                                  "collection_id": "01JCOLLECTION123456789AB",
                                   "description_preview": "Detailed analysis of experimental results...",
                                   "created_at": "2026-01-10T00:00:00.000Z",
                                   "updated_at": "2026-01-14T09:00:00.000Z"
@@ -15859,18 +16123,18 @@
                           }
                         },
                         "required": [
-                          "pi",
+                          "id",
                           "label",
                           "type",
                           "score",
-                          "collection_pi"
+                          "collection_id"
                         ]
                       }
                     },
                     "metadata": {
                       "type": "object",
                       "properties": {
-                        "collection_pis": {
+                        "collection_ids": {
                           "type": "array",
                           "items": {
                             "type": "string"
@@ -15887,7 +16151,7 @@
                         }
                       },
                       "required": [
-                        "collection_pis",
+                        "collection_ids",
                         "query",
                         "collections_searched",
                         "result_count"
@@ -15958,6 +16222,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "requestBody": {
@@ -15986,6 +16253,19 @@
                     },
                     "description": "Filter by entity types"
                   },
+                  "filter": {
+                    "type": "object",
+                    "additionalProperties": {
+                      "nullable": true
+                    },
+                    "description": "Filter by indexed metadata properties.\n\n**Filterable Properties:**\nOnly underscore-prefixed properties (`_year`, `_class`, etc.) are indexed as filterable metadata.\n\n**Operators:**\n| Operator | Description | Example |\n|----------|-------------|---------|\n| `$eq` | Equals | `{ \"_year\": { \"$eq\": 1905 } }` |\n| `$ne` | Not equals | `{ \"_class\": { \"$ne\": \"draft\" } }` |\n| `$gt` | Greater than | `{ \"_year\": { \"$gt\": 1900 } }` |\n| `$gte` | Greater than or equal | `{ \"_year\": { \"$gte\": 1900 } }` |\n| `$lt` | Less than | `{ \"_year\": { \"$lt\": 2000 } }` |\n| `$lte` | Less than or equal | `{ \"_year\": { \"$lte\": 2000 } }` |\n| `$in` | In array | `{ \"_class\": { \"$in\": [\"letter\", \"memo\"] } }` |\n| `$nin` | Not in array | `{ \"_class\": { \"$nin\": [\"draft\"] } }` |\n| `$exists` | Property exists | `{ \"_ocr_text\": { \"$exists\": true } }` |\n\n**Logical Operators:**\n| Operator | Description | Example |\n|----------|-------------|---------|\n| `$and` | All conditions must match | `{ \"$and\": [{ \"_year\": { \"$gt\": 1900 } }, { \"_year\": { \"$lt\": 2000 } }] }` |\n| `$or` | Any condition must match | `{ \"$or\": [{ \"_class\": \"letter\" }, { \"_class\": \"memo\" }] }` |\n\n**Built-in Fields (always available):**\n- `type` - Entity type\n- `created_at` - ISO timestamp string\n- `updated_at` - ISO timestamp string\n\n**Example - Find letters from 1800-1900:**\n```json\n{\n  \"$and\": [\n    { \"type\": { \"$eq\": \"letter\" } },\n    { \"_year\": { \"$gte\": 1800 } },\n    { \"_year\": { \"$lte\": 1900 } }\n  ]\n}\n```",
+                    "example": {
+                      "_year": {
+                        "$gt": 1800
+                      },
+                      "type": "letter"
+                    }
+                  },
                   "collection_limit": {
                     "type": "number",
                     "minimum": 1,
@@ -16031,7 +16311,7 @@
                       "items": {
                         "type": "object",
                         "properties": {
-                          "pi": {
+                          "id": {
                             "type": "string"
                           },
                           "label": {
@@ -16043,7 +16323,7 @@
                           "score": {
                             "type": "number"
                           },
-                          "collection_pi": {
+                          "collection_id": {
                             "type": "string"
                           },
                           "created_at": {
@@ -16063,7 +16343,7 @@
                                   "id": "01KENTITY123456789ABCDEFGH",
                                   "type": "file",
                                   "label": "Discovered Document.pdf",
-                                  "collection_pi": "01JCOLLECTION123456789AB",
+                                  "collection_id": "01JCOLLECTION123456789AB",
                                   "description_preview": "A document discovered through semantic search...",
                                   "created_at": "2026-01-08T00:00:00.000Z",
                                   "updated_at": "2026-01-12T14:00:00.000Z"
@@ -16083,11 +16363,11 @@
                           }
                         },
                         "required": [
-                          "pi",
+                          "id",
                           "label",
                           "type",
                           "score",
-                          "collection_pi"
+                          "collection_id"
                         ]
                       }
                     },
@@ -16175,6 +16455,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "requestBody": {
@@ -16260,6 +16543,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "responses": {
@@ -16302,6 +16588,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "responses": {
@@ -16368,6 +16657,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "responses": {