@arke-institute/sdk 3.6.6 → 3.6.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/dist/generated/index.d.cts +322 -81
  2. package/dist/generated/index.d.ts +322 -81
  3. package/dist/index.cjs.map +1 -1
  4. package/dist/index.js.map +1 -1
  5. package/dist/operations/index.cjs +2 -1
  6. package/dist/operations/index.cjs.map +1 -1
  7. package/dist/operations/index.js +2 -1
  8. package/dist/operations/index.js.map +1 -1
  9. package/openapi/spec.json +295 -161
  10. package/openapi/version.json +1 -1
  11. package/package.json +1 -1
package/openapi/spec.json CHANGED
@@ -237,10 +237,10 @@
237
237
  ],
238
238
  "description": "Identity type"
239
239
  },
240
- "pi": {
240
+ "id": {
241
241
  "type": "string",
242
242
  "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
243
- "description": "User entity PI (persistent identifier)",
243
+ "description": "User entity ID",
244
244
  "example": "01J1SHMAE10000000000000000"
245
245
  },
246
246
  "auth_method": {
@@ -281,7 +281,7 @@
281
281
  },
282
282
  "required": [
283
283
  "type",
284
- "pi",
284
+ "id",
285
285
  "auth_method"
286
286
  ]
287
287
  },
@@ -295,10 +295,10 @@
295
295
  ],
296
296
  "description": "Identity type"
297
297
  },
298
- "pi": {
298
+ "id": {
299
299
  "type": "string",
300
300
  "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
301
- "description": "Agent entity PI (persistent identifier)",
301
+ "description": "Agent entity ID",
302
302
  "example": "01J1AGENTID000000000000000"
303
303
  },
304
304
  "auth_method": {
@@ -309,10 +309,10 @@
309
309
  "description": "How this identity was authenticated",
310
310
  "example": "api_key"
311
311
  },
312
- "owner_pi": {
312
+ "owner_id": {
313
313
  "type": "string",
314
314
  "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
315
- "description": "Entity PI of the agent owner",
315
+ "description": "Entity ID of the agent owner",
316
316
  "example": "01J1OWNERID0000000000000000"
317
317
  },
318
318
  "key_prefix": {
@@ -328,9 +328,9 @@
328
328
  },
329
329
  "required": [
330
330
  "type",
331
- "pi",
331
+ "id",
332
332
  "auth_method",
333
- "owner_pi",
333
+ "owner_id",
334
334
  "key_prefix",
335
335
  "key_expires_at"
336
336
  ]
@@ -710,9 +710,9 @@
710
710
  "UserCollectionItem": {
711
711
  "type": "object",
712
712
  "properties": {
713
- "pi": {
713
+ "id": {
714
714
  "type": "string",
715
- "description": "Collection persistent identifier",
715
+ "description": "Collection ID",
716
716
  "example": "01JCOLLECTION123456789AB"
717
717
  },
718
718
  "label": {
@@ -732,7 +732,7 @@
732
732
  }
733
733
  },
734
734
  "required": [
735
- "pi",
735
+ "id",
736
736
  "label",
737
737
  "predicate",
738
738
  "created_at"
@@ -806,7 +806,7 @@
806
806
  "description": "Entity label (from properties.label, filename, or name)",
807
807
  "example": "Research Paper.pdf"
808
808
  },
809
- "collection_pi": {
809
+ "collection_id": {
810
810
  "type": "string",
811
811
  "description": "Collection ID this entity belongs to",
812
812
  "example": "01JCOLLECTION123456789ABCD"
@@ -844,7 +844,7 @@
844
844
  "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
845
845
  "type": "file",
846
846
  "label": "Research Paper.pdf",
847
- "collection_pi": "01JCOLLECTION123456789AB",
847
+ "collection_id": "01JCOLLECTION123456789AB",
848
848
  "description_preview": "A comprehensive study on distributed systems architecture...",
849
849
  "created_at": "2026-01-12T00:00:00.000Z",
850
850
  "updated_at": "2026-01-12T10:30:00.000Z"
@@ -853,10 +853,10 @@
853
853
  "SearchResultItem": {
854
854
  "type": "object",
855
855
  "properties": {
856
- "pi": {
856
+ "id": {
857
857
  "type": "string",
858
858
  "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
859
- "description": "Entity persistent identifier",
859
+ "description": "Entity ID",
860
860
  "example": "01KDETYWYWM0MJVKM8DK3AEXPY"
861
861
  },
862
862
  "type": {
@@ -869,7 +869,7 @@
869
869
  "description": "Entity label/name",
870
870
  "example": "Research Paper.pdf"
871
871
  },
872
- "collection_pi": {
872
+ "collection_id": {
873
873
  "type": "string",
874
874
  "nullable": true,
875
875
  "description": "Collection this entity belongs to (null for public-domain)",
@@ -905,10 +905,10 @@
905
905
  }
906
906
  },
907
907
  "required": [
908
- "pi",
908
+ "id",
909
909
  "type",
910
910
  "label",
911
- "collection_pi",
911
+ "collection_id",
912
912
  "score"
913
913
  ]
914
914
  },
@@ -1827,10 +1827,10 @@
1827
1827
  "CollectionEntitySummary": {
1828
1828
  "type": "object",
1829
1829
  "properties": {
1830
- "pi": {
1830
+ "id": {
1831
1831
  "type": "string",
1832
1832
  "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
1833
- "description": "Entity persistent identifier"
1833
+ "description": "Entity ID"
1834
1834
  },
1835
1835
  "type": {
1836
1836
  "type": "string",
@@ -1874,7 +1874,7 @@
1874
1874
  }
1875
1875
  },
1876
1876
  "required": [
1877
- "pi",
1877
+ "id",
1878
1878
  "type",
1879
1879
  "label",
1880
1880
  "created_at",
@@ -2695,6 +2695,11 @@
2695
2695
  "description": "Relationship to remove"
2696
2696
  },
2697
2697
  "description": "Relationships to remove"
2698
+ },
2699
+ "sync_index": {
2700
+ "type": "boolean",
2701
+ "default": false,
2702
+ "description": "Wait for collection index update before returning. Use when checking index immediately after update."
2698
2703
  }
2699
2704
  },
2700
2705
  "required": [
@@ -2762,6 +2767,11 @@
2762
2767
  "maxLength": 500,
2763
2768
  "description": "Reason for deleting the entity",
2764
2769
  "example": "Duplicate entry"
2770
+ },
2771
+ "sync_index": {
2772
+ "type": "boolean",
2773
+ "default": false,
2774
+ "description": "Wait for collection index removal before returning. Use when checking index immediately after deletion."
2765
2775
  }
2766
2776
  },
2767
2777
  "required": [
@@ -3034,7 +3044,7 @@
3034
3044
  "TreeNode": {
3035
3045
  "type": "object",
3036
3046
  "properties": {
3037
- "pi": {
3047
+ "id": {
3038
3048
  "type": "string",
3039
3049
  "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
3040
3050
  "description": "Entity ID (ULID format)",
@@ -3061,7 +3071,7 @@
3061
3071
  }
3062
3072
  },
3063
3073
  "required": [
3064
- "pi",
3074
+ "id",
3065
3075
  "label",
3066
3076
  "type",
3067
3077
  "depth",
@@ -5771,29 +5781,54 @@
5771
5781
  "type": "object",
5772
5782
  "properties": {
5773
5783
  "klados": {
5774
- "type": "object",
5775
- "properties": {
5776
- "pi": {
5777
- "type": "string",
5778
- "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$"
5779
- },
5780
- "type": {
5781
- "type": "string"
5782
- },
5783
- "label": {
5784
- "type": "string"
5784
+ "anyOf": [
5785
+ {
5786
+ "type": "object",
5787
+ "properties": {
5788
+ "id": {
5789
+ "type": "string",
5790
+ "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$"
5791
+ },
5792
+ "type": {
5793
+ "type": "string"
5794
+ },
5795
+ "label": {
5796
+ "type": "string"
5797
+ },
5798
+ "description": {
5799
+ "type": "string"
5800
+ }
5801
+ },
5802
+ "required": [
5803
+ "id"
5804
+ ]
5785
5805
  },
5786
- "description": {
5787
- "type": "string"
5806
+ {
5807
+ "type": "object",
5808
+ "properties": {
5809
+ "pi": {
5810
+ "type": "string",
5811
+ "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$"
5812
+ },
5813
+ "type": {
5814
+ "type": "string"
5815
+ },
5816
+ "label": {
5817
+ "type": "string"
5818
+ },
5819
+ "description": {
5820
+ "type": "string"
5821
+ }
5822
+ },
5823
+ "required": [
5824
+ "pi"
5825
+ ]
5788
5826
  }
5789
- },
5790
- "required": [
5791
- "pi"
5792
5827
  ],
5793
5828
  "description": "Reference to the klados entity to invoke for this step",
5794
5829
  "title": "KladosRef",
5795
5830
  "example": {
5796
- "pi": "01KEXAMPLE123456789012345",
5831
+ "id": "01KEXAMPLE123456789012345",
5797
5832
  "type": "klados",
5798
5833
  "label": "OCR Processor"
5799
5834
  }
@@ -5940,7 +5975,7 @@
5940
5975
  "example": {
5941
5976
  "extract": {
5942
5977
  "klados": {
5943
- "pi": "01KKLADOSA12345678901234",
5978
+ "id": "01KKLADOSA12345678901234",
5944
5979
  "type": "klados"
5945
5980
  },
5946
5981
  "then": {
@@ -5949,7 +5984,7 @@
5949
5984
  },
5950
5985
  "summarize": {
5951
5986
  "klados": {
5952
- "pi": "01KKLADOSB12345678901234",
5987
+ "id": "01KKLADOSB12345678901234",
5953
5988
  "type": "klados"
5954
5989
  },
5955
5990
  "then": {
@@ -6213,29 +6248,54 @@
6213
6248
  "type": "object",
6214
6249
  "properties": {
6215
6250
  "klados": {
6216
- "type": "object",
6217
- "properties": {
6218
- "pi": {
6219
- "type": "string",
6220
- "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$"
6221
- },
6222
- "type": {
6223
- "type": "string"
6224
- },
6225
- "label": {
6226
- "type": "string"
6251
+ "anyOf": [
6252
+ {
6253
+ "type": "object",
6254
+ "properties": {
6255
+ "id": {
6256
+ "type": "string",
6257
+ "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$"
6258
+ },
6259
+ "type": {
6260
+ "type": "string"
6261
+ },
6262
+ "label": {
6263
+ "type": "string"
6264
+ },
6265
+ "description": {
6266
+ "type": "string"
6267
+ }
6268
+ },
6269
+ "required": [
6270
+ "id"
6271
+ ]
6227
6272
  },
6228
- "description": {
6229
- "type": "string"
6273
+ {
6274
+ "type": "object",
6275
+ "properties": {
6276
+ "pi": {
6277
+ "type": "string",
6278
+ "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$"
6279
+ },
6280
+ "type": {
6281
+ "type": "string"
6282
+ },
6283
+ "label": {
6284
+ "type": "string"
6285
+ },
6286
+ "description": {
6287
+ "type": "string"
6288
+ }
6289
+ },
6290
+ "required": [
6291
+ "pi"
6292
+ ]
6230
6293
  }
6231
- },
6232
- "required": [
6233
- "pi"
6234
6294
  ],
6235
6295
  "description": "Reference to the klados entity to invoke for this step",
6236
6296
  "title": "KladosRef",
6237
6297
  "example": {
6238
- "pi": "01KEXAMPLE123456789012345",
6298
+ "id": "01KEXAMPLE123456789012345",
6239
6299
  "type": "klados",
6240
6300
  "label": "OCR Processor"
6241
6301
  }
@@ -6382,7 +6442,7 @@
6382
6442
  "example": {
6383
6443
  "extract": {
6384
6444
  "klados": {
6385
- "pi": "01KKLADOSA12345678901234",
6445
+ "id": "01KKLADOSA12345678901234",
6386
6446
  "type": "klados"
6387
6447
  },
6388
6448
  "then": {
@@ -6391,7 +6451,7 @@
6391
6451
  },
6392
6452
  "summarize": {
6393
6453
  "klados": {
6394
- "pi": "01KKLADOSB12345678901234",
6454
+ "id": "01KKLADOSB12345678901234",
6395
6455
  "type": "klados"
6396
6456
  },
6397
6457
  "then": {
@@ -6848,7 +6908,7 @@
6848
6908
  "description": "Auto-increment event ID (use as cursor)",
6849
6909
  "example": 12346
6850
6910
  },
6851
- "pi": {
6911
+ "entity_id": {
6852
6912
  "type": "string",
6853
6913
  "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
6854
6914
  "description": "Entity ID that changed",
@@ -6868,7 +6928,7 @@
6868
6928
  },
6869
6929
  "required": [
6870
6930
  "id",
6871
- "pi",
6931
+ "entity_id",
6872
6932
  "cid",
6873
6933
  "ts"
6874
6934
  ]
@@ -6903,7 +6963,7 @@
6903
6963
  "PathEdge": {
6904
6964
  "type": "object",
6905
6965
  "properties": {
6906
- "subject_pi": {
6966
+ "subject_id": {
6907
6967
  "type": "string",
6908
6968
  "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
6909
6969
  "description": "Source entity PI",
@@ -6941,7 +7001,7 @@
6941
7001
  "type": "string",
6942
7002
  "description": "Relationship predicate"
6943
7003
  },
6944
- "object_pi": {
7004
+ "object_id": {
6945
7005
  "type": "string",
6946
7006
  "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
6947
7007
  "description": "Target entity PI",
@@ -6977,36 +7037,36 @@
6977
7037
  }
6978
7038
  },
6979
7039
  "required": [
6980
- "subject_pi",
7040
+ "subject_id",
6981
7041
  "subject_label",
6982
7042
  "subject_type",
6983
7043
  "predicate",
6984
- "object_pi",
7044
+ "object_id",
6985
7045
  "object_label",
6986
7046
  "object_type"
6987
7047
  ],
6988
7048
  "example": {
6989
- "subject_pi": "01KE4ZY69F9R40E88PK9S0TQRQ",
7049
+ "subject_id": "01KE4ZY69F9R40E88PK9S0TQRQ",
6990
7050
  "subject_label": "Project Folder",
6991
7051
  "subject_type": "folder",
6992
7052
  "subject_preview": {
6993
7053
  "id": "01KE4ZY69F9R40E88PK9S0TQRQ",
6994
7054
  "type": "folder",
6995
7055
  "label": "Project Folder",
6996
- "collection_pi": "01JCOLLECTION123456789ABCD",
7056
+ "collection_id": "01JCOLLECTION123456789ABCD",
6997
7057
  "description_preview": "Main project folder containing research documents...",
6998
7058
  "created_at": "2025-01-10T08:00:00.000Z",
6999
7059
  "updated_at": "2025-01-18T16:45:00.000Z"
7000
7060
  },
7001
7061
  "predicate": "contains",
7002
- "object_pi": "01KE506KZGD8M2P1XK3VNQT4YR",
7062
+ "object_id": "01KE506KZGD8M2P1XK3VNQT4YR",
7003
7063
  "object_label": "Research Paper.pdf",
7004
7064
  "object_type": "file",
7005
7065
  "object_preview": {
7006
7066
  "id": "01KE506KZGD8M2P1XK3VNQT4YR",
7007
7067
  "type": "file",
7008
7068
  "label": "Research Paper.pdf",
7009
- "collection_pi": "01JCOLLECTION123456789ABCD",
7069
+ "collection_id": "01JCOLLECTION123456789ABCD",
7010
7070
  "description_preview": "Analysis of entity management patterns and best practices...",
7011
7071
  "created_at": "2025-01-15T10:00:00.000Z",
7012
7072
  "updated_at": "2025-01-20T14:30:00.000Z"
@@ -7016,13 +7076,13 @@
7016
7076
  "PathResult": {
7017
7077
  "type": "object",
7018
7078
  "properties": {
7019
- "source_pi": {
7079
+ "source_id": {
7020
7080
  "type": "string",
7021
7081
  "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
7022
7082
  "description": "Entity ID (ULID format)",
7023
7083
  "example": "01KDETYWYWM0MJVKM8DK3AEXPY"
7024
7084
  },
7025
- "target_pi": {
7085
+ "target_id": {
7026
7086
  "type": "string",
7027
7087
  "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
7028
7088
  "description": "Entity ID (ULID format)",
@@ -7040,8 +7100,8 @@
7040
7100
  }
7041
7101
  },
7042
7102
  "required": [
7043
- "source_pi",
7044
- "target_pi",
7103
+ "source_id",
7104
+ "target_id",
7045
7105
  "length",
7046
7106
  "edges"
7047
7107
  ]
@@ -7068,7 +7128,7 @@
7068
7128
  "PathsBetweenRequest": {
7069
7129
  "type": "object",
7070
7130
  "properties": {
7071
- "source_pis": {
7131
+ "source_ids": {
7072
7132
  "type": "array",
7073
7133
  "items": {
7074
7134
  "type": "string",
@@ -7082,7 +7142,7 @@
7082
7142
  "01KE4ZY69F9R40E88PK9S0TQRQ"
7083
7143
  ]
7084
7144
  },
7085
- "target_pis": {
7145
+ "target_ids": {
7086
7146
  "type": "array",
7087
7147
  "items": {
7088
7148
  "type": "string",
@@ -7125,20 +7185,20 @@
7125
7185
  }
7126
7186
  },
7127
7187
  "required": [
7128
- "source_pis",
7129
- "target_pis"
7188
+ "source_ids",
7189
+ "target_ids"
7130
7190
  ]
7131
7191
  },
7132
7192
  "ReachableResult": {
7133
7193
  "type": "object",
7134
7194
  "properties": {
7135
- "source_pi": {
7195
+ "source_id": {
7136
7196
  "type": "string",
7137
7197
  "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
7138
7198
  "description": "Entity ID (ULID format)",
7139
7199
  "example": "01KDETYWYWM0MJVKM8DK3AEXPY"
7140
7200
  },
7141
- "target_pi": {
7201
+ "target_id": {
7142
7202
  "type": "string",
7143
7203
  "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
7144
7204
  "description": "Entity ID (ULID format)",
@@ -7182,16 +7242,16 @@
7182
7242
  }
7183
7243
  },
7184
7244
  "required": [
7185
- "source_pi",
7186
- "target_pi",
7245
+ "source_id",
7246
+ "target_id",
7187
7247
  "target_label",
7188
7248
  "target_type",
7189
7249
  "length",
7190
7250
  "edges"
7191
7251
  ],
7192
7252
  "example": {
7193
- "source_pi": "01KE4ZY69F9R40E88PK9S0TQRQ",
7194
- "target_pi": "01KE506KZGD8M2P1XK3VNQT4YR",
7253
+ "source_id": "01KE4ZY69F9R40E88PK9S0TQRQ",
7254
+ "target_id": "01KE506KZGD8M2P1XK3VNQT4YR",
7195
7255
  "target_label": "Research Paper.pdf",
7196
7256
  "target_type": "file",
7197
7257
  "length": 1,
@@ -7200,7 +7260,7 @@
7200
7260
  "id": "01KE506KZGD8M2P1XK3VNQT4YR",
7201
7261
  "type": "file",
7202
7262
  "label": "Research Paper.pdf",
7203
- "collection_pi": "01JCOLLECTION123456789ABCD",
7263
+ "collection_id": "01JCOLLECTION123456789ABCD",
7204
7264
  "description_preview": "Analysis of entity management patterns and best practices...",
7205
7265
  "created_at": "2025-01-15T10:00:00.000Z",
7206
7266
  "updated_at": "2025-01-20T14:30:00.000Z"
@@ -7229,7 +7289,7 @@
7229
7289
  "PathsReachableRequest": {
7230
7290
  "type": "object",
7231
7291
  "properties": {
7232
- "source_pis": {
7292
+ "source_ids": {
7233
7293
  "type": "array",
7234
7294
  "items": {
7235
7295
  "type": "string",
@@ -7278,7 +7338,7 @@
7278
7338
  }
7279
7339
  },
7280
7340
  "required": [
7281
- "source_pis",
7341
+ "source_ids",
7282
7342
  "target_type"
7283
7343
  ]
7284
7344
  },
@@ -7295,7 +7355,7 @@
7295
7355
  "predicate": {
7296
7356
  "type": "string"
7297
7357
  },
7298
- "peer_pi": {
7358
+ "peer_id": {
7299
7359
  "type": "string",
7300
7360
  "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
7301
7361
  "description": "Entity ID (ULID format)",
@@ -7337,7 +7397,7 @@
7337
7397
  "required": [
7338
7398
  "direction",
7339
7399
  "predicate",
7340
- "peer_pi",
7400
+ "peer_id",
7341
7401
  "peer_type",
7342
7402
  "peer_label",
7343
7403
  "properties"
@@ -7345,7 +7405,7 @@
7345
7405
  "example": {
7346
7406
  "direction": "outgoing",
7347
7407
  "predicate": "contains",
7348
- "peer_pi": "01KE506KZGD8M2P1XK3VNQT4YR",
7408
+ "peer_id": "01KE506KZGD8M2P1XK3VNQT4YR",
7349
7409
  "peer_type": "file",
7350
7410
  "peer_label": "Research Paper.pdf",
7351
7411
  "properties": {},
@@ -7353,7 +7413,7 @@
7353
7413
  "id": "01KE506KZGD8M2P1XK3VNQT4YR",
7354
7414
  "type": "file",
7355
7415
  "label": "Research Paper.pdf",
7356
- "collection_pi": "01KE4ZY69F9R40E88PK9S0TQRQ",
7416
+ "collection_id": "01KE4ZY69F9R40E88PK9S0TQRQ",
7357
7417
  "description_preview": "Analysis of entity management patterns and best practices...",
7358
7418
  "created_at": "2025-01-15T10:00:00.000Z",
7359
7419
  "updated_at": "2025-01-20T14:30:00.000Z"
@@ -7363,7 +7423,7 @@
7363
7423
  "GraphEntityResponse": {
7364
7424
  "type": "object",
7365
7425
  "properties": {
7366
- "pi": {
7426
+ "id": {
7367
7427
  "type": "string",
7368
7428
  "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
7369
7429
  "description": "Entity ID (ULID format)",
@@ -7375,7 +7435,7 @@
7375
7435
  "label": {
7376
7436
  "type": "string"
7377
7437
  },
7378
- "collection_pi": {
7438
+ "collection_id": {
7379
7439
  "type": "string",
7380
7440
  "nullable": true
7381
7441
  },
@@ -7395,26 +7455,26 @@
7395
7455
  }
7396
7456
  },
7397
7457
  "required": [
7398
- "pi",
7458
+ "id",
7399
7459
  "type",
7400
7460
  "label",
7401
- "collection_pi",
7461
+ "collection_id",
7402
7462
  "created_at",
7403
7463
  "updated_at",
7404
7464
  "relationships"
7405
7465
  ],
7406
7466
  "example": {
7407
- "pi": "01KE4ZY69F9R40E88PK9S0TQRQ",
7467
+ "id": "01KE4ZY69F9R40E88PK9S0TQRQ",
7408
7468
  "type": "folder",
7409
7469
  "label": "Project Folder",
7410
- "collection_pi": "01JCOLLECTION123456789ABCD",
7470
+ "collection_id": "01JCOLLECTION123456789ABCD",
7411
7471
  "created_at": "2025-01-10T08:00:00.000Z",
7412
7472
  "updated_at": "2025-01-18T16:45:00.000Z",
7413
7473
  "relationships": [
7414
7474
  {
7415
7475
  "direction": "outgoing",
7416
7476
  "predicate": "contains",
7417
- "peer_pi": "01KE506KZGD8M2P1XK3VNQT4YR",
7477
+ "peer_id": "01KE506KZGD8M2P1XK3VNQT4YR",
7418
7478
  "peer_type": "file",
7419
7479
  "peer_label": "Research Paper.pdf",
7420
7480
  "properties": {},
@@ -7422,7 +7482,7 @@
7422
7482
  "id": "01KE506KZGD8M2P1XK3VNQT4YR",
7423
7483
  "type": "file",
7424
7484
  "label": "Research Paper.pdf",
7425
- "collection_pi": "01JCOLLECTION123456789ABCD",
7485
+ "collection_id": "01JCOLLECTION123456789ABCD",
7426
7486
  "description_preview": "Analysis of entity management patterns and best practices...",
7427
7487
  "created_at": "2025-01-15T10:00:00.000Z",
7428
7488
  "updated_at": "2025-01-20T14:30:00.000Z"
@@ -7581,7 +7641,7 @@
7581
7641
  "entity": {
7582
7642
  "type": "object",
7583
7643
  "properties": {
7584
- "pi": {
7644
+ "id": {
7585
7645
  "type": "string",
7586
7646
  "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
7587
7647
  "description": "Entity ID (ULID format)",
@@ -7595,7 +7655,7 @@
7595
7655
  "type": "string",
7596
7656
  "example": "Albert Einstein"
7597
7657
  },
7598
- "collection_pi": {
7658
+ "collection_id": {
7599
7659
  "type": "string",
7600
7660
  "nullable": true,
7601
7661
  "example": "01JCOLL_RESEARCH"
@@ -7622,22 +7682,22 @@
7622
7682
  }
7623
7683
  },
7624
7684
  "required": [
7625
- "pi",
7685
+ "id",
7626
7686
  "type",
7627
7687
  "label",
7628
- "collection_pi"
7688
+ "collection_id"
7629
7689
  ],
7630
7690
  "description": "Query result entity with optional expansion data",
7631
7691
  "example": {
7632
- "pi": "01KE4ZY69F9R40E88PK9S0TQRQ",
7692
+ "id": "01KE4ZY69F9R40E88PK9S0TQRQ",
7633
7693
  "type": "person",
7634
7694
  "label": "Albert Einstein",
7635
- "collection_pi": "01JCOLL_RESEARCH",
7695
+ "collection_id": "01JCOLL_RESEARCH",
7636
7696
  "preview_data": {
7637
7697
  "id": "01KE4ZY69F9R40E88PK9S0TQRQ",
7638
7698
  "type": "person",
7639
7699
  "label": "Albert Einstein",
7640
- "collection_pi": "01JCOLL_RESEARCH",
7700
+ "collection_id": "01JCOLL_RESEARCH",
7641
7701
  "description_preview": "German-born theoretical physicist who developed the theory of relativity...",
7642
7702
  "created_at": "2025-01-15T10:00:00.000Z",
7643
7703
  "updated_at": "2025-01-20T14:30:00.000Z"
@@ -7665,15 +7725,15 @@
7665
7725
  "description": "A single query result with entity, path, and score",
7666
7726
  "example": {
7667
7727
  "entity": {
7668
- "pi": "01KE4ZY69F9R40E88PK9S0TQRQ",
7728
+ "id": "01KE4ZY69F9R40E88PK9S0TQRQ",
7669
7729
  "type": "file",
7670
7730
  "label": "Theory of Relativity.pdf",
7671
- "collection_pi": "01JCOLL_RESEARCH",
7731
+ "collection_id": "01JCOLL_RESEARCH",
7672
7732
  "preview_data": {
7673
7733
  "id": "01KE4ZY69F9R40E88PK9S0TQRQ",
7674
7734
  "type": "file",
7675
7735
  "label": "Theory of Relativity.pdf",
7676
- "collection_pi": "01JCOLL_RESEARCH",
7736
+ "collection_id": "01JCOLL_RESEARCH",
7677
7737
  "description_preview": "Seminal paper on special and general relativity...",
7678
7738
  "created_at": "2025-01-10T08:00:00.000Z",
7679
7739
  "updated_at": "2025-01-10T08:00:00.000Z"
@@ -7748,6 +7808,18 @@
7748
7808
  ],
7749
7809
  "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)",
7750
7810
  "example": "preview"
7811
+ },
7812
+ "filter": {
7813
+ "type": "object",
7814
+ "additionalProperties": {
7815
+ "nullable": true
7816
+ },
7817
+ "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```",
7818
+ "example": {
7819
+ "_year": {
7820
+ "$gt": 1800
7821
+ }
7822
+ }
7751
7823
  }
7752
7824
  },
7753
7825
  "required": [
@@ -8152,7 +8224,7 @@
8152
8224
  "AttestationResponse": {
8153
8225
  "type": "object",
8154
8226
  "properties": {
8155
- "pi": {
8227
+ "id": {
8156
8228
  "type": "string",
8157
8229
  "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
8158
8230
  "description": "Entity ID (ULID format)",
@@ -8189,7 +8261,7 @@
8189
8261
  }
8190
8262
  },
8191
8263
  "required": [
8192
- "pi",
8264
+ "id",
8193
8265
  "ver",
8194
8266
  "cid",
8195
8267
  "arweave_tx",
@@ -8200,7 +8272,7 @@
8200
8272
  "AttestationPendingResponse": {
8201
8273
  "type": "object",
8202
8274
  "properties": {
8203
- "pi": {
8275
+ "id": {
8204
8276
  "type": "string",
8205
8277
  "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
8206
8278
  "description": "Entity ID (ULID format)",
@@ -8233,7 +8305,7 @@
8233
8305
  }
8234
8306
  },
8235
8307
  "required": [
8236
- "pi",
8308
+ "id",
8237
8309
  "ver",
8238
8310
  "cid",
8239
8311
  "attestation_status",
@@ -8275,7 +8347,7 @@
8275
8347
  "attestation": {
8276
8348
  "type": "object",
8277
8349
  "properties": {
8278
- "pi": {
8350
+ "id": {
8279
8351
  "type": "string",
8280
8352
  "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
8281
8353
  "description": "Entity ID (ULID format)",
@@ -8323,7 +8395,7 @@
8323
8395
  }
8324
8396
  },
8325
8397
  "required": [
8326
- "pi",
8398
+ "id",
8327
8399
  "ver",
8328
8400
  "cid",
8329
8401
  "op",
@@ -10250,6 +10322,16 @@
10250
10322
  "name": "type",
10251
10323
  "in": "query"
10252
10324
  },
10325
+ {
10326
+ "schema": {
10327
+ "type": "string",
10328
+ "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.",
10329
+ "example": "{\"_year\":{\"$gte\":1800,\"$lte\":1900}}"
10330
+ },
10331
+ "required": false,
10332
+ "name": "filter",
10333
+ "in": "query"
10334
+ },
10253
10335
  {
10254
10336
  "schema": {
10255
10337
  "type": "integer",
@@ -15026,9 +15108,9 @@
15026
15108
  "schema": {
15027
15109
  "type": "object",
15028
15110
  "properties": {
15029
- "pi": {
15111
+ "id": {
15030
15112
  "type": "string",
15031
- "description": "Collection PI to find similar collections for"
15113
+ "description": "Collection ID to find similar collections for"
15032
15114
  },
15033
15115
  "limit": {
15034
15116
  "type": "number",
@@ -15054,7 +15136,7 @@
15054
15136
  }
15055
15137
  },
15056
15138
  "required": [
15057
- "pi"
15139
+ "id"
15058
15140
  ]
15059
15141
  }
15060
15142
  }
@@ -15073,7 +15155,7 @@
15073
15155
  "items": {
15074
15156
  "type": "object",
15075
15157
  "properties": {
15076
- "pi": {
15158
+ "id": {
15077
15159
  "type": "string"
15078
15160
  },
15079
15161
  "label": {
@@ -15118,7 +15200,7 @@
15118
15200
  }
15119
15201
  },
15120
15202
  "required": [
15121
- "pi",
15203
+ "id",
15122
15204
  "label",
15123
15205
  "score"
15124
15206
  ]
@@ -15127,7 +15209,7 @@
15127
15209
  "metadata": {
15128
15210
  "type": "object",
15129
15211
  "properties": {
15130
- "source_pi": {
15212
+ "source_id": {
15131
15213
  "type": "string"
15132
15214
  },
15133
15215
  "result_count": {
@@ -15141,7 +15223,7 @@
15141
15223
  }
15142
15224
  },
15143
15225
  "required": [
15144
- "source_pi",
15226
+ "source_id",
15145
15227
  "result_count"
15146
15228
  ]
15147
15229
  }
@@ -15234,13 +15316,13 @@
15234
15316
  "schema": {
15235
15317
  "type": "object",
15236
15318
  "properties": {
15237
- "pi": {
15319
+ "id": {
15238
15320
  "type": "string",
15239
- "description": "Entity PI to find similar items for"
15321
+ "description": "Entity ID to find similar items for"
15240
15322
  },
15241
- "collection_pi": {
15323
+ "collection_id": {
15242
15324
  "type": "string",
15243
- "description": "Entity's collection PI"
15325
+ "description": "Entity's collection ID"
15244
15326
  },
15245
15327
  "limit": {
15246
15328
  "type": "number",
@@ -15285,8 +15367,8 @@
15285
15367
  }
15286
15368
  },
15287
15369
  "required": [
15288
- "pi",
15289
- "collection_pi"
15370
+ "id",
15371
+ "collection_id"
15290
15372
  ]
15291
15373
  }
15292
15374
  }
@@ -15305,7 +15387,7 @@
15305
15387
  "items": {
15306
15388
  "type": "object",
15307
15389
  "properties": {
15308
- "pi": {
15390
+ "id": {
15309
15391
  "type": "string"
15310
15392
  },
15311
15393
  "type": {
@@ -15314,7 +15396,7 @@
15314
15396
  "label": {
15315
15397
  "type": "string"
15316
15398
  },
15317
- "collection_pi": {
15399
+ "collection_id": {
15318
15400
  "type": "string",
15319
15401
  "nullable": true
15320
15402
  },
@@ -15338,7 +15420,7 @@
15338
15420
  "id": "01KENTITY123456789ABCDEFGH",
15339
15421
  "type": "document",
15340
15422
  "label": "Similar Research Paper",
15341
- "collection_pi": "01JCOLLECTION123456789AB",
15423
+ "collection_id": "01JCOLLECTION123456789AB",
15342
15424
  "description_preview": "Related findings on distributed systems...",
15343
15425
  "created_at": "2026-01-08T00:00:00.000Z",
15344
15426
  "updated_at": "2026-01-12T10:00:00.000Z"
@@ -15358,10 +15440,10 @@
15358
15440
  }
15359
15441
  },
15360
15442
  "required": [
15361
- "pi",
15443
+ "id",
15362
15444
  "type",
15363
15445
  "label",
15364
- "collection_pi",
15446
+ "collection_id",
15365
15447
  "score"
15366
15448
  ]
15367
15449
  }
@@ -15369,7 +15451,7 @@
15369
15451
  "metadata": {
15370
15452
  "type": "object",
15371
15453
  "properties": {
15372
- "source_pi": {
15454
+ "source_id": {
15373
15455
  "type": "string"
15374
15456
  },
15375
15457
  "collections_searched": {
@@ -15386,7 +15468,7 @@
15386
15468
  }
15387
15469
  },
15388
15470
  "required": [
15389
- "source_pi",
15471
+ "source_id",
15390
15472
  "collections_searched",
15391
15473
  "result_count"
15392
15474
  ]
@@ -15500,6 +15582,19 @@
15500
15582
  },
15501
15583
  "description": "Filter by collection types"
15502
15584
  },
15585
+ "filter": {
15586
+ "type": "object",
15587
+ "additionalProperties": {
15588
+ "nullable": true
15589
+ },
15590
+ "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```",
15591
+ "example": {
15592
+ "_year": {
15593
+ "$gt": 1800
15594
+ },
15595
+ "type": "letter"
15596
+ }
15597
+ },
15503
15598
  "expand": {
15504
15599
  "type": "string",
15505
15600
  "enum": [
@@ -15531,7 +15626,7 @@
15531
15626
  "items": {
15532
15627
  "type": "object",
15533
15628
  "properties": {
15534
- "pi": {
15629
+ "id": {
15535
15630
  "type": "string"
15536
15631
  },
15537
15632
  "label": {
@@ -15579,7 +15674,7 @@
15579
15674
  }
15580
15675
  },
15581
15676
  "required": [
15582
- "pi",
15677
+ "id",
15583
15678
  "label",
15584
15679
  "type",
15585
15680
  "score"
@@ -15690,6 +15785,19 @@
15690
15785
  "default": 10,
15691
15786
  "description": "Maximum results to return"
15692
15787
  },
15788
+ "filter": {
15789
+ "type": "object",
15790
+ "additionalProperties": {
15791
+ "nullable": true
15792
+ },
15793
+ "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```",
15794
+ "example": {
15795
+ "_year": {
15796
+ "$gt": 1800
15797
+ },
15798
+ "type": "letter"
15799
+ }
15800
+ },
15693
15801
  "expand": {
15694
15802
  "type": "string",
15695
15803
  "enum": [
@@ -15730,7 +15838,7 @@
15730
15838
  "items": {
15731
15839
  "type": "object",
15732
15840
  "properties": {
15733
- "pi": {
15841
+ "id": {
15734
15842
  "type": "string"
15735
15843
  },
15736
15844
  "label": {
@@ -15739,7 +15847,7 @@
15739
15847
  "score": {
15740
15848
  "type": "number"
15741
15849
  },
15742
- "collection_pi": {
15850
+ "collection_id": {
15743
15851
  "type": "string",
15744
15852
  "nullable": true
15745
15853
  },
@@ -15763,7 +15871,7 @@
15763
15871
  "id": "01KAGENT123456789ABCDEFGHI",
15764
15872
  "type": "agent",
15765
15873
  "label": "Document Analyzer Agent",
15766
- "collection_pi": "01JCOLLECTION123456789AB",
15874
+ "collection_id": "01JCOLLECTION123456789AB",
15767
15875
  "description_preview": "An AI agent that analyzes documents and extracts key insights...",
15768
15876
  "created_at": "2026-01-01T00:00:00.000Z",
15769
15877
  "updated_at": "2026-01-15T16:00:00.000Z"
@@ -15783,10 +15891,10 @@
15783
15891
  }
15784
15892
  },
15785
15893
  "required": [
15786
- "pi",
15894
+ "id",
15787
15895
  "label",
15788
15896
  "score",
15789
- "collection_pi"
15897
+ "collection_id"
15790
15898
  ]
15791
15899
  }
15792
15900
  },
@@ -15863,7 +15971,7 @@
15863
15971
  "Search"
15864
15972
  ],
15865
15973
  "summary": "Search entities within collection(s)",
15866
- "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",
15974
+ "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",
15867
15975
  "x-arke-action": "search:query",
15868
15976
  "x-arke-auth": "required",
15869
15977
  "x-arke-tier": "external",
@@ -15881,17 +15989,17 @@
15881
15989
  "schema": {
15882
15990
  "type": "object",
15883
15991
  "properties": {
15884
- "collection_pi": {
15992
+ "collection_id": {
15885
15993
  "type": "string",
15886
- "description": "Single collection PI to search within"
15994
+ "description": "Single collection ID to search within"
15887
15995
  },
15888
- "collection_pis": {
15996
+ "collection_ids": {
15889
15997
  "type": "array",
15890
15998
  "items": {
15891
15999
  "type": "string"
15892
16000
  },
15893
16001
  "maxItems": 20,
15894
- "description": "Multiple collection PIs to search (max 20)"
16002
+ "description": "Multiple collection IDs to search (max 20)"
15895
16003
  },
15896
16004
  "query": {
15897
16005
  "type": "string",
@@ -15913,6 +16021,19 @@
15913
16021
  },
15914
16022
  "description": "Filter by entity types"
15915
16023
  },
16024
+ "filter": {
16025
+ "type": "object",
16026
+ "additionalProperties": {
16027
+ "nullable": true
16028
+ },
16029
+ "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```",
16030
+ "example": {
16031
+ "_year": {
16032
+ "$gt": 1800
16033
+ },
16034
+ "type": "letter"
16035
+ }
16036
+ },
15916
16037
  "per_collection_limit": {
15917
16038
  "type": "number",
15918
16039
  "minimum": 1,
@@ -15950,7 +16071,7 @@
15950
16071
  "items": {
15951
16072
  "type": "object",
15952
16073
  "properties": {
15953
- "pi": {
16074
+ "id": {
15954
16075
  "type": "string"
15955
16076
  },
15956
16077
  "label": {
@@ -15962,7 +16083,7 @@
15962
16083
  "score": {
15963
16084
  "type": "number"
15964
16085
  },
15965
- "collection_pi": {
16086
+ "collection_id": {
15966
16087
  "type": "string"
15967
16088
  },
15968
16089
  "created_at": {
@@ -15982,7 +16103,7 @@
15982
16103
  "id": "01KENTITY123456789ABCDEFGH",
15983
16104
  "type": "document",
15984
16105
  "label": "Research Findings Report",
15985
- "collection_pi": "01JCOLLECTION123456789AB",
16106
+ "collection_id": "01JCOLLECTION123456789AB",
15986
16107
  "description_preview": "Detailed analysis of experimental results...",
15987
16108
  "created_at": "2026-01-10T00:00:00.000Z",
15988
16109
  "updated_at": "2026-01-14T09:00:00.000Z"
@@ -16002,18 +16123,18 @@
16002
16123
  }
16003
16124
  },
16004
16125
  "required": [
16005
- "pi",
16126
+ "id",
16006
16127
  "label",
16007
16128
  "type",
16008
16129
  "score",
16009
- "collection_pi"
16130
+ "collection_id"
16010
16131
  ]
16011
16132
  }
16012
16133
  },
16013
16134
  "metadata": {
16014
16135
  "type": "object",
16015
16136
  "properties": {
16016
- "collection_pis": {
16137
+ "collection_ids": {
16017
16138
  "type": "array",
16018
16139
  "items": {
16019
16140
  "type": "string"
@@ -16030,7 +16151,7 @@
16030
16151
  }
16031
16152
  },
16032
16153
  "required": [
16033
- "collection_pis",
16154
+ "collection_ids",
16034
16155
  "query",
16035
16156
  "collections_searched",
16036
16157
  "result_count"
@@ -16132,6 +16253,19 @@
16132
16253
  },
16133
16254
  "description": "Filter by entity types"
16134
16255
  },
16256
+ "filter": {
16257
+ "type": "object",
16258
+ "additionalProperties": {
16259
+ "nullable": true
16260
+ },
16261
+ "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```",
16262
+ "example": {
16263
+ "_year": {
16264
+ "$gt": 1800
16265
+ },
16266
+ "type": "letter"
16267
+ }
16268
+ },
16135
16269
  "collection_limit": {
16136
16270
  "type": "number",
16137
16271
  "minimum": 1,
@@ -16177,7 +16311,7 @@
16177
16311
  "items": {
16178
16312
  "type": "object",
16179
16313
  "properties": {
16180
- "pi": {
16314
+ "id": {
16181
16315
  "type": "string"
16182
16316
  },
16183
16317
  "label": {
@@ -16189,7 +16323,7 @@
16189
16323
  "score": {
16190
16324
  "type": "number"
16191
16325
  },
16192
- "collection_pi": {
16326
+ "collection_id": {
16193
16327
  "type": "string"
16194
16328
  },
16195
16329
  "created_at": {
@@ -16209,7 +16343,7 @@
16209
16343
  "id": "01KENTITY123456789ABCDEFGH",
16210
16344
  "type": "file",
16211
16345
  "label": "Discovered Document.pdf",
16212
- "collection_pi": "01JCOLLECTION123456789AB",
16346
+ "collection_id": "01JCOLLECTION123456789AB",
16213
16347
  "description_preview": "A document discovered through semantic search...",
16214
16348
  "created_at": "2026-01-08T00:00:00.000Z",
16215
16349
  "updated_at": "2026-01-12T14:00:00.000Z"
@@ -16229,11 +16363,11 @@
16229
16363
  }
16230
16364
  },
16231
16365
  "required": [
16232
- "pi",
16366
+ "id",
16233
16367
  "label",
16234
16368
  "type",
16235
16369
  "score",
16236
- "collection_pi"
16370
+ "collection_id"
16237
16371
  ]
16238
16372
  }
16239
16373
  },