@sanity/client 8.7.0 → 8.8.0

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 (21) hide show
  1. package/README.md +24 -6
  2. package/dist/collaboration.d.ts +33 -0
  3. package/dist/collaboration.js +2 -0
  4. package/dist/getCommentTargetDocumentRef-B8NuiBjG.js +31 -0
  5. package/dist/getCommentTargetDocumentRef-B8NuiBjG.js.map +1 -0
  6. package/dist/index.d.ts +2 -2
  7. package/dist/index.js +28 -5
  8. package/dist/index.js.map +1 -1
  9. package/dist/index.node.d.ts +387 -110
  10. package/dist/index.node.js +54 -6
  11. package/dist/index.node.js.map +1 -1
  12. package/dist/media-library.d.ts +1 -1
  13. package/dist/{types-Do7-A3K9.d.ts → types-Cov8gzNZ.d.ts} +388 -111
  14. package/package.json +2 -1
  15. package/src/collaboration/comments.ts +30 -7
  16. package/src/collaboration/getCommentTargetDocumentRef.ts +45 -0
  17. package/src/collaboration/index.ts +1 -0
  18. package/src/collaboration/types.ts +105 -13
  19. package/src/context/openapi.json +1011 -698
  20. package/src/context/types.gen.ts +324 -182
  21. package/src/types.ts +1 -0
package/src/context/openapi.json CHANGED
@@ -413,68 +413,147 @@
413
413
  "enum": [1]
414
414
  },
415
415
  "content": {
416
- "type": "object",
417
- "properties": {
418
- "kind": {
419
- "type": "string",
420
- "enum": [
421
- "conflict",
422
- "gap",
423
- "update_required",
424
- "add_entry",
425
- "remove_entry",
426
- "split_entry",
427
- "merge_entry"
428
- ]
429
- },
430
- "severity": {
431
- "type": "string",
432
- "enum": ["critical", "suggestion"]
433
- },
434
- "scopePath": {
435
- "type": "string"
436
- },
437
- "issue": {
438
- "type": "string"
439
- },
440
- "suggestedFix": {
441
- "type": "string"
442
- },
443
- "citedSourceIds": {
444
- "type": "array",
445
- "items": {
446
- "type": "string"
447
- }
448
- },
449
- "claimKey": {
450
- "type": "string"
451
- },
452
- "involvedScopes": {
453
- "type": "array",
454
- "items": {
455
- "type": "string"
456
- }
457
- },
458
- "currentClaim": {
459
- "type": "string"
460
- },
461
- "alternativeClaim": {
462
- "type": "string"
463
- },
464
- "currentAuthority": {
465
- "type": "string",
466
- "enum": ["primary", "secondary", "community"]
467
- },
468
- "alternativeAuthority": {
469
- "type": "string",
470
- "enum": ["primary", "secondary", "community"]
416
+ "oneOf": [
417
+ {
418
+ "type": "object",
419
+ "properties": {
420
+ "severity": {
421
+ "type": "string",
422
+ "enum": ["critical", "suggestion"]
423
+ },
424
+ "scopePath": {
425
+ "type": "string"
426
+ },
427
+ "issue": {
428
+ "type": "string"
429
+ },
430
+ "suggestedFix": {
431
+ "type": "string"
432
+ },
433
+ "kind": {
434
+ "type": "string",
435
+ "enum": ["conflict"]
436
+ },
437
+ "claimKey": {
438
+ "type": "string"
439
+ },
440
+ "sides": {
441
+ "minItems": 2,
442
+ "type": "array",
443
+ "items": {
444
+ "type": "object",
445
+ "properties": {
446
+ "claim": {
447
+ "type": "string"
448
+ },
449
+ "value": {
450
+ "type": "string"
451
+ },
452
+ "entryPaths": {
453
+ "type": "array",
454
+ "items": {
455
+ "type": "string"
456
+ }
457
+ },
458
+ "sourceIds": {
459
+ "type": "array",
460
+ "items": {
461
+ "type": "string"
462
+ }
463
+ },
464
+ "span": {
465
+ "type": "object",
466
+ "properties": {
467
+ "sourceId": {
468
+ "type": "string"
469
+ },
470
+ "lineStart": {
471
+ "type": "integer",
472
+ "minimum": 1,
473
+ "maximum": 9007199254740991
474
+ },
475
+ "lineEnd": {
476
+ "type": "integer",
477
+ "minimum": 1,
478
+ "maximum": 9007199254740991
479
+ }
480
+ },
481
+ "required": ["sourceId", "lineStart", "lineEnd"],
482
+ "description": "ConflictSpan"
483
+ },
484
+ "authority": {
485
+ "type": "string",
486
+ "enum": ["primary", "secondary", "community"]
487
+ }
488
+ },
489
+ "required": ["claim"],
490
+ "description": "ConflictSide"
491
+ }
492
+ },
493
+ "suggested": {
494
+ "type": "integer",
495
+ "minimum": 0,
496
+ "maximum": 9007199254740991
497
+ }
498
+ },
499
+ "required": [
500
+ "severity",
501
+ "scopePath",
502
+ "issue",
503
+ "suggestedFix",
504
+ "kind",
505
+ "claimKey",
506
+ "sides"
507
+ ],
508
+ "description": "ConflictIssueContent"
471
509
  },
472
- "suggestedResolution": {
473
- "type": "string",
474
- "enum": ["keep_existing", "accept_new"]
510
+ {
511
+ "type": "object",
512
+ "properties": {
513
+ "severity": {
514
+ "type": "string",
515
+ "enum": ["critical", "suggestion"]
516
+ },
517
+ "scopePath": {
518
+ "type": "string"
519
+ },
520
+ "issue": {
521
+ "type": "string"
522
+ },
523
+ "suggestedFix": {
524
+ "type": "string"
525
+ },
526
+ "kind": {
527
+ "type": "string",
528
+ "enum": [
529
+ "gap",
530
+ "update_required",
531
+ "add_entry",
532
+ "remove_entry",
533
+ "split_entry",
534
+ "merge_entry"
535
+ ]
536
+ },
537
+ "citedSourceIds": {
538
+ "type": "array",
539
+ "items": {
540
+ "type": "string"
541
+ }
542
+ },
543
+ "claimKey": {
544
+ "type": "string"
545
+ },
546
+ "involvedScopes": {
547
+ "type": "array",
548
+ "items": {
549
+ "type": "string"
550
+ }
551
+ }
552
+ },
553
+ "required": ["severity", "scopePath", "issue", "suggestedFix", "kind"],
554
+ "description": "MechanicalIssueContent"
475
555
  }
476
- },
477
- "required": ["kind", "severity", "scopePath", "issue", "suggestedFix"],
556
+ ],
478
557
  "description": "IssueContent"
479
558
  },
480
559
  "fingerprint": {
@@ -557,68 +636,147 @@
557
636
  "enum": [1]
558
637
  },
559
638
  "content": {
560
- "type": "object",
561
- "properties": {
562
- "kind": {
563
- "type": "string",
564
- "enum": [
565
- "conflict",
566
- "gap",
567
- "update_required",
568
- "add_entry",
569
- "remove_entry",
570
- "split_entry",
571
- "merge_entry"
572
- ]
573
- },
574
- "severity": {
575
- "type": "string",
576
- "enum": ["critical", "suggestion"]
577
- },
578
- "scopePath": {
579
- "type": "string"
580
- },
581
- "issue": {
582
- "type": "string"
583
- },
584
- "suggestedFix": {
585
- "type": "string"
586
- },
587
- "citedSourceIds": {
588
- "type": "array",
589
- "items": {
590
- "type": "string"
591
- }
592
- },
593
- "claimKey": {
594
- "type": "string"
595
- },
596
- "involvedScopes": {
597
- "type": "array",
598
- "items": {
599
- "type": "string"
600
- }
601
- },
602
- "currentClaim": {
603
- "type": "string"
604
- },
605
- "alternativeClaim": {
606
- "type": "string"
607
- },
608
- "currentAuthority": {
609
- "type": "string",
610
- "enum": ["primary", "secondary", "community"]
611
- },
612
- "alternativeAuthority": {
613
- "type": "string",
614
- "enum": ["primary", "secondary", "community"]
639
+ "oneOf": [
640
+ {
641
+ "type": "object",
642
+ "properties": {
643
+ "severity": {
644
+ "type": "string",
645
+ "enum": ["critical", "suggestion"]
646
+ },
647
+ "scopePath": {
648
+ "type": "string"
649
+ },
650
+ "issue": {
651
+ "type": "string"
652
+ },
653
+ "suggestedFix": {
654
+ "type": "string"
655
+ },
656
+ "kind": {
657
+ "type": "string",
658
+ "enum": ["conflict"]
659
+ },
660
+ "claimKey": {
661
+ "type": "string"
662
+ },
663
+ "sides": {
664
+ "minItems": 2,
665
+ "type": "array",
666
+ "items": {
667
+ "type": "object",
668
+ "properties": {
669
+ "claim": {
670
+ "type": "string"
671
+ },
672
+ "value": {
673
+ "type": "string"
674
+ },
675
+ "entryPaths": {
676
+ "type": "array",
677
+ "items": {
678
+ "type": "string"
679
+ }
680
+ },
681
+ "sourceIds": {
682
+ "type": "array",
683
+ "items": {
684
+ "type": "string"
685
+ }
686
+ },
687
+ "span": {
688
+ "type": "object",
689
+ "properties": {
690
+ "sourceId": {
691
+ "type": "string"
692
+ },
693
+ "lineStart": {
694
+ "type": "integer",
695
+ "minimum": 1,
696
+ "maximum": 9007199254740991
697
+ },
698
+ "lineEnd": {
699
+ "type": "integer",
700
+ "minimum": 1,
701
+ "maximum": 9007199254740991
702
+ }
703
+ },
704
+ "required": ["sourceId", "lineStart", "lineEnd"],
705
+ "description": "ConflictSpan"
706
+ },
707
+ "authority": {
708
+ "type": "string",
709
+ "enum": ["primary", "secondary", "community"]
710
+ }
711
+ },
712
+ "required": ["claim"],
713
+ "description": "ConflictSide"
714
+ }
715
+ },
716
+ "suggested": {
717
+ "type": "integer",
718
+ "minimum": 0,
719
+ "maximum": 9007199254740991
720
+ }
721
+ },
722
+ "required": [
723
+ "severity",
724
+ "scopePath",
725
+ "issue",
726
+ "suggestedFix",
727
+ "kind",
728
+ "claimKey",
729
+ "sides"
730
+ ],
731
+ "description": "ConflictIssueContent"
615
732
  },
616
- "suggestedResolution": {
617
- "type": "string",
618
- "enum": ["keep_existing", "accept_new"]
733
+ {
734
+ "type": "object",
735
+ "properties": {
736
+ "severity": {
737
+ "type": "string",
738
+ "enum": ["critical", "suggestion"]
739
+ },
740
+ "scopePath": {
741
+ "type": "string"
742
+ },
743
+ "issue": {
744
+ "type": "string"
745
+ },
746
+ "suggestedFix": {
747
+ "type": "string"
748
+ },
749
+ "kind": {
750
+ "type": "string",
751
+ "enum": [
752
+ "gap",
753
+ "update_required",
754
+ "add_entry",
755
+ "remove_entry",
756
+ "split_entry",
757
+ "merge_entry"
758
+ ]
759
+ },
760
+ "citedSourceIds": {
761
+ "type": "array",
762
+ "items": {
763
+ "type": "string"
764
+ }
765
+ },
766
+ "claimKey": {
767
+ "type": "string"
768
+ },
769
+ "involvedScopes": {
770
+ "type": "array",
771
+ "items": {
772
+ "type": "string"
773
+ }
774
+ }
775
+ },
776
+ "required": ["severity", "scopePath", "issue", "suggestedFix", "kind"],
777
+ "description": "MechanicalIssueContent"
619
778
  }
620
- },
621
- "required": ["kind", "severity", "scopePath", "issue", "suggestedFix"],
779
+ ],
622
780
  "description": "IssueContent"
623
781
  },
624
782
  "fingerprint": {
@@ -656,8 +814,9 @@
656
814
  },
657
815
  "resolution": {
658
816
  "nullable": true,
659
- "type": "string",
660
- "enum": ["keep_existing", "accept_new", null]
817
+ "type": "integer",
818
+ "minimum": 0,
819
+ "maximum": 9007199254740991
661
820
  }
662
821
  },
663
822
  "required": [
@@ -711,68 +870,147 @@
711
870
  "enum": [1]
712
871
  },
713
872
  "content": {
714
- "type": "object",
715
- "properties": {
716
- "kind": {
717
- "type": "string",
718
- "enum": [
719
- "conflict",
720
- "gap",
721
- "update_required",
722
- "add_entry",
723
- "remove_entry",
724
- "split_entry",
725
- "merge_entry"
726
- ]
727
- },
728
- "severity": {
729
- "type": "string",
730
- "enum": ["critical", "suggestion"]
731
- },
732
- "scopePath": {
733
- "type": "string"
734
- },
735
- "issue": {
736
- "type": "string"
737
- },
738
- "suggestedFix": {
739
- "type": "string"
740
- },
741
- "citedSourceIds": {
742
- "type": "array",
743
- "items": {
744
- "type": "string"
745
- }
746
- },
747
- "claimKey": {
748
- "type": "string"
749
- },
750
- "involvedScopes": {
751
- "type": "array",
752
- "items": {
753
- "type": "string"
754
- }
755
- },
756
- "currentClaim": {
757
- "type": "string"
758
- },
759
- "alternativeClaim": {
760
- "type": "string"
761
- },
762
- "currentAuthority": {
763
- "type": "string",
764
- "enum": ["primary", "secondary", "community"]
765
- },
766
- "alternativeAuthority": {
767
- "type": "string",
768
- "enum": ["primary", "secondary", "community"]
873
+ "oneOf": [
874
+ {
875
+ "type": "object",
876
+ "properties": {
877
+ "severity": {
878
+ "type": "string",
879
+ "enum": ["critical", "suggestion"]
880
+ },
881
+ "scopePath": {
882
+ "type": "string"
883
+ },
884
+ "issue": {
885
+ "type": "string"
886
+ },
887
+ "suggestedFix": {
888
+ "type": "string"
889
+ },
890
+ "kind": {
891
+ "type": "string",
892
+ "enum": ["conflict"]
893
+ },
894
+ "claimKey": {
895
+ "type": "string"
896
+ },
897
+ "sides": {
898
+ "minItems": 2,
899
+ "type": "array",
900
+ "items": {
901
+ "type": "object",
902
+ "properties": {
903
+ "claim": {
904
+ "type": "string"
905
+ },
906
+ "value": {
907
+ "type": "string"
908
+ },
909
+ "entryPaths": {
910
+ "type": "array",
911
+ "items": {
912
+ "type": "string"
913
+ }
914
+ },
915
+ "sourceIds": {
916
+ "type": "array",
917
+ "items": {
918
+ "type": "string"
919
+ }
920
+ },
921
+ "span": {
922
+ "type": "object",
923
+ "properties": {
924
+ "sourceId": {
925
+ "type": "string"
926
+ },
927
+ "lineStart": {
928
+ "type": "integer",
929
+ "minimum": 1,
930
+ "maximum": 9007199254740991
931
+ },
932
+ "lineEnd": {
933
+ "type": "integer",
934
+ "minimum": 1,
935
+ "maximum": 9007199254740991
936
+ }
937
+ },
938
+ "required": ["sourceId", "lineStart", "lineEnd"],
939
+ "description": "ConflictSpan"
940
+ },
941
+ "authority": {
942
+ "type": "string",
943
+ "enum": ["primary", "secondary", "community"]
944
+ }
945
+ },
946
+ "required": ["claim"],
947
+ "description": "ConflictSide"
948
+ }
949
+ },
950
+ "suggested": {
951
+ "type": "integer",
952
+ "minimum": 0,
953
+ "maximum": 9007199254740991
954
+ }
955
+ },
956
+ "required": [
957
+ "severity",
958
+ "scopePath",
959
+ "issue",
960
+ "suggestedFix",
961
+ "kind",
962
+ "claimKey",
963
+ "sides"
964
+ ],
965
+ "description": "ConflictIssueContent"
769
966
  },
770
- "suggestedResolution": {
771
- "type": "string",
772
- "enum": ["keep_existing", "accept_new"]
967
+ {
968
+ "type": "object",
969
+ "properties": {
970
+ "severity": {
971
+ "type": "string",
972
+ "enum": ["critical", "suggestion"]
973
+ },
974
+ "scopePath": {
975
+ "type": "string"
976
+ },
977
+ "issue": {
978
+ "type": "string"
979
+ },
980
+ "suggestedFix": {
981
+ "type": "string"
982
+ },
983
+ "kind": {
984
+ "type": "string",
985
+ "enum": [
986
+ "gap",
987
+ "update_required",
988
+ "add_entry",
989
+ "remove_entry",
990
+ "split_entry",
991
+ "merge_entry"
992
+ ]
993
+ },
994
+ "citedSourceIds": {
995
+ "type": "array",
996
+ "items": {
997
+ "type": "string"
998
+ }
999
+ },
1000
+ "claimKey": {
1001
+ "type": "string"
1002
+ },
1003
+ "involvedScopes": {
1004
+ "type": "array",
1005
+ "items": {
1006
+ "type": "string"
1007
+ }
1008
+ }
1009
+ },
1010
+ "required": ["severity", "scopePath", "issue", "suggestedFix", "kind"],
1011
+ "description": "MechanicalIssueContent"
773
1012
  }
774
- },
775
- "required": ["kind", "severity", "scopePath", "issue", "suggestedFix"],
1013
+ ],
776
1014
  "description": "IssueContent"
777
1015
  },
778
1016
  "fingerprint": {
@@ -927,9 +1165,22 @@
927
1165
  "nullable": true,
928
1166
  "type": "string",
929
1167
  "enum": ["call", "result", null]
1168
+ },
1169
+ "error": {
1170
+ "default": null,
1171
+ "nullable": true,
1172
+ "type": "string",
1173
+ "maxLength": 20000
1174
+ },
1175
+ "timestamp": {
1176
+ "default": null,
1177
+ "nullable": true,
1178
+ "type": "string",
1179
+ "format": "date-time",
1180
+ "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
930
1181
  }
931
1182
  },
932
- "required": ["role", "content", "toolName", "toolType"],
1183
+ "required": ["role", "content", "toolName", "toolType", "error", "timestamp"],
933
1184
  "description": "ConversationMessage"
934
1185
  }
935
1186
  },
@@ -1366,6 +1617,21 @@
1366
1617
  "required": ["used", "limit"],
1367
1618
  "additionalProperties": false
1368
1619
  },
1620
+ "buildRestriction": {
1621
+ "nullable": true,
1622
+ "type": "object",
1623
+ "properties": {
1624
+ "code": {
1625
+ "type": "string"
1626
+ },
1627
+ "message": {
1628
+ "type": "string"
1629
+ }
1630
+ },
1631
+ "required": ["code", "message"],
1632
+ "additionalProperties": false,
1633
+ "description": "PlanRestriction"
1634
+ },
1369
1635
  "refreshEnabled": {
1370
1636
  "type": "boolean"
1371
1637
  },
@@ -1439,6 +1705,7 @@
1439
1705
  "hasWebSource",
1440
1706
  "hasDatasetSource",
1441
1707
  "sourceUsage",
1708
+ "buildRestriction",
1442
1709
  "refreshEnabled",
1443
1710
  "refreshFrequency",
1444
1711
  "refreshNextRunAt",
@@ -1685,6 +1952,21 @@
1685
1952
  "required": ["used", "limit"],
1686
1953
  "additionalProperties": false
1687
1954
  },
1955
+ "buildRestriction": {
1956
+ "nullable": true,
1957
+ "type": "object",
1958
+ "properties": {
1959
+ "code": {
1960
+ "type": "string"
1961
+ },
1962
+ "message": {
1963
+ "type": "string"
1964
+ }
1965
+ },
1966
+ "required": ["code", "message"],
1967
+ "additionalProperties": false,
1968
+ "description": "PlanRestriction"
1969
+ },
1688
1970
  "refreshEnabled": {
1689
1971
  "type": "boolean"
1690
1972
  },
@@ -1758,6 +2040,7 @@
1758
2040
  "hasWebSource",
1759
2041
  "hasDatasetSource",
1760
2042
  "sourceUsage",
2043
+ "buildRestriction",
1761
2044
  "refreshEnabled",
1762
2045
  "refreshFrequency",
1763
2046
  "refreshNextRunAt",
@@ -1971,6 +2254,21 @@
1971
2254
  "required": ["used", "limit"],
1972
2255
  "additionalProperties": false
1973
2256
  },
2257
+ "buildRestriction": {
2258
+ "nullable": true,
2259
+ "type": "object",
2260
+ "properties": {
2261
+ "code": {
2262
+ "type": "string"
2263
+ },
2264
+ "message": {
2265
+ "type": "string"
2266
+ }
2267
+ },
2268
+ "required": ["code", "message"],
2269
+ "additionalProperties": false,
2270
+ "description": "PlanRestriction"
2271
+ },
1974
2272
  "refreshEnabled": {
1975
2273
  "type": "boolean"
1976
2274
  },
@@ -2044,6 +2342,7 @@
2044
2342
  "hasWebSource",
2045
2343
  "hasDatasetSource",
2046
2344
  "sourceUsage",
2345
+ "buildRestriction",
2047
2346
  "refreshEnabled",
2048
2347
  "refreshFrequency",
2049
2348
  "refreshNextRunAt",
@@ -2284,6 +2583,21 @@
2284
2583
  "required": ["used", "limit"],
2285
2584
  "additionalProperties": false
2286
2585
  },
2586
+ "buildRestriction": {
2587
+ "nullable": true,
2588
+ "type": "object",
2589
+ "properties": {
2590
+ "code": {
2591
+ "type": "string"
2592
+ },
2593
+ "message": {
2594
+ "type": "string"
2595
+ }
2596
+ },
2597
+ "required": ["code", "message"],
2598
+ "additionalProperties": false,
2599
+ "description": "PlanRestriction"
2600
+ },
2287
2601
  "refreshEnabled": {
2288
2602
  "type": "boolean"
2289
2603
  },
@@ -2357,6 +2671,7 @@
2357
2671
  "hasWebSource",
2358
2672
  "hasDatasetSource",
2359
2673
  "sourceUsage",
2674
+ "buildRestriction",
2360
2675
  "refreshEnabled",
2361
2676
  "refreshFrequency",
2362
2677
  "refreshNextRunAt",
@@ -2379,7 +2694,7 @@
2379
2694
  "operationId": "deleteKnowledgeBase",
2380
2695
  "summary": "Delete a knowledge base",
2381
2696
  "tags": ["knowledge-bases"],
2382
- "description": "Removes the knowledge base and everything it owns: sources, imports, and revisions. Content documents in the bound dataset are deleted best-effort, and stored source files are reclaimed by a separate cleanup.",
2697
+ "description": "Removes the knowledge base and everything it owns: sources, imports, revisions, the content documents in the bound dataset, and the stored source files. Returns 409 `buildInFlight` while a build, refresh, apply, or import is running, since that work would write files back after the delete; retry once it finishes.",
2383
2698
  "parameters": [
2384
2699
  {
2385
2700
  "schema": {
@@ -2643,6 +2958,10 @@
2643
2958
  "nullable": true,
2644
2959
  "type": "string"
2645
2960
  },
2961
+ "externalId": {
2962
+ "nullable": true,
2963
+ "type": "string"
2964
+ },
2646
2965
  "fetchedAt": {
2647
2966
  "nullable": true,
2648
2967
  "type": "string",
@@ -2671,6 +2990,7 @@
2671
2990
  "tldr",
2672
2991
  "topics",
2673
2992
  "canonicalUrl",
2993
+ "externalId",
2674
2994
  "fetchedAt",
2675
2995
  "distilledAt",
2676
2996
  "createdAt"
@@ -2769,6 +3089,10 @@
2769
3089
  "nullable": true,
2770
3090
  "type": "string"
2771
3091
  },
3092
+ "externalId": {
3093
+ "nullable": true,
3094
+ "type": "string"
3095
+ },
2772
3096
  "fetchedAt": {
2773
3097
  "nullable": true,
2774
3098
  "type": "string",
@@ -2797,6 +3121,7 @@
2797
3121
  "tldr",
2798
3122
  "topics",
2799
3123
  "canonicalUrl",
3124
+ "externalId",
2800
3125
  "fetchedAt",
2801
3126
  "distilledAt",
2802
3127
  "createdAt"
@@ -3734,7 +4059,7 @@
3734
4059
  "operationId": "startUpload",
3735
4060
  "summary": "Start a file-upload import",
3736
4061
  "tags": ["imports"],
3737
- "description": "Creates a file-upload import and returns a single-use signed upload URL. PUT the file bytes to it, then call `POST .../imports/uploads/{importId}/complete` to start ingestion. The bytes never pass through this API. Supports the `Idempotency-Key` header.",
4062
+ "description": "Creates a file-upload import and returns a single-use signed upload URL, valid for one hour. PUT the file bytes to it, then call `POST .../imports/uploads/{importId}/complete` to start ingestion. When `contentType` is set, the PUT must send the same `Content-Type` header; when omitted, the PUT may send any or none. An import that is not completed within 24 hours is deleted. The bytes never pass through this API. Supports the `Idempotency-Key` header.",
3738
4063
  "requestBody": {
3739
4064
  "required": true,
3740
4065
  "content": {
@@ -3848,7 +4173,7 @@
3848
4173
  "operationId": "getJob",
3849
4174
  "summary": "Get a job by id",
3850
4175
  "tags": ["jobs"],
3851
- "description": "Returns the status of a job, such as a build or an import. Job ids come from the endpoint that queued the work.",
4176
+ "description": "Returns the status of a job, such as a build, an import, or a refresh. Job ids come from the endpoint that queued the work.",
3852
4177
  "parameters": [
3853
4178
  {
3854
4179
  "schema": {
@@ -4013,69 +4338,151 @@
4013
4338
  "type": "string"
4014
4339
  },
4015
4340
  "content": {
4016
- "type": "object",
4017
- "properties": {
4018
- "kind": {
4019
- "type": "string",
4020
- "enum": [
4021
- "conflict",
4022
- "gap",
4023
- "update_required",
4024
- "add_entry",
4025
- "remove_entry",
4026
- "split_entry",
4027
- "merge_entry"
4028
- ]
4029
- },
4030
- "severity": {
4031
- "type": "string",
4032
- "enum": ["critical", "suggestion"]
4033
- },
4034
- "scopePath": {
4035
- "type": "string"
4036
- },
4037
- "issue": {
4038
- "type": "string"
4039
- },
4040
- "suggestedFix": {
4041
- "type": "string"
4042
- },
4043
- "citedSourceIds": {
4044
- "type": "array",
4045
- "items": {
4046
- "type": "string"
4047
- }
4048
- },
4049
- "claimKey": {
4050
- "type": "string"
4051
- },
4052
- "involvedScopes": {
4053
- "type": "array",
4054
- "items": {
4055
- "type": "string"
4056
- }
4057
- },
4058
- "currentClaim": {
4059
- "type": "string"
4060
- },
4061
- "alternativeClaim": {
4062
- "type": "string"
4063
- },
4064
- "currentAuthority": {
4065
- "type": "string",
4066
- "enum": ["primary", "secondary", "community"]
4067
- },
4068
- "alternativeAuthority": {
4069
- "type": "string",
4070
- "enum": ["primary", "secondary", "community"]
4341
+ "oneOf": [
4342
+ {
4343
+ "type": "object",
4344
+ "properties": {
4345
+ "severity": {
4346
+ "type": "string",
4347
+ "enum": ["critical", "suggestion"]
4348
+ },
4349
+ "scopePath": {
4350
+ "type": "string"
4351
+ },
4352
+ "issue": {
4353
+ "type": "string"
4354
+ },
4355
+ "suggestedFix": {
4356
+ "type": "string"
4357
+ },
4358
+ "kind": {
4359
+ "type": "string",
4360
+ "enum": ["conflict"]
4361
+ },
4362
+ "claimKey": {
4363
+ "type": "string"
4364
+ },
4365
+ "sides": {
4366
+ "minItems": 2,
4367
+ "type": "array",
4368
+ "items": {
4369
+ "type": "object",
4370
+ "properties": {
4371
+ "claim": {
4372
+ "type": "string"
4373
+ },
4374
+ "value": {
4375
+ "type": "string"
4376
+ },
4377
+ "entryPaths": {
4378
+ "type": "array",
4379
+ "items": {
4380
+ "type": "string"
4381
+ }
4382
+ },
4383
+ "sourceIds": {
4384
+ "type": "array",
4385
+ "items": {
4386
+ "type": "string"
4387
+ }
4388
+ },
4389
+ "span": {
4390
+ "type": "object",
4391
+ "properties": {
4392
+ "sourceId": {
4393
+ "type": "string"
4394
+ },
4395
+ "lineStart": {
4396
+ "type": "integer",
4397
+ "minimum": 1,
4398
+ "maximum": 9007199254740991
4399
+ },
4400
+ "lineEnd": {
4401
+ "type": "integer",
4402
+ "minimum": 1,
4403
+ "maximum": 9007199254740991
4404
+ }
4405
+ },
4406
+ "required": ["sourceId", "lineStart", "lineEnd"],
4407
+ "additionalProperties": false,
4408
+ "description": "ConflictSpan"
4409
+ },
4410
+ "authority": {
4411
+ "type": "string",
4412
+ "enum": ["primary", "secondary", "community"]
4413
+ }
4414
+ },
4415
+ "required": ["claim"],
4416
+ "additionalProperties": false,
4417
+ "description": "ConflictSide"
4418
+ }
4419
+ },
4420
+ "suggested": {
4421
+ "type": "integer",
4422
+ "minimum": 0,
4423
+ "maximum": 9007199254740991
4424
+ }
4425
+ },
4426
+ "required": [
4427
+ "severity",
4428
+ "scopePath",
4429
+ "issue",
4430
+ "suggestedFix",
4431
+ "kind",
4432
+ "claimKey",
4433
+ "sides"
4434
+ ],
4435
+ "additionalProperties": false,
4436
+ "description": "ConflictIssueContent"
4071
4437
  },
4072
- "suggestedResolution": {
4073
- "type": "string",
4074
- "enum": ["keep_existing", "accept_new"]
4438
+ {
4439
+ "type": "object",
4440
+ "properties": {
4441
+ "severity": {
4442
+ "type": "string",
4443
+ "enum": ["critical", "suggestion"]
4444
+ },
4445
+ "scopePath": {
4446
+ "type": "string"
4447
+ },
4448
+ "issue": {
4449
+ "type": "string"
4450
+ },
4451
+ "suggestedFix": {
4452
+ "type": "string"
4453
+ },
4454
+ "kind": {
4455
+ "type": "string",
4456
+ "enum": [
4457
+ "gap",
4458
+ "update_required",
4459
+ "add_entry",
4460
+ "remove_entry",
4461
+ "split_entry",
4462
+ "merge_entry"
4463
+ ]
4464
+ },
4465
+ "citedSourceIds": {
4466
+ "type": "array",
4467
+ "items": {
4468
+ "type": "string"
4469
+ }
4470
+ },
4471
+ "claimKey": {
4472
+ "type": "string"
4473
+ },
4474
+ "involvedScopes": {
4475
+ "type": "array",
4476
+ "items": {
4477
+ "type": "string"
4478
+ }
4479
+ }
4480
+ },
4481
+ "required": ["severity", "scopePath", "issue", "suggestedFix", "kind"],
4482
+ "additionalProperties": false,
4483
+ "description": "MechanicalIssueContent"
4075
4484
  }
4076
- },
4077
- "required": ["kind", "severity", "scopePath", "issue", "suggestedFix"],
4078
- "additionalProperties": false,
4485
+ ],
4079
4486
  "description": "IssueContent"
4080
4487
  },
4081
4488
  "status": {
@@ -4084,8 +4491,9 @@
4084
4491
  },
4085
4492
  "resolution": {
4086
4493
  "nullable": true,
4087
- "type": "string",
4088
- "enum": ["keep_existing", "accept_new"]
4494
+ "type": "integer",
4495
+ "minimum": 0,
4496
+ "maximum": 9007199254740991
4089
4497
  },
4090
4498
  "resolvedBy": {
4091
4499
  "nullable": true,
@@ -4139,7 +4547,7 @@
4139
4547
  "operationId": "resolveIssue",
4140
4548
  "summary": "Resolve a conflict issue",
4141
4549
  "tags": ["issues"],
4142
- "description": "Settles a conflict with one of two choices: `keep_existing` or `accept_new` (rewrites the entry; the returned `jobId` tracks it). Only conflict issues are resolvable, and a dismissed issue must be reopened first. The decision becomes a standing instruction for every future build; `resolvedBy` records who decided.",
4550
+ "description": "Settles a conflict by choosing a side: `resolution` is an index into `content.sides`. Index 0 of a per-entry conflict is the entry's own position, so choosing it keeps the body; any other side rewrites the entry (the returned `jobId` tracks it). Only conflict issues are resolvable, and a dismissed issue must be reopened first. The decision becomes a standing instruction for every future build; `resolvedBy` records who decided.",
4143
4551
  "requestBody": {
4144
4552
  "required": true,
4145
4553
  "content": {
@@ -4148,8 +4556,9 @@
4148
4556
  "type": "object",
4149
4557
  "properties": {
4150
4558
  "resolution": {
4151
- "type": "string",
4152
- "enum": ["keep_existing", "accept_new"]
4559
+ "type": "integer",
4560
+ "minimum": 0,
4561
+ "maximum": 9007199254740991
4153
4562
  }
4154
4563
  },
4155
4564
  "required": ["resolution"]
@@ -4195,69 +4604,157 @@
4195
4604
  "type": "string"
4196
4605
  },
4197
4606
  "content": {
4198
- "type": "object",
4199
- "properties": {
4200
- "kind": {
4201
- "type": "string",
4202
- "enum": [
4203
- "conflict",
4204
- "gap",
4205
- "update_required",
4206
- "add_entry",
4207
- "remove_entry",
4208
- "split_entry",
4209
- "merge_entry"
4210
- ]
4211
- },
4212
- "severity": {
4213
- "type": "string",
4214
- "enum": ["critical", "suggestion"]
4215
- },
4216
- "scopePath": {
4217
- "type": "string"
4218
- },
4219
- "issue": {
4220
- "type": "string"
4221
- },
4222
- "suggestedFix": {
4223
- "type": "string"
4224
- },
4225
- "citedSourceIds": {
4226
- "type": "array",
4227
- "items": {
4228
- "type": "string"
4229
- }
4230
- },
4231
- "claimKey": {
4232
- "type": "string"
4233
- },
4234
- "involvedScopes": {
4235
- "type": "array",
4236
- "items": {
4237
- "type": "string"
4238
- }
4239
- },
4240
- "currentClaim": {
4241
- "type": "string"
4242
- },
4243
- "alternativeClaim": {
4244
- "type": "string"
4245
- },
4246
- "currentAuthority": {
4247
- "type": "string",
4248
- "enum": ["primary", "secondary", "community"]
4249
- },
4250
- "alternativeAuthority": {
4251
- "type": "string",
4252
- "enum": ["primary", "secondary", "community"]
4607
+ "oneOf": [
4608
+ {
4609
+ "type": "object",
4610
+ "properties": {
4611
+ "severity": {
4612
+ "type": "string",
4613
+ "enum": ["critical", "suggestion"]
4614
+ },
4615
+ "scopePath": {
4616
+ "type": "string"
4617
+ },
4618
+ "issue": {
4619
+ "type": "string"
4620
+ },
4621
+ "suggestedFix": {
4622
+ "type": "string"
4623
+ },
4624
+ "kind": {
4625
+ "type": "string",
4626
+ "enum": ["conflict"]
4627
+ },
4628
+ "claimKey": {
4629
+ "type": "string"
4630
+ },
4631
+ "sides": {
4632
+ "minItems": 2,
4633
+ "type": "array",
4634
+ "items": {
4635
+ "type": "object",
4636
+ "properties": {
4637
+ "claim": {
4638
+ "type": "string"
4639
+ },
4640
+ "value": {
4641
+ "type": "string"
4642
+ },
4643
+ "entryPaths": {
4644
+ "type": "array",
4645
+ "items": {
4646
+ "type": "string"
4647
+ }
4648
+ },
4649
+ "sourceIds": {
4650
+ "type": "array",
4651
+ "items": {
4652
+ "type": "string"
4653
+ }
4654
+ },
4655
+ "span": {
4656
+ "type": "object",
4657
+ "properties": {
4658
+ "sourceId": {
4659
+ "type": "string"
4660
+ },
4661
+ "lineStart": {
4662
+ "type": "integer",
4663
+ "minimum": 1,
4664
+ "maximum": 9007199254740991
4665
+ },
4666
+ "lineEnd": {
4667
+ "type": "integer",
4668
+ "minimum": 1,
4669
+ "maximum": 9007199254740991
4670
+ }
4671
+ },
4672
+ "required": ["sourceId", "lineStart", "lineEnd"],
4673
+ "additionalProperties": false,
4674
+ "description": "ConflictSpan"
4675
+ },
4676
+ "authority": {
4677
+ "type": "string",
4678
+ "enum": ["primary", "secondary", "community"]
4679
+ }
4680
+ },
4681
+ "required": ["claim"],
4682
+ "additionalProperties": false,
4683
+ "description": "ConflictSide"
4684
+ }
4685
+ },
4686
+ "suggested": {
4687
+ "type": "integer",
4688
+ "minimum": 0,
4689
+ "maximum": 9007199254740991
4690
+ }
4691
+ },
4692
+ "required": [
4693
+ "severity",
4694
+ "scopePath",
4695
+ "issue",
4696
+ "suggestedFix",
4697
+ "kind",
4698
+ "claimKey",
4699
+ "sides"
4700
+ ],
4701
+ "additionalProperties": false,
4702
+ "description": "ConflictIssueContent"
4253
4703
  },
4254
- "suggestedResolution": {
4255
- "type": "string",
4256
- "enum": ["keep_existing", "accept_new"]
4704
+ {
4705
+ "type": "object",
4706
+ "properties": {
4707
+ "severity": {
4708
+ "type": "string",
4709
+ "enum": ["critical", "suggestion"]
4710
+ },
4711
+ "scopePath": {
4712
+ "type": "string"
4713
+ },
4714
+ "issue": {
4715
+ "type": "string"
4716
+ },
4717
+ "suggestedFix": {
4718
+ "type": "string"
4719
+ },
4720
+ "kind": {
4721
+ "type": "string",
4722
+ "enum": [
4723
+ "gap",
4724
+ "update_required",
4725
+ "add_entry",
4726
+ "remove_entry",
4727
+ "split_entry",
4728
+ "merge_entry"
4729
+ ]
4730
+ },
4731
+ "citedSourceIds": {
4732
+ "type": "array",
4733
+ "items": {
4734
+ "type": "string"
4735
+ }
4736
+ },
4737
+ "claimKey": {
4738
+ "type": "string"
4739
+ },
4740
+ "involvedScopes": {
4741
+ "type": "array",
4742
+ "items": {
4743
+ "type": "string"
4744
+ }
4745
+ }
4746
+ },
4747
+ "required": [
4748
+ "severity",
4749
+ "scopePath",
4750
+ "issue",
4751
+ "suggestedFix",
4752
+ "kind"
4753
+ ],
4754
+ "additionalProperties": false,
4755
+ "description": "MechanicalIssueContent"
4257
4756
  }
4258
- },
4259
- "required": ["kind", "severity", "scopePath", "issue", "suggestedFix"],
4260
- "additionalProperties": false,
4757
+ ],
4261
4758
  "description": "IssueContent"
4262
4759
  },
4263
4760
  "status": {
@@ -4266,8 +4763,9 @@
4266
4763
  },
4267
4764
  "resolution": {
4268
4765
  "nullable": true,
4269
- "type": "string",
4270
- "enum": ["keep_existing", "accept_new"]
4766
+ "type": "integer",
4767
+ "minimum": 0,
4768
+ "maximum": 9007199254740991
4271
4769
  },
4272
4770
  "resolvedBy": {
4273
4771
  "nullable": true,
@@ -4366,69 +4864,151 @@
4366
4864
  "type": "string"
4367
4865
  },
4368
4866
  "content": {
4369
- "type": "object",
4370
- "properties": {
4371
- "kind": {
4372
- "type": "string",
4373
- "enum": [
4374
- "conflict",
4375
- "gap",
4376
- "update_required",
4377
- "add_entry",
4378
- "remove_entry",
4379
- "split_entry",
4380
- "merge_entry"
4381
- ]
4382
- },
4383
- "severity": {
4384
- "type": "string",
4385
- "enum": ["critical", "suggestion"]
4386
- },
4387
- "scopePath": {
4388
- "type": "string"
4389
- },
4390
- "issue": {
4391
- "type": "string"
4392
- },
4393
- "suggestedFix": {
4394
- "type": "string"
4395
- },
4396
- "citedSourceIds": {
4397
- "type": "array",
4398
- "items": {
4399
- "type": "string"
4400
- }
4401
- },
4402
- "claimKey": {
4403
- "type": "string"
4404
- },
4405
- "involvedScopes": {
4406
- "type": "array",
4407
- "items": {
4408
- "type": "string"
4409
- }
4410
- },
4411
- "currentClaim": {
4412
- "type": "string"
4413
- },
4414
- "alternativeClaim": {
4415
- "type": "string"
4416
- },
4417
- "currentAuthority": {
4418
- "type": "string",
4419
- "enum": ["primary", "secondary", "community"]
4420
- },
4421
- "alternativeAuthority": {
4422
- "type": "string",
4423
- "enum": ["primary", "secondary", "community"]
4867
+ "oneOf": [
4868
+ {
4869
+ "type": "object",
4870
+ "properties": {
4871
+ "severity": {
4872
+ "type": "string",
4873
+ "enum": ["critical", "suggestion"]
4874
+ },
4875
+ "scopePath": {
4876
+ "type": "string"
4877
+ },
4878
+ "issue": {
4879
+ "type": "string"
4880
+ },
4881
+ "suggestedFix": {
4882
+ "type": "string"
4883
+ },
4884
+ "kind": {
4885
+ "type": "string",
4886
+ "enum": ["conflict"]
4887
+ },
4888
+ "claimKey": {
4889
+ "type": "string"
4890
+ },
4891
+ "sides": {
4892
+ "minItems": 2,
4893
+ "type": "array",
4894
+ "items": {
4895
+ "type": "object",
4896
+ "properties": {
4897
+ "claim": {
4898
+ "type": "string"
4899
+ },
4900
+ "value": {
4901
+ "type": "string"
4902
+ },
4903
+ "entryPaths": {
4904
+ "type": "array",
4905
+ "items": {
4906
+ "type": "string"
4907
+ }
4908
+ },
4909
+ "sourceIds": {
4910
+ "type": "array",
4911
+ "items": {
4912
+ "type": "string"
4913
+ }
4914
+ },
4915
+ "span": {
4916
+ "type": "object",
4917
+ "properties": {
4918
+ "sourceId": {
4919
+ "type": "string"
4920
+ },
4921
+ "lineStart": {
4922
+ "type": "integer",
4923
+ "minimum": 1,
4924
+ "maximum": 9007199254740991
4925
+ },
4926
+ "lineEnd": {
4927
+ "type": "integer",
4928
+ "minimum": 1,
4929
+ "maximum": 9007199254740991
4930
+ }
4931
+ },
4932
+ "required": ["sourceId", "lineStart", "lineEnd"],
4933
+ "additionalProperties": false,
4934
+ "description": "ConflictSpan"
4935
+ },
4936
+ "authority": {
4937
+ "type": "string",
4938
+ "enum": ["primary", "secondary", "community"]
4939
+ }
4940
+ },
4941
+ "required": ["claim"],
4942
+ "additionalProperties": false,
4943
+ "description": "ConflictSide"
4944
+ }
4945
+ },
4946
+ "suggested": {
4947
+ "type": "integer",
4948
+ "minimum": 0,
4949
+ "maximum": 9007199254740991
4950
+ }
4951
+ },
4952
+ "required": [
4953
+ "severity",
4954
+ "scopePath",
4955
+ "issue",
4956
+ "suggestedFix",
4957
+ "kind",
4958
+ "claimKey",
4959
+ "sides"
4960
+ ],
4961
+ "additionalProperties": false,
4962
+ "description": "ConflictIssueContent"
4424
4963
  },
4425
- "suggestedResolution": {
4426
- "type": "string",
4427
- "enum": ["keep_existing", "accept_new"]
4964
+ {
4965
+ "type": "object",
4966
+ "properties": {
4967
+ "severity": {
4968
+ "type": "string",
4969
+ "enum": ["critical", "suggestion"]
4970
+ },
4971
+ "scopePath": {
4972
+ "type": "string"
4973
+ },
4974
+ "issue": {
4975
+ "type": "string"
4976
+ },
4977
+ "suggestedFix": {
4978
+ "type": "string"
4979
+ },
4980
+ "kind": {
4981
+ "type": "string",
4982
+ "enum": [
4983
+ "gap",
4984
+ "update_required",
4985
+ "add_entry",
4986
+ "remove_entry",
4987
+ "split_entry",
4988
+ "merge_entry"
4989
+ ]
4990
+ },
4991
+ "citedSourceIds": {
4992
+ "type": "array",
4993
+ "items": {
4994
+ "type": "string"
4995
+ }
4996
+ },
4997
+ "claimKey": {
4998
+ "type": "string"
4999
+ },
5000
+ "involvedScopes": {
5001
+ "type": "array",
5002
+ "items": {
5003
+ "type": "string"
5004
+ }
5005
+ }
5006
+ },
5007
+ "required": ["severity", "scopePath", "issue", "suggestedFix", "kind"],
5008
+ "additionalProperties": false,
5009
+ "description": "MechanicalIssueContent"
4428
5010
  }
4429
- },
4430
- "required": ["kind", "severity", "scopePath", "issue", "suggestedFix"],
4431
- "additionalProperties": false,
5011
+ ],
4432
5012
  "description": "IssueContent"
4433
5013
  },
4434
5014
  "status": {
@@ -4437,8 +5017,9 @@
4437
5017
  },
4438
5018
  "resolution": {
4439
5019
  "nullable": true,
4440
- "type": "string",
4441
- "enum": ["keep_existing", "accept_new"]
5020
+ "type": "integer",
5021
+ "minimum": 0,
5022
+ "maximum": 9007199254740991
4442
5023
  },
4443
5024
  "resolvedBy": {
4444
5025
  "nullable": true,
@@ -4492,7 +5073,7 @@
4492
5073
  "operationId": "createInstruction",
4493
5074
  "summary": "Author a human instruction",
4494
5075
  "tags": ["instructions"],
4495
- "description": "Creates a standing rule that every future build honors. Tie it to one or more sources with `scopeSourceIds`, or leave it null to apply knowledge-base-wide. Pass `rebuildPaths` to immediately rebuild those entries under the new rule; the response carries the rebuild job id, or null when the rebuild could not start (the rule is saved either way). Pass `verified` after a completed synchronous contradiction check to skip the background one; if the requested rebuild fails to start, the background check runs anyway so the contradicting pages get filed as issues.",
5076
+ "description": "Creates a standing rule for how entries citing its sources are written. Tie it to one or more sources with `scopeSourceIds`; every rule is source-tied. Pass `rebuildPaths` to immediately rebuild those entries under the new rule; the response carries the rebuild job id, or null when the rebuild could not start (the rule is saved either way). Pass `verified` after a completed synchronous contradiction check to skip the background one; if the requested rebuild fails to start, the background check runs anyway so the contradicting pages get filed as issues.",
4496
5077
  "requestBody": {
4497
5078
  "required": true,
4498
5079
  "content": {
@@ -4506,7 +5087,6 @@
4506
5087
  "maxLength": 2000
4507
5088
  },
4508
5089
  "scopeSourceIds": {
4509
- "nullable": true,
4510
5090
  "minItems": 1,
4511
5091
  "maxItems": 100,
4512
5092
  "type": "array",
@@ -4529,7 +5109,7 @@
4529
5109
  "type": "boolean"
4530
5110
  }
4531
5111
  },
4532
- "required": ["statement"],
5112
+ "required": ["statement", "scopeSourceIds"],
4533
5113
  "description": "CreateInstructionInput"
4534
5114
  }
4535
5115
  }
@@ -4576,7 +5156,6 @@
4576
5156
  "type": "string"
4577
5157
  },
4578
5158
  "scopeSourceIds": {
4579
- "nullable": true,
4580
5159
  "type": "array",
4581
5160
  "items": {
4582
5161
  "type": "string",
@@ -4696,7 +5275,6 @@
4696
5275
  "maxLength": 2000
4697
5276
  },
4698
5277
  "scopeSourceIds": {
4699
- "nullable": true,
4700
5278
  "minItems": 1,
4701
5279
  "maxItems": 100,
4702
5280
  "type": "array",
@@ -4759,7 +5337,6 @@
4759
5337
  "type": "string"
4760
5338
  },
4761
5339
  "scopeSourceIds": {
4762
- "nullable": true,
4763
5340
  "type": "array",
4764
5341
  "items": {
4765
5342
  "type": "string",
@@ -5093,322 +5670,12 @@
5093
5670
  }
5094
5671
  }
5095
5672
  },
5096
- "/{apiVersion}/context/organizations/{organizationId}/mcp/{mcpEndpointName}/status": {
5097
- "get": {
5098
- "operationId": "getMcpEndpointStatus",
5099
- "summary": "Pre-flight checks for an MCP endpoint",
5100
- "tags": ["mcp"],
5101
- "description": "Verifies the endpoint can serve a connection with this credential: Studio deployment and schema (GROQ mode), semantic search readiness, and knowledge-base resolution — reporting denied and missing knowledge bases distinctly. Always 200 with per-check verdicts; `requiredOk` is mode-aware.",
5102
- "parameters": [
5103
- {
5104
- "schema": {
5105
- "type": "string"
5106
- },
5107
- "in": "query",
5108
- "name": "tools",
5109
- "required": false
5110
- },
5111
- {
5112
- "schema": {
5113
- "type": "string"
5114
- },
5115
- "in": "query",
5116
- "name": "instructions",
5117
- "required": false
5118
- },
5119
- {
5120
- "schema": {
5121
- "type": "string"
5122
- },
5123
- "in": "query",
5124
- "name": "perspective",
5125
- "required": false
5126
- },
5127
- {
5128
- "schema": {
5129
- "type": "string"
5130
- },
5131
- "in": "query",
5132
- "name": "embeddings",
5133
- "required": false
5134
- },
5135
- {
5136
- "schema": {
5137
- "type": "string"
5138
- },
5139
- "in": "query",
5140
- "name": "groqFilter",
5141
- "required": false
5142
- },
5143
- {
5144
- "schema": {
5145
- "type": "string",
5146
- "enum": ["knowledge_base", "groq"]
5147
- },
5148
- "in": "query",
5149
- "name": "mode",
5150
- "required": false
5151
- },
5152
- {
5153
- "schema": {
5154
- "type": "string"
5155
- },
5156
- "in": "query",
5157
- "name": "knowledgeBases",
5158
- "required": false
5159
- },
5160
- {
5161
- "schema": {
5162
- "type": "string"
5163
- },
5164
- "in": "query",
5165
- "name": "linkResolver",
5166
- "required": false
5167
- },
5168
- {
5169
- "schema": {
5170
- "type": "string"
5171
- },
5172
- "in": "query",
5173
- "name": "workspace",
5174
- "required": false
5175
- },
5176
- {
5177
- "schema": {
5178
- "type": "string",
5179
- "minLength": 1
5180
- },
5181
- "in": "path",
5182
- "name": "mcpEndpointName",
5183
- "required": true
5184
- }
5185
- ],
5186
- "responses": {
5187
- "200": {
5188
- "description": "Default Response",
5189
- "content": {
5190
- "application/json": {
5191
- "schema": {
5192
- "type": "object",
5193
- "properties": {
5194
- "requiredOk": {
5195
- "type": "boolean"
5196
- },
5197
- "checks": {
5198
- "type": "object",
5199
- "properties": {
5200
- "studio": {
5201
- "anyOf": [
5202
- {
5203
- "type": "object",
5204
- "properties": {
5205
- "ok": {
5206
- "type": "boolean",
5207
- "enum": [true]
5208
- },
5209
- "workspace": {
5210
- "type": "string"
5211
- },
5212
- "workspaceTitle": {
5213
- "type": "string"
5214
- },
5215
- "workspaceAutoSelected": {
5216
- "type": "boolean"
5217
- },
5218
- "availableWorkspaces": {
5219
- "type": "array",
5220
- "items": {
5221
- "type": "object",
5222
- "properties": {
5223
- "name": {
5224
- "type": "string"
5225
- },
5226
- "title": {
5227
- "type": "string"
5228
- }
5229
- },
5230
- "required": ["name", "title"],
5231
- "additionalProperties": false
5232
- }
5233
- }
5234
- },
5235
- "required": [
5236
- "ok",
5237
- "workspace",
5238
- "workspaceTitle",
5239
- "workspaceAutoSelected",
5240
- "availableWorkspaces"
5241
- ],
5242
- "additionalProperties": false
5243
- },
5244
- {
5245
- "type": "object",
5246
- "properties": {
5247
- "ok": {
5248
- "type": "boolean",
5249
- "enum": [false]
5250
- },
5251
- "error": {
5252
- "type": "string"
5253
- }
5254
- },
5255
- "required": ["ok", "error"],
5256
- "additionalProperties": false
5257
- }
5258
- ]
5259
- },
5260
- "semanticSearch": {
5261
- "nullable": true,
5262
- "anyOf": [
5263
- {
5264
- "type": "object",
5265
- "properties": {
5266
- "ok": {
5267
- "type": "boolean",
5268
- "enum": [true]
5269
- },
5270
- "enabled": {
5271
- "type": "boolean"
5272
- },
5273
- "status": {
5274
- "nullable": true,
5275
- "type": "string"
5276
- },
5277
- "withinUsageLimit": {
5278
- "nullable": true,
5279
- "type": "boolean"
5280
- }
5281
- },
5282
- "required": ["ok", "enabled", "status", "withinUsageLimit"],
5283
- "additionalProperties": false
5284
- },
5285
- {
5286
- "type": "object",
5287
- "properties": {
5288
- "ok": {
5289
- "type": "boolean",
5290
- "enum": [false]
5291
- },
5292
- "error": {
5293
- "type": "string"
5294
- }
5295
- },
5296
- "required": ["ok", "error"],
5297
- "additionalProperties": false
5298
- }
5299
- ]
5300
- },
5301
- "schema": {
5302
- "anyOf": [
5303
- {
5304
- "type": "object",
5305
- "properties": {
5306
- "ok": {
5307
- "type": "boolean",
5308
- "enum": [true]
5309
- },
5310
- "documentTypes": {
5311
- "type": "number"
5312
- }
5313
- },
5314
- "required": ["ok", "documentTypes"],
5315
- "additionalProperties": false
5316
- },
5317
- {
5318
- "type": "object",
5319
- "properties": {
5320
- "ok": {
5321
- "type": "boolean",
5322
- "enum": [false]
5323
- },
5324
- "error": {
5325
- "type": "string"
5326
- }
5327
- },
5328
- "required": ["ok", "error"],
5329
- "additionalProperties": false
5330
- }
5331
- ]
5332
- },
5333
- "knowledgeBases": {
5334
- "anyOf": [
5335
- {
5336
- "type": "object",
5337
- "properties": {
5338
- "ok": {
5339
- "type": "boolean",
5340
- "enum": [true]
5341
- },
5342
- "resolved": {
5343
- "type": "array",
5344
- "items": {
5345
- "type": "string"
5346
- }
5347
- },
5348
- "missing": {
5349
- "type": "array",
5350
- "items": {
5351
- "type": "string"
5352
- }
5353
- }
5354
- },
5355
- "required": ["ok", "resolved", "missing"],
5356
- "additionalProperties": false
5357
- },
5358
- {
5359
- "type": "object",
5360
- "properties": {
5361
- "ok": {
5362
- "type": "boolean",
5363
- "enum": [false]
5364
- },
5365
- "resolved": {
5366
- "type": "array",
5367
- "items": {
5368
- "type": "string"
5369
- }
5370
- },
5371
- "missing": {
5372
- "type": "array",
5373
- "items": {
5374
- "type": "string"
5375
- }
5376
- },
5377
- "denied": {
5378
- "type": "array",
5379
- "items": {
5380
- "type": "string"
5381
- }
5382
- },
5383
- "error": {
5384
- "type": "string"
5385
- }
5386
- },
5387
- "required": ["ok", "resolved", "missing", "error"],
5388
- "additionalProperties": false
5389
- }
5390
- ]
5391
- }
5392
- },
5393
- "required": ["studio", "semanticSearch", "schema", "knowledgeBases"],
5394
- "additionalProperties": false
5395
- }
5396
- },
5397
- "required": ["requiredOk", "checks"],
5398
- "additionalProperties": false
5399
- }
5400
- }
5401
- }
5402
- }
5403
- }
5404
- }
5405
- },
5406
5673
  "/{apiVersion}/context/organizations/{organizationId}/conversations/{threadId}": {
5407
5674
  "put": {
5408
5675
  "operationId": "saveConversation",
5409
5676
  "summary": "Record a conversation",
5410
5677
  "tags": ["conversations"],
5411
- "description": "Upserts the conversation telemetry for one thread. `threadId` identifies the conversation within your organization — reuse means the same conversation. Messages replace the stored transcript wholesale; `metadata`, `sharing`, and model fields only overwrite when present. Last write per thread wins — retries are safe. `sharing` records your opt-in to share telemetry with Sanity: metadata-only metrics, or full transcripts.",
5678
+ "description": "Upserts the conversation telemetry for one thread. `threadId` identifies the conversation within your organization — reuse means the same conversation. Messages replace the stored transcript wholesale; `metadata`, `sharing`, and model fields only overwrite when present. `tokenUsage` accumulates: each save reports one generation call and the stored value is the conversation total, added only when the save changes the transcript so retries never double-count. Report a failure as `error` on the message where it happened: a tool result for a failed tool call, an assistant message for a turn that failed instead of answering. The dashboard highlights conversations with a failed turn and counts failed tool calls separately, since agents often recover from one. Last write per thread wins — retries are safe. `sharing` records your opt-in to share telemetry with Sanity: metadata-only metrics, or full transcripts.",
5412
5679
  "requestBody": {
5413
5680
  "required": true,
5414
5681
  "content": {
@@ -5442,10 +5709,16 @@
5442
5709
  "nullable": true,
5443
5710
  "type": "string",
5444
5711
  "enum": ["call", "result"]
5712
+ },
5713
+ "error": {
5714
+ "default": null,
5715
+ "nullable": true,
5716
+ "type": "string",
5717
+ "maxLength": 20000
5445
5718
  }
5446
5719
  },
5447
5720
  "required": ["role"],
5448
- "description": "ConversationMessage"
5721
+ "description": "ConversationMessageInput"
5449
5722
  }
5450
5723
  },
5451
5724
  "modelProvider": {
@@ -5595,9 +5868,29 @@
5595
5868
  "nullable": true,
5596
5869
  "type": "string",
5597
5870
  "enum": ["call", "result"]
5871
+ },
5872
+ "error": {
5873
+ "default": null,
5874
+ "nullable": true,
5875
+ "type": "string",
5876
+ "maxLength": 20000
5877
+ },
5878
+ "timestamp": {
5879
+ "default": null,
5880
+ "nullable": true,
5881
+ "type": "string",
5882
+ "format": "date-time",
5883
+ "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
5598
5884
  }
5599
5885
  },
5600
- "required": ["role", "content", "toolName", "toolType"],
5886
+ "required": [
5887
+ "role",
5888
+ "content",
5889
+ "toolName",
5890
+ "toolType",
5891
+ "error",
5892
+ "timestamp"
5893
+ ],
5601
5894
  "additionalProperties": false,
5602
5895
  "description": "ConversationMessage"
5603
5896
  }
@@ -5840,9 +6133,29 @@
5840
6133
  "nullable": true,
5841
6134
  "type": "string",
5842
6135
  "enum": ["call", "result"]
6136
+ },
6137
+ "error": {
6138
+ "default": null,
6139
+ "nullable": true,
6140
+ "type": "string",
6141
+ "maxLength": 20000
6142
+ },
6143
+ "timestamp": {
6144
+ "default": null,
6145
+ "nullable": true,
6146
+ "type": "string",
6147
+ "format": "date-time",
6148
+ "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
5843
6149
  }
5844
6150
  },
5845
- "required": ["role", "content", "toolName", "toolType"],
6151
+ "required": [
6152
+ "role",
6153
+ "content",
6154
+ "toolName",
6155
+ "toolType",
6156
+ "error",
6157
+ "timestamp"
6158
+ ],
5846
6159
  "additionalProperties": false,
5847
6160
  "description": "ConversationMessage"
5848
6161
  }