@arke-institute/sdk 2.3.10 → 2.3.12

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 (5) hide show
  1. package/dist/generated/index.d.cts +414 -7
  2. package/dist/generated/index.d.ts +414 -7
  3. package/openapi/spec.json +798 -3
  4. package/openapi/version.json +1 -1
  5. package/package.json +1 -1
package/openapi/spec.json CHANGED
@@ -72,6 +72,37 @@
72
72
  "scheme": "bearer",
73
73
  "bearerFormat": "JWT",
74
74
  "description": "Supabase JWT token"
75
+ },
76
+ "apiKeyAuth": {
77
+ "type": "apiKey",
78
+ "in": "header",
79
+ "name": "Authorization",
80
+ "description": "API Key authentication. Format: `ApiKey ak_xxx` (agent) or `ApiKey uk_xxx` (user)"
81
+ }
82
+ },
83
+ "parameters": {
84
+ "X-Arke-Network": {
85
+ "name": "X-Arke-Network",
86
+ "in": "header",
87
+ "required": false,
88
+ "schema": {
89
+ "type": "string",
90
+ "enum": [
91
+ "main",
92
+ "test"
93
+ ],
94
+ "default": "main"
95
+ },
96
+ "description": "Target network. Use `test` for isolated test data with II-prefixed IDs."
97
+ },
98
+ "X-On-Behalf-Of": {
99
+ "name": "X-On-Behalf-Of",
100
+ "in": "header",
101
+ "required": false,
102
+ "schema": {
103
+ "type": "string"
104
+ },
105
+ "description": "User entity ID for service accounts acting on behalf of a user. Only valid with `role: service` authentication."
75
106
  }
76
107
  },
77
108
  "schemas": {
@@ -2205,6 +2236,441 @@
2205
2236
  "truncated"
2206
2237
  ]
2207
2238
  },
2239
+ "VersionMeta": {
2240
+ "type": "object",
2241
+ "nullable": true,
2242
+ "properties": {
2243
+ "cid": {
2244
+ "type": "string",
2245
+ "minLength": 1,
2246
+ "description": "Content Identifier (CID) - content-addressed hash",
2247
+ "example": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy"
2248
+ },
2249
+ "ver": {
2250
+ "type": "integer",
2251
+ "minimum": 0,
2252
+ "exclusiveMinimum": true,
2253
+ "description": "Entity version number",
2254
+ "example": 1
2255
+ },
2256
+ "ts": {
2257
+ "type": "string",
2258
+ "format": "date-time",
2259
+ "description": "ISO 8601 datetime",
2260
+ "example": "2025-12-26T12:00:00.000Z"
2261
+ }
2262
+ },
2263
+ "required": [
2264
+ "cid",
2265
+ "ver",
2266
+ "ts"
2267
+ ],
2268
+ "description": "Metadata about the \"from\" version (null for version 1)"
2269
+ },
2270
+ "PropertyChange": {
2271
+ "type": "object",
2272
+ "properties": {
2273
+ "from": {
2274
+ "nullable": true,
2275
+ "description": "Previous value"
2276
+ },
2277
+ "to": {
2278
+ "nullable": true,
2279
+ "description": "New value"
2280
+ }
2281
+ }
2282
+ },
2283
+ "PropertiesChanges": {
2284
+ "type": "object",
2285
+ "properties": {
2286
+ "added": {
2287
+ "type": "object",
2288
+ "additionalProperties": {
2289
+ "nullable": true
2290
+ },
2291
+ "description": "Properties that were added",
2292
+ "example": {
2293
+ "email": "new@example.com"
2294
+ }
2295
+ },
2296
+ "removed": {
2297
+ "type": "object",
2298
+ "additionalProperties": {
2299
+ "nullable": true
2300
+ },
2301
+ "description": "Properties that were removed (includes old values)",
2302
+ "example": {
2303
+ "deprecated_field": "old value"
2304
+ }
2305
+ },
2306
+ "changed": {
2307
+ "type": "object",
2308
+ "additionalProperties": {
2309
+ "$ref": "#/components/schemas/PropertyChange"
2310
+ },
2311
+ "description": "Properties that changed",
2312
+ "example": {
2313
+ "name": {
2314
+ "from": "Old Name",
2315
+ "to": "New Name"
2316
+ }
2317
+ }
2318
+ }
2319
+ },
2320
+ "required": [
2321
+ "added",
2322
+ "removed",
2323
+ "changed"
2324
+ ]
2325
+ },
2326
+ "RelationshipChange": {
2327
+ "type": "object",
2328
+ "properties": {
2329
+ "predicate": {
2330
+ "type": "string",
2331
+ "minLength": 1
2332
+ },
2333
+ "peer": {
2334
+ "type": "string",
2335
+ "minLength": 1
2336
+ },
2337
+ "peer_type": {
2338
+ "type": "string"
2339
+ },
2340
+ "peer_label": {
2341
+ "type": "string"
2342
+ },
2343
+ "properties": {
2344
+ "$ref": "#/components/schemas/PropertyChange"
2345
+ }
2346
+ },
2347
+ "required": [
2348
+ "predicate",
2349
+ "peer",
2350
+ "properties"
2351
+ ]
2352
+ },
2353
+ "RelationshipsChanges": {
2354
+ "type": "object",
2355
+ "properties": {
2356
+ "added": {
2357
+ "type": "array",
2358
+ "items": {
2359
+ "type": "object",
2360
+ "properties": {
2361
+ "predicate": {
2362
+ "type": "string",
2363
+ "minLength": 1
2364
+ },
2365
+ "peer": {
2366
+ "type": "string",
2367
+ "minLength": 1
2368
+ },
2369
+ "peer_type": {
2370
+ "type": "string"
2371
+ },
2372
+ "peer_label": {
2373
+ "type": "string"
2374
+ },
2375
+ "properties": {
2376
+ "type": "object",
2377
+ "additionalProperties": {
2378
+ "nullable": true
2379
+ }
2380
+ }
2381
+ },
2382
+ "required": [
2383
+ "predicate",
2384
+ "peer"
2385
+ ],
2386
+ "description": "Entity relationship",
2387
+ "example": {
2388
+ "predicate": "crew",
2389
+ "peer": "01KDETYWYWM0MJVKM8DK3AEXPY",
2390
+ "peer_type": "collection"
2391
+ }
2392
+ },
2393
+ "description": "Relationships that were added"
2394
+ },
2395
+ "removed": {
2396
+ "type": "array",
2397
+ "items": {
2398
+ "type": "object",
2399
+ "properties": {
2400
+ "predicate": {
2401
+ "type": "string",
2402
+ "minLength": 1
2403
+ },
2404
+ "peer": {
2405
+ "type": "string",
2406
+ "minLength": 1
2407
+ },
2408
+ "peer_type": {
2409
+ "type": "string"
2410
+ },
2411
+ "peer_label": {
2412
+ "type": "string"
2413
+ },
2414
+ "properties": {
2415
+ "type": "object",
2416
+ "additionalProperties": {
2417
+ "nullable": true
2418
+ }
2419
+ }
2420
+ },
2421
+ "required": [
2422
+ "predicate",
2423
+ "peer"
2424
+ ],
2425
+ "description": "Entity relationship",
2426
+ "example": {
2427
+ "predicate": "crew",
2428
+ "peer": "01KDETYWYWM0MJVKM8DK3AEXPY",
2429
+ "peer_type": "collection"
2430
+ }
2431
+ },
2432
+ "description": "Relationships that were removed"
2433
+ },
2434
+ "changed": {
2435
+ "type": "array",
2436
+ "items": {
2437
+ "$ref": "#/components/schemas/RelationshipChange"
2438
+ },
2439
+ "description": "Relationships with changed properties"
2440
+ }
2441
+ },
2442
+ "required": [
2443
+ "added",
2444
+ "removed",
2445
+ "changed"
2446
+ ]
2447
+ },
2448
+ "SemanticChanges": {
2449
+ "type": "object",
2450
+ "properties": {
2451
+ "properties": {
2452
+ "$ref": "#/components/schemas/PropertiesChanges"
2453
+ },
2454
+ "relationships": {
2455
+ "$ref": "#/components/schemas/RelationshipsChanges"
2456
+ }
2457
+ },
2458
+ "required": [
2459
+ "properties",
2460
+ "relationships"
2461
+ ]
2462
+ },
2463
+ "SemanticDiffResponse": {
2464
+ "type": "object",
2465
+ "properties": {
2466
+ "entity_id": {
2467
+ "type": "string",
2468
+ "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
2469
+ "description": "Entity ID (ULID format)",
2470
+ "example": "01KDETYWYWM0MJVKM8DK3AEXPY"
2471
+ },
2472
+ "from": {
2473
+ "$ref": "#/components/schemas/VersionMeta"
2474
+ },
2475
+ "to": {
2476
+ "$ref": "#/components/schemas/VersionMeta"
2477
+ },
2478
+ "format": {
2479
+ "type": "string",
2480
+ "enum": [
2481
+ "semantic"
2482
+ ]
2483
+ },
2484
+ "changes": {
2485
+ "$ref": "#/components/schemas/SemanticChanges"
2486
+ }
2487
+ },
2488
+ "required": [
2489
+ "entity_id",
2490
+ "from",
2491
+ "to",
2492
+ "format",
2493
+ "changes"
2494
+ ]
2495
+ },
2496
+ "PatchOperation": {
2497
+ "anyOf": [
2498
+ {
2499
+ "type": "object",
2500
+ "properties": {
2501
+ "op": {
2502
+ "type": "string",
2503
+ "enum": [
2504
+ "add"
2505
+ ]
2506
+ },
2507
+ "path": {
2508
+ "type": "string"
2509
+ },
2510
+ "value": {
2511
+ "nullable": true
2512
+ }
2513
+ },
2514
+ "required": [
2515
+ "op",
2516
+ "path"
2517
+ ]
2518
+ },
2519
+ {
2520
+ "type": "object",
2521
+ "properties": {
2522
+ "op": {
2523
+ "type": "string",
2524
+ "enum": [
2525
+ "remove"
2526
+ ]
2527
+ },
2528
+ "path": {
2529
+ "type": "string"
2530
+ }
2531
+ },
2532
+ "required": [
2533
+ "op",
2534
+ "path"
2535
+ ]
2536
+ },
2537
+ {
2538
+ "type": "object",
2539
+ "properties": {
2540
+ "op": {
2541
+ "type": "string",
2542
+ "enum": [
2543
+ "replace"
2544
+ ]
2545
+ },
2546
+ "path": {
2547
+ "type": "string"
2548
+ },
2549
+ "value": {
2550
+ "nullable": true
2551
+ }
2552
+ },
2553
+ "required": [
2554
+ "op",
2555
+ "path"
2556
+ ]
2557
+ }
2558
+ ]
2559
+ },
2560
+ "PatchDiffResponse": {
2561
+ "type": "object",
2562
+ "properties": {
2563
+ "entity_id": {
2564
+ "type": "string",
2565
+ "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
2566
+ "description": "Entity ID (ULID format)",
2567
+ "example": "01KDETYWYWM0MJVKM8DK3AEXPY"
2568
+ },
2569
+ "from": {
2570
+ "$ref": "#/components/schemas/VersionMeta"
2571
+ },
2572
+ "to": {
2573
+ "$ref": "#/components/schemas/VersionMeta"
2574
+ },
2575
+ "format": {
2576
+ "type": "string",
2577
+ "enum": [
2578
+ "patch"
2579
+ ]
2580
+ },
2581
+ "patch": {
2582
+ "type": "array",
2583
+ "items": {
2584
+ "$ref": "#/components/schemas/PatchOperation"
2585
+ },
2586
+ "description": "RFC 6902 JSON Patch operations"
2587
+ }
2588
+ },
2589
+ "required": [
2590
+ "entity_id",
2591
+ "from",
2592
+ "to",
2593
+ "format",
2594
+ "patch"
2595
+ ]
2596
+ },
2597
+ "DiffResponse": {
2598
+ "anyOf": [
2599
+ {
2600
+ "$ref": "#/components/schemas/SemanticDiffResponse"
2601
+ },
2602
+ {
2603
+ "$ref": "#/components/schemas/PatchDiffResponse"
2604
+ }
2605
+ ]
2606
+ },
2607
+ "PermissionResolution": {
2608
+ "type": "object",
2609
+ "properties": {
2610
+ "method": {
2611
+ "type": "string",
2612
+ "enum": [
2613
+ "collection",
2614
+ "self",
2615
+ "open_season"
2616
+ ],
2617
+ "description": "How permissions were resolved",
2618
+ "example": "collection"
2619
+ },
2620
+ "collection_id": {
2621
+ "type": "string",
2622
+ "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
2623
+ "description": "Collection ID if permissions come from a collection role",
2624
+ "example": "01KDETYWYWM0MJVKM8DK3AEXPY"
2625
+ },
2626
+ "role": {
2627
+ "type": "string",
2628
+ "description": "Role name in the collection",
2629
+ "example": "editor"
2630
+ }
2631
+ },
2632
+ "required": [
2633
+ "method"
2634
+ ],
2635
+ "description": "How permissions were resolved"
2636
+ },
2637
+ "EntityPermissionsResponse": {
2638
+ "type": "object",
2639
+ "properties": {
2640
+ "entity_id": {
2641
+ "type": "string",
2642
+ "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
2643
+ "description": "The entity ID",
2644
+ "example": "01KDETYWYWM0MJVKM8DK3AEXPY"
2645
+ },
2646
+ "entity_type": {
2647
+ "type": "string",
2648
+ "description": "The entity type",
2649
+ "example": "file"
2650
+ },
2651
+ "allowed_actions": {
2652
+ "type": "array",
2653
+ "items": {
2654
+ "type": "string"
2655
+ },
2656
+ "description": "Actions the user can perform on this entity",
2657
+ "example": [
2658
+ "entity:view",
2659
+ "entity:update",
2660
+ "file:download"
2661
+ ]
2662
+ },
2663
+ "resolution": {
2664
+ "$ref": "#/components/schemas/PermissionResolution"
2665
+ }
2666
+ },
2667
+ "required": [
2668
+ "entity_id",
2669
+ "entity_type",
2670
+ "allowed_actions",
2671
+ "resolution"
2672
+ ]
2673
+ },
2208
2674
  "AddRelationshipResponse": {
2209
2675
  "type": "object",
2210
2676
  "properties": {
@@ -5761,8 +6227,7 @@
5761
6227
  "manifest_preview"
5762
6228
  ]
5763
6229
  }
5764
- },
5765
- "parameters": {}
6230
+ }
5766
6231
  },
5767
6232
  "x-arke-version": "1.0.0",
5768
6233
  "paths": {
@@ -5844,6 +6309,9 @@
5844
6309
  "security": [
5845
6310
  {
5846
6311
  "bearerAuth": []
6312
+ },
6313
+ {
6314
+ "apiKeyAuth": []
5847
6315
  }
5848
6316
  ],
5849
6317
  "responses": {
@@ -5951,6 +6419,9 @@
5951
6419
  "security": [
5952
6420
  {
5953
6421
  "bearerAuth": []
6422
+ },
6423
+ {
6424
+ "apiKeyAuth": []
5954
6425
  }
5955
6426
  ],
5956
6427
  "parameters": [
@@ -6084,6 +6555,9 @@
6084
6555
  "security": [
6085
6556
  {
6086
6557
  "bearerAuth": []
6558
+ },
6559
+ {
6560
+ "apiKeyAuth": []
6087
6561
  }
6088
6562
  ],
6089
6563
  "requestBody": {
@@ -6134,6 +6608,9 @@
6134
6608
  "security": [
6135
6609
  {
6136
6610
  "bearerAuth": []
6611
+ },
6612
+ {
6613
+ "apiKeyAuth": []
6137
6614
  }
6138
6615
  ],
6139
6616
  "responses": {
@@ -6177,6 +6654,9 @@
6177
6654
  "security": [
6178
6655
  {
6179
6656
  "bearerAuth": []
6657
+ },
6658
+ {
6659
+ "apiKeyAuth": []
6180
6660
  }
6181
6661
  ],
6182
6662
  "parameters": [
@@ -6350,6 +6830,9 @@
6350
6830
  "security": [
6351
6831
  {
6352
6832
  "bearerAuth": []
6833
+ },
6834
+ {
6835
+ "apiKeyAuth": []
6353
6836
  }
6354
6837
  ],
6355
6838
  "requestBody": {
@@ -6428,6 +6911,9 @@
6428
6911
  "security": [
6429
6912
  {
6430
6913
  "bearerAuth": []
6914
+ },
6915
+ {
6916
+ "apiKeyAuth": []
6431
6917
  }
6432
6918
  ],
6433
6919
  "requestBody": {
@@ -6578,6 +7064,9 @@
6578
7064
  "security": [
6579
7065
  {
6580
7066
  "bearerAuth": []
7067
+ },
7068
+ {
7069
+ "apiKeyAuth": []
6581
7070
  }
6582
7071
  ],
6583
7072
  "parameters": [
@@ -6710,6 +7199,9 @@
6710
7199
  "security": [
6711
7200
  {
6712
7201
  "bearerAuth": []
7202
+ },
7203
+ {
7204
+ "apiKeyAuth": []
6713
7205
  }
6714
7206
  ],
6715
7207
  "parameters": [
@@ -6825,6 +7317,9 @@
6825
7317
  "security": [
6826
7318
  {
6827
7319
  "bearerAuth": []
7320
+ },
7321
+ {
7322
+ "apiKeyAuth": []
6828
7323
  }
6829
7324
  ],
6830
7325
  "parameters": [
@@ -6950,6 +7445,9 @@
6950
7445
  "security": [
6951
7446
  {
6952
7447
  "bearerAuth": []
7448
+ },
7449
+ {
7450
+ "apiKeyAuth": []
6953
7451
  }
6954
7452
  ],
6955
7453
  "parameters": [
@@ -7120,6 +7618,9 @@
7120
7618
  "security": [
7121
7619
  {
7122
7620
  "bearerAuth": []
7621
+ },
7622
+ {
7623
+ "apiKeyAuth": []
7123
7624
  }
7124
7625
  ],
7125
7626
  "parameters": [
@@ -7235,6 +7736,9 @@
7235
7736
  "security": [
7236
7737
  {
7237
7738
  "bearerAuth": []
7739
+ },
7740
+ {
7741
+ "apiKeyAuth": []
7238
7742
  }
7239
7743
  ],
7240
7744
  "parameters": [
@@ -7364,6 +7868,9 @@
7364
7868
  "security": [
7365
7869
  {
7366
7870
  "bearerAuth": []
7871
+ },
7872
+ {
7873
+ "apiKeyAuth": []
7367
7874
  }
7368
7875
  ],
7369
7876
  "parameters": [
@@ -7599,6 +8106,9 @@
7599
8106
  "security": [
7600
8107
  {
7601
8108
  "bearerAuth": []
8109
+ },
8110
+ {
8111
+ "apiKeyAuth": []
7602
8112
  }
7603
8113
  ],
7604
8114
  "requestBody": {
@@ -7766,6 +8276,9 @@
7766
8276
  "security": [
7767
8277
  {
7768
8278
  "bearerAuth": []
8279
+ },
8280
+ {
8281
+ "apiKeyAuth": []
7769
8282
  }
7770
8283
  ],
7771
8284
  "parameters": [
@@ -7896,6 +8409,9 @@
7896
8409
  "security": [
7897
8410
  {
7898
8411
  "bearerAuth": []
8412
+ },
8413
+ {
8414
+ "apiKeyAuth": []
7899
8415
  }
7900
8416
  ],
7901
8417
  "parameters": [
@@ -8028,6 +8544,9 @@
8028
8544
  "security": [
8029
8545
  {
8030
8546
  "bearerAuth": []
8547
+ },
8548
+ {
8549
+ "apiKeyAuth": []
8031
8550
  }
8032
8551
  ],
8033
8552
  "parameters": [
@@ -8322,6 +8841,219 @@
8322
8841
  }
8323
8842
  }
8324
8843
  },
8844
+ "/entities/{id}/diff": {
8845
+ "get": {
8846
+ "tags": [
8847
+ "Entities",
8848
+ "Versions"
8849
+ ],
8850
+ "summary": "Get diff between entity versions",
8851
+ "description": "Computes the difference between two versions of an entity.\n\nQuery parameters:\n- `from`: CID of the \"from\" version (defaults to prev of \"to\" version)\n- `to`: CID of the \"to\" version (defaults to current tip)\n- `format`: Output format - \"semantic\" (default) or \"patch\" (RFC 6902)\n\nModes:\n- No params: Compare current tip with its previous version\n- `to` only: Compare that version with its prev\n- `from` only: Compare from that version to current tip\n- Both: Compare any two versions\n\nFor version 1 entities (no previous version), \"from\" is null and all content appears as added.",
8852
+ "x-arke-action": "entity:view",
8853
+ "x-arke-auth": "optional",
8854
+ "x-arke-tier": "standard",
8855
+ "parameters": [
8856
+ {
8857
+ "schema": {
8858
+ "type": "string",
8859
+ "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
8860
+ "description": "Entity ID (ULID format)",
8861
+ "example": "01KDETYWYWM0MJVKM8DK3AEXPY"
8862
+ },
8863
+ "required": true,
8864
+ "description": "Entity ID (ULID)",
8865
+ "name": "id",
8866
+ "in": "path"
8867
+ },
8868
+ {
8869
+ "schema": {
8870
+ "type": "string",
8871
+ "minLength": 1,
8872
+ "description": "Content Identifier (CID) - content-addressed hash",
8873
+ "example": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy"
8874
+ },
8875
+ "required": false,
8876
+ "description": "CID of the \"from\" version. Defaults to prev of \"to\" version.",
8877
+ "name": "from",
8878
+ "in": "query"
8879
+ },
8880
+ {
8881
+ "schema": {
8882
+ "type": "string",
8883
+ "minLength": 1,
8884
+ "description": "Content Identifier (CID) - content-addressed hash",
8885
+ "example": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy"
8886
+ },
8887
+ "required": false,
8888
+ "description": "CID of the \"to\" version. Defaults to current tip.",
8889
+ "name": "to",
8890
+ "in": "query"
8891
+ },
8892
+ {
8893
+ "schema": {
8894
+ "type": "string",
8895
+ "enum": [
8896
+ "semantic",
8897
+ "patch"
8898
+ ],
8899
+ "default": "semantic"
8900
+ },
8901
+ "required": false,
8902
+ "description": "Output format: \"semantic\" (default) or \"patch\" (RFC 6902)",
8903
+ "name": "format",
8904
+ "in": "query"
8905
+ }
8906
+ ],
8907
+ "responses": {
8908
+ "200": {
8909
+ "description": "Diff computed",
8910
+ "content": {
8911
+ "application/json": {
8912
+ "schema": {
8913
+ "$ref": "#/components/schemas/DiffResponse"
8914
+ }
8915
+ }
8916
+ }
8917
+ },
8918
+ "400": {
8919
+ "description": "Bad Request - Invalid input",
8920
+ "content": {
8921
+ "application/json": {
8922
+ "schema": {
8923
+ "$ref": "#/components/schemas/ValidationErrorResponse"
8924
+ },
8925
+ "example": {
8926
+ "error": "Validation failed",
8927
+ "details": {
8928
+ "issues": [
8929
+ {
8930
+ "path": [
8931
+ "properties",
8932
+ "label"
8933
+ ],
8934
+ "message": "Required"
8935
+ }
8936
+ ]
8937
+ }
8938
+ }
8939
+ }
8940
+ }
8941
+ },
8942
+ "403": {
8943
+ "description": "Forbidden - Insufficient permissions",
8944
+ "content": {
8945
+ "application/json": {
8946
+ "schema": {
8947
+ "$ref": "#/components/schemas/ErrorResponse"
8948
+ },
8949
+ "example": {
8950
+ "error": "Forbidden: You do not have permission to perform this action"
8951
+ }
8952
+ }
8953
+ }
8954
+ },
8955
+ "404": {
8956
+ "description": "Not Found - Resource does not exist",
8957
+ "content": {
8958
+ "application/json": {
8959
+ "schema": {
8960
+ "$ref": "#/components/schemas/ErrorResponse"
8961
+ },
8962
+ "example": {
8963
+ "error": "Entity not found"
8964
+ }
8965
+ }
8966
+ }
8967
+ }
8968
+ }
8969
+ }
8970
+ },
8971
+ "/entities/{id}/permissions": {
8972
+ "get": {
8973
+ "tags": [
8974
+ "Entities",
8975
+ "Permissions"
8976
+ ],
8977
+ "summary": "Get your permissions for an entity",
8978
+ "description": "Returns the list of actions you can perform on this entity.\n\nThe response includes:\n- `allowed_actions`: Concrete actions you can perform (no wildcards)\n- `resolution`: How permissions were determined\n\nResolution methods:\n- `collection`: Permissions from your role in the parent collection\n- `self`: You are checking your own user entity (self-ownership)\n- `open_season`: Entity is not in any collection (publicly accessible)\n\nActions are filtered to only those relevant to the entity type:\n- For files: entity:* and file:* actions\n- For collections: entity:* and collection:* actions\n- etc.",
8979
+ "x-arke-action": "entity:view",
8980
+ "x-arke-auth": "required",
8981
+ "x-arke-tier": "standard",
8982
+ "security": [
8983
+ {
8984
+ "bearerAuth": []
8985
+ },
8986
+ {
8987
+ "apiKeyAuth": []
8988
+ }
8989
+ ],
8990
+ "parameters": [
8991
+ {
8992
+ "schema": {
8993
+ "type": "string",
8994
+ "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
8995
+ "description": "Entity ID (ULID format)",
8996
+ "example": "01KDETYWYWM0MJVKM8DK3AEXPY"
8997
+ },
8998
+ "required": true,
8999
+ "description": "Entity ID (ULID)",
9000
+ "name": "id",
9001
+ "in": "path"
9002
+ }
9003
+ ],
9004
+ "responses": {
9005
+ "200": {
9006
+ "description": "Permissions retrieved",
9007
+ "content": {
9008
+ "application/json": {
9009
+ "schema": {
9010
+ "$ref": "#/components/schemas/EntityPermissionsResponse"
9011
+ }
9012
+ }
9013
+ }
9014
+ },
9015
+ "401": {
9016
+ "description": "Unauthorized - Missing or invalid authentication",
9017
+ "content": {
9018
+ "application/json": {
9019
+ "schema": {
9020
+ "$ref": "#/components/schemas/ErrorResponse"
9021
+ },
9022
+ "example": {
9023
+ "error": "Unauthorized: Missing or invalid authentication token"
9024
+ }
9025
+ }
9026
+ }
9027
+ },
9028
+ "403": {
9029
+ "description": "Forbidden - Insufficient permissions",
9030
+ "content": {
9031
+ "application/json": {
9032
+ "schema": {
9033
+ "$ref": "#/components/schemas/ErrorResponse"
9034
+ },
9035
+ "example": {
9036
+ "error": "Forbidden: You do not have permission to perform this action"
9037
+ }
9038
+ }
9039
+ }
9040
+ },
9041
+ "404": {
9042
+ "description": "Not Found - Resource does not exist",
9043
+ "content": {
9044
+ "application/json": {
9045
+ "schema": {
9046
+ "$ref": "#/components/schemas/ErrorResponse"
9047
+ },
9048
+ "example": {
9049
+ "error": "Entity not found"
9050
+ }
9051
+ }
9052
+ }
9053
+ }
9054
+ }
9055
+ }
9056
+ },
8325
9057
  "/relationships": {
8326
9058
  "post": {
8327
9059
  "tags": [
@@ -8335,6 +9067,9 @@
8335
9067
  "security": [
8336
9068
  {
8337
9069
  "bearerAuth": []
9070
+ },
9071
+ {
9072
+ "apiKeyAuth": []
8338
9073
  }
8339
9074
  ],
8340
9075
  "requestBody": {
@@ -8451,6 +9186,9 @@
8451
9186
  "security": [
8452
9187
  {
8453
9188
  "bearerAuth": []
9189
+ },
9190
+ {
9191
+ "apiKeyAuth": []
8454
9192
  }
8455
9193
  ],
8456
9194
  "requestBody": {
@@ -8569,6 +9307,9 @@
8569
9307
  "security": [
8570
9308
  {
8571
9309
  "bearerAuth": []
9310
+ },
9311
+ {
9312
+ "apiKeyAuth": []
8572
9313
  }
8573
9314
  ],
8574
9315
  "requestBody": {
@@ -8687,6 +9428,9 @@
8687
9428
  "security": [
8688
9429
  {
8689
9430
  "bearerAuth": []
9431
+ },
9432
+ {
9433
+ "apiKeyAuth": []
8690
9434
  }
8691
9435
  ],
8692
9436
  "requestBody": {
@@ -8805,6 +9549,9 @@
8805
9549
  "security": [
8806
9550
  {
8807
9551
  "bearerAuth": []
9552
+ },
9553
+ {
9554
+ "apiKeyAuth": []
8808
9555
  }
8809
9556
  ],
8810
9557
  "requestBody": {
@@ -8972,6 +9719,9 @@
8972
9719
  "security": [
8973
9720
  {
8974
9721
  "bearerAuth": []
9722
+ },
9723
+ {
9724
+ "apiKeyAuth": []
8975
9725
  }
8976
9726
  ],
8977
9727
  "parameters": [
@@ -9104,6 +9854,9 @@
9104
9854
  "security": [
9105
9855
  {
9106
9856
  "bearerAuth": []
9857
+ },
9858
+ {
9859
+ "apiKeyAuth": []
9107
9860
  }
9108
9861
  ],
9109
9862
  "parameters": [
@@ -9313,6 +10066,9 @@
9313
10066
  "security": [
9314
10067
  {
9315
10068
  "bearerAuth": []
10069
+ },
10070
+ {
10071
+ "apiKeyAuth": []
9316
10072
  }
9317
10073
  ],
9318
10074
  "parameters": [
@@ -9445,6 +10201,9 @@
9445
10201
  "security": [
9446
10202
  {
9447
10203
  "bearerAuth": []
10204
+ },
10205
+ {
10206
+ "apiKeyAuth": []
9448
10207
  }
9449
10208
  ],
9450
10209
  "requestBody": {
@@ -9595,6 +10354,9 @@
9595
10354
  "security": [
9596
10355
  {
9597
10356
  "bearerAuth": []
10357
+ },
10358
+ {
10359
+ "apiKeyAuth": []
9598
10360
  }
9599
10361
  ],
9600
10362
  "parameters": [
@@ -9727,6 +10489,9 @@
9727
10489
  "security": [
9728
10490
  {
9729
10491
  "bearerAuth": []
10492
+ },
10493
+ {
10494
+ "apiKeyAuth": []
9730
10495
  }
9731
10496
  ],
9732
10497
  "parameters": [
@@ -9859,6 +10624,9 @@
9859
10624
  "security": [
9860
10625
  {
9861
10626
  "bearerAuth": []
10627
+ },
10628
+ {
10629
+ "apiKeyAuth": []
9862
10630
  }
9863
10631
  ],
9864
10632
  "parameters": [
@@ -10003,6 +10771,9 @@
10003
10771
  "security": [
10004
10772
  {
10005
10773
  "bearerAuth": []
10774
+ },
10775
+ {
10776
+ "apiKeyAuth": []
10006
10777
  }
10007
10778
  ],
10008
10779
  "parameters": [
@@ -10135,6 +10906,9 @@
10135
10906
  "security": [
10136
10907
  {
10137
10908
  "bearerAuth": []
10909
+ },
10910
+ {
10911
+ "apiKeyAuth": []
10138
10912
  }
10139
10913
  ],
10140
10914
  "parameters": [
@@ -10267,6 +11041,9 @@
10267
11041
  "security": [
10268
11042
  {
10269
11043
  "bearerAuth": []
11044
+ },
11045
+ {
11046
+ "apiKeyAuth": []
10270
11047
  }
10271
11048
  ],
10272
11049
  "parameters": [
@@ -10612,6 +11389,9 @@
10612
11389
  "security": [
10613
11390
  {
10614
11391
  "bearerAuth": []
11392
+ },
11393
+ {
11394
+ "apiKeyAuth": []
10615
11395
  }
10616
11396
  ],
10617
11397
  "requestBody": {
@@ -10775,6 +11555,9 @@
10775
11555
  "security": [
10776
11556
  {
10777
11557
  "bearerAuth": []
11558
+ },
11559
+ {
11560
+ "apiKeyAuth": []
10778
11561
  }
10779
11562
  ],
10780
11563
  "parameters": [
@@ -10907,6 +11690,9 @@
10907
11690
  "security": [
10908
11691
  {
10909
11692
  "bearerAuth": []
11693
+ },
11694
+ {
11695
+ "apiKeyAuth": []
10910
11696
  }
10911
11697
  ],
10912
11698
  "parameters": [
@@ -11032,6 +11818,9 @@
11032
11818
  "security": [
11033
11819
  {
11034
11820
  "bearerAuth": []
11821
+ },
11822
+ {
11823
+ "apiKeyAuth": []
11035
11824
  }
11036
11825
  ],
11037
11826
  "parameters": [
@@ -11145,6 +11934,9 @@
11145
11934
  "security": [
11146
11935
  {
11147
11936
  "bearerAuth": []
11937
+ },
11938
+ {
11939
+ "apiKeyAuth": []
11148
11940
  }
11149
11941
  ],
11150
11942
  "parameters": [
@@ -11227,6 +12019,9 @@
11227
12019
  "security": [
11228
12020
  {
11229
12021
  "bearerAuth": []
12022
+ },
12023
+ {
12024
+ "apiKeyAuth": []
11230
12025
  }
11231
12026
  ],
11232
12027
  "parameters": [
@@ -11535,7 +12330,7 @@
11535
12330
  "Query"
11536
12331
  ],
11537
12332
  "summary": "Execute Argo query",
11538
- "description": "Execute an Argo DSL query for path-based graph traversal.\n\n## Query Syntax\n\n```\nENTRY_POINT [ENTRY_FILTER] [-[RELATION]{DEPTH}-> TARGET_FILTER]...\n```\n\n### Entry Points\n\n| Syntax | Description | Example |\n|--------|-------------|---------|\n| `\"text\"` | Semantic search | `\"george washington\"` |\n| `@id` | Exact entity ID | `@01KE4ZY69F9R40E88PK9S0TQRQ` |\n| `type:X` | All entities of type | `type:person` |\n| `type:X ~ \"text\"` | Semantic search within type | `type:person ~ \"physician\"` |\n\n### Edges (Hops)\n\n| Syntax | Direction |\n|--------|-----------|\n| `-[*]->` | Outgoing |\n| `<-[*]-` | Incoming |\n| `<-[*]->` | Both |\n| `-[*]{,4}->` | Variable depth (1-4) |\n\n### Examples\n\n```\n\"george washington\" # Simple semantic search\n\"albert einstein\" type:person # With type filter\n\"medical college\" -[*]{,4}-> type:file # Find files connected to concept\n@01KE4ZY... -[*]{,2}-> type:person # Find people near entity\n```\n",
12333
+ "description": "Execute an Argo DSL query for path-based graph traversal.\n\n## Query Syntax\n\n```\n[SCOPE_PREFIX] ENTRY_POINT [ENTRY_FILTER] [-[RELATION]{DEPTH}-> TARGET_FILTER]...\n```\n\n## Scope Prefixes\n\nControl where semantic search looks for entry points. Default is discovery mode.\n\n| Prefix | Description | Example |\n|--------|-------------|---------|\n| (none) | **Discovery mode** (default) - find relevant collections, then search within each | `\"medical notes\"` |\n| `@:collections` | Search for collections themselves | `@:collections \"columbia archives\"` |\n| `@:collection(id)` | Search within a specific collection | `@:collection(01JCOLL123) \"meeting\"` |\n| `@:discover` | Explicit discovery mode | `@:discover \"research papers\"` |\n| `@:public` | Search public domain only | `@:public \"orphaned data\"` |\n\n**Note:** Graph traversal (hops) is always cross-collection regardless of scope.\n\n### Entry Points\n\n| Syntax | Description | Example |\n|--------|-------------|---------|\n| `\"text\"` | Semantic search | `\"george washington\"` |\n| `@id` | Exact entity ID | `@01KE4ZY69F9R40E88PK9S0TQRQ` |\n| `type:X` | All entities of type | `type:person` |\n| `type:X ~ \"text\"` | Semantic search within type | `type:person ~ \"physician\"` |\n\n### Edges (Hops)\n\n| Syntax | Direction |\n|--------|-----------|\n| `-[*]->` | Outgoing |\n| `<-[*]-` | Incoming |\n| `<-[*]->` | Both |\n| `-[*]{,4}->` | Variable depth (1-4) |\n\n### Examples\n\n```\n\"george washington\" # Discovery mode (default)\n@:collections \"columbia university\" # Find collections\n@:collection(01JCOLL123) \"faculty meeting\" # Within specific collection\n@:discover \"alice\" -[*]{,2}-> type:person # Discover, then traverse\n@01KE4ZY... -[*]{,2}-> type:person # From exact entity\n```\n",
11539
12334
  "x-arke-action": "query:execute",
11540
12335
  "x-arke-auth": "optional",
11541
12336
  "x-arke-tier": "external",