@serviceai/api-spec 1.1.23 → 1.1.24

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 (4) hide show
  1. package/openapi.json +1026 -2
  2. package/openapi.yaml +630 -2
  3. package/package.json +1 -1
  4. package/types.d.ts +616 -1
package/openapi.json CHANGED
@@ -2,7 +2,7 @@
2
2
  "openapi": "3.1.0",
3
3
  "info": {
4
4
  "title": "ServiceAi API",
5
- "version": "1.1.23",
5
+ "version": "1.1.24",
6
6
  "description": "Source-of-truth API contract for ServiceAi. Generated from `shared/schema.ts` Zod schemas by `scripts/build-api-spec.ts`. Versioning policy: see `docs/api-versioning.md`. The hand-written docs/ios-contract.md and docs/lidar-mobile-upload-contract.md are human-readable design notes only — this spec is the canonical wire contract.",
7
7
  "license": {
8
8
  "name": "Proprietary",
@@ -114,7 +114,7 @@
114
114
  "properties": {
115
115
  "apiVersion": {
116
116
  "type": "string",
117
- "example": "1.1.23"
117
+ "example": "1.1.24"
118
118
  },
119
119
  "minClientVersion": {
120
120
  "type": "string",
@@ -2598,6 +2598,260 @@
2598
2598
  "mirrorX"
2599
2599
  ],
2600
2600
  "description": "Persisted floor-plan PNG render-frame. `mirrorX` is derived from `scans.client_mirror_applied` (negate when false). Null sentinel: ANY required column NULL → `null` is emitted instead of a partial frame."
2601
+ },
2602
+ "ChattyToolDefinition": {
2603
+ "type": "object",
2604
+ "properties": {
2605
+ "type": {
2606
+ "type": "string",
2607
+ "enum": [
2608
+ "function"
2609
+ ]
2610
+ },
2611
+ "function": {
2612
+ "type": "object",
2613
+ "properties": {
2614
+ "name": {
2615
+ "type": "string",
2616
+ "minLength": 1
2617
+ },
2618
+ "description": {
2619
+ "type": "string"
2620
+ },
2621
+ "parameters": {
2622
+ "type": "object",
2623
+ "properties": {
2624
+ "type": {
2625
+ "type": "string",
2626
+ "enum": [
2627
+ "object"
2628
+ ]
2629
+ },
2630
+ "properties": {
2631
+ "type": "object",
2632
+ "additionalProperties": {
2633
+ "allOf": [
2634
+ {
2635
+ "type": "object",
2636
+ "additionalProperties": {}
2637
+ },
2638
+ {
2639
+ "type": "object",
2640
+ "properties": {
2641
+ "type": {
2642
+ "anyOf": [
2643
+ {
2644
+ "type": "string"
2645
+ },
2646
+ {
2647
+ "type": "array",
2648
+ "items": {
2649
+ "type": "string"
2650
+ }
2651
+ }
2652
+ ]
2653
+ },
2654
+ "description": {
2655
+ "type": "string"
2656
+ },
2657
+ "enum": {
2658
+ "type": "array",
2659
+ "items": {
2660
+ "type": "string"
2661
+ }
2662
+ },
2663
+ "required": {
2664
+ "type": "array",
2665
+ "items": {
2666
+ "type": "string"
2667
+ }
2668
+ },
2669
+ "additionalProperties": {
2670
+ "type": "boolean"
2671
+ }
2672
+ },
2673
+ "required": [
2674
+ "type"
2675
+ ]
2676
+ }
2677
+ ]
2678
+ }
2679
+ },
2680
+ "required": {
2681
+ "type": "array",
2682
+ "items": {
2683
+ "type": "string"
2684
+ }
2685
+ },
2686
+ "additionalProperties": {
2687
+ "type": "boolean"
2688
+ }
2689
+ },
2690
+ "required": [
2691
+ "type",
2692
+ "properties"
2693
+ ]
2694
+ }
2695
+ },
2696
+ "required": [
2697
+ "name",
2698
+ "description",
2699
+ "parameters"
2700
+ ]
2701
+ }
2702
+ },
2703
+ "required": [
2704
+ "type",
2705
+ "function"
2706
+ ]
2707
+ },
2708
+ "ChattyExecuteRequest": {
2709
+ "type": "object",
2710
+ "properties": {
2711
+ "function": {
2712
+ "type": "string",
2713
+ "minLength": 1
2714
+ },
2715
+ "name": {
2716
+ "type": "string",
2717
+ "minLength": 1
2718
+ },
2719
+ "arguments": {
2720
+ "type": "object",
2721
+ "additionalProperties": {}
2722
+ }
2723
+ }
2724
+ },
2725
+ "ChattyExecuteResponse": {
2726
+ "type": "object",
2727
+ "properties": {
2728
+ "success": {
2729
+ "type": "boolean"
2730
+ },
2731
+ "message": {
2732
+ "type": "string"
2733
+ },
2734
+ "error": {
2735
+ "type": "string"
2736
+ },
2737
+ "code": {
2738
+ "type": "string"
2739
+ },
2740
+ "data": {},
2741
+ "action": {}
2742
+ },
2743
+ "required": [
2744
+ "success"
2745
+ ]
2746
+ },
2747
+ "ChattyAiContextResponse": {
2748
+ "type": "object",
2749
+ "properties": {
2750
+ "instructions": {
2751
+ "type": "string"
2752
+ },
2753
+ "knowledgeBaseLoaded": {
2754
+ "type": "boolean"
2755
+ },
2756
+ "workflowStagesLoaded": {
2757
+ "type": "boolean"
2758
+ },
2759
+ "timestamp": {
2760
+ "type": "string"
2761
+ }
2762
+ },
2763
+ "required": [
2764
+ "instructions",
2765
+ "knowledgeBaseLoaded",
2766
+ "workflowStagesLoaded",
2767
+ "timestamp"
2768
+ ]
2769
+ },
2770
+ "RealtimeTokenRequest": {
2771
+ "type": "object",
2772
+ "properties": {
2773
+ "directWebRTC": {
2774
+ "type": "boolean"
2775
+ }
2776
+ }
2777
+ },
2778
+ "RealtimeTokenResponse": {
2779
+ "type": "object",
2780
+ "properties": {
2781
+ "sessionId": {
2782
+ "type": "string"
2783
+ },
2784
+ "model": {
2785
+ "type": "string"
2786
+ },
2787
+ "voice": {
2788
+ "type": "string"
2789
+ },
2790
+ "clientSecret": {
2791
+ "type": "string"
2792
+ },
2793
+ "fallback": {
2794
+ "type": "boolean"
2795
+ },
2796
+ "directWebRTC": {
2797
+ "type": "boolean"
2798
+ },
2799
+ "useWebRTC": {
2800
+ "type": "boolean"
2801
+ },
2802
+ "expiresInSeconds": {
2803
+ "type": "integer",
2804
+ "minimum": 0
2805
+ },
2806
+ "metadata": {
2807
+ "type": "object",
2808
+ "properties": {
2809
+ "organizationId": {
2810
+ "anyOf": [
2811
+ {
2812
+ "type": "string"
2813
+ },
2814
+ {
2815
+ "type": "number"
2816
+ }
2817
+ ]
2818
+ }
2819
+ },
2820
+ "required": [
2821
+ "organizationId"
2822
+ ]
2823
+ },
2824
+ "message": {
2825
+ "type": "string"
2826
+ }
2827
+ },
2828
+ "required": [
2829
+ "fallback"
2830
+ ]
2831
+ },
2832
+ "CsrfTokenResponse": {
2833
+ "type": "object",
2834
+ "properties": {
2835
+ "token": {
2836
+ "type": "string",
2837
+ "minLength": 1
2838
+ }
2839
+ },
2840
+ "required": [
2841
+ "token"
2842
+ ]
2843
+ },
2844
+ "RealtimeWebrtcRequest": {
2845
+ "type": "object",
2846
+ "properties": {
2847
+ "sdp": {
2848
+ "type": "string",
2849
+ "minLength": 1
2850
+ }
2851
+ },
2852
+ "required": [
2853
+ "sdp"
2854
+ ]
2601
2855
  }
2602
2856
  },
2603
2857
  "parameters": {}
@@ -5138,6 +5392,776 @@
5138
5392
  }
5139
5393
  }
5140
5394
  }
5395
+ },
5396
+ "/api/chatty-voice/tools": {
5397
+ "get": {
5398
+ "summary": "List the OpenAI-Realtime-compatible function tools the executor can run.",
5399
+ "description": "Returns the canonical Chatty Voice tool catalogue as a BARE ARRAY of `ChattyToolDefinition` envelopes (no wrapping object). Each entry is executable via POST /api/chatty-voice/tools/execute.",
5400
+ "tags": [
5401
+ "chatty"
5402
+ ],
5403
+ "parameters": [
5404
+ {
5405
+ "name": "X-Client-Version",
5406
+ "in": "header",
5407
+ "required": false,
5408
+ "schema": {
5409
+ "type": "string",
5410
+ "example": "1.0.0"
5411
+ },
5412
+ "description": "Semver of the calling app build. Drives the 426 / soft-upgrade handshake."
5413
+ }
5414
+ ],
5415
+ "responses": {
5416
+ "200": {
5417
+ "description": "Bare array of tool definitions.",
5418
+ "content": {
5419
+ "application/json": {
5420
+ "schema": {
5421
+ "type": "array",
5422
+ "items": {
5423
+ "type": "object",
5424
+ "properties": {
5425
+ "type": {
5426
+ "type": "string",
5427
+ "enum": [
5428
+ "function"
5429
+ ]
5430
+ },
5431
+ "function": {
5432
+ "type": "object",
5433
+ "properties": {
5434
+ "name": {
5435
+ "type": "string",
5436
+ "minLength": 1
5437
+ },
5438
+ "description": {
5439
+ "type": "string"
5440
+ },
5441
+ "parameters": {
5442
+ "type": "object",
5443
+ "properties": {
5444
+ "type": {
5445
+ "type": "string",
5446
+ "enum": [
5447
+ "object"
5448
+ ]
5449
+ },
5450
+ "properties": {
5451
+ "type": "object",
5452
+ "additionalProperties": {
5453
+ "allOf": [
5454
+ {
5455
+ "type": "object",
5456
+ "additionalProperties": {}
5457
+ },
5458
+ {
5459
+ "type": "object",
5460
+ "properties": {
5461
+ "type": {
5462
+ "anyOf": [
5463
+ {
5464
+ "type": "string"
5465
+ },
5466
+ {
5467
+ "type": "array",
5468
+ "items": {
5469
+ "type": "string"
5470
+ }
5471
+ }
5472
+ ]
5473
+ },
5474
+ "description": {
5475
+ "type": "string"
5476
+ },
5477
+ "enum": {
5478
+ "type": "array",
5479
+ "items": {
5480
+ "type": "string"
5481
+ }
5482
+ },
5483
+ "required": {
5484
+ "type": "array",
5485
+ "items": {
5486
+ "type": "string"
5487
+ }
5488
+ },
5489
+ "additionalProperties": {
5490
+ "type": "boolean"
5491
+ }
5492
+ },
5493
+ "required": [
5494
+ "type"
5495
+ ]
5496
+ }
5497
+ ]
5498
+ }
5499
+ },
5500
+ "required": {
5501
+ "type": "array",
5502
+ "items": {
5503
+ "type": "string"
5504
+ }
5505
+ },
5506
+ "additionalProperties": {
5507
+ "type": "boolean"
5508
+ }
5509
+ },
5510
+ "required": [
5511
+ "type",
5512
+ "properties"
5513
+ ]
5514
+ }
5515
+ },
5516
+ "required": [
5517
+ "name",
5518
+ "description",
5519
+ "parameters"
5520
+ ]
5521
+ }
5522
+ },
5523
+ "required": [
5524
+ "type",
5525
+ "function"
5526
+ ]
5527
+ }
5528
+ }
5529
+ }
5530
+ }
5531
+ },
5532
+ "401": {
5533
+ "description": "Unauthenticated.",
5534
+ "content": {
5535
+ "application/json": {
5536
+ "schema": {
5537
+ "$ref": "#/components/schemas/ErrorEnvelope"
5538
+ }
5539
+ }
5540
+ }
5541
+ },
5542
+ "403": {
5543
+ "description": "Caller lacks the chatty-voice entitlement.",
5544
+ "content": {
5545
+ "application/json": {
5546
+ "schema": {
5547
+ "$ref": "#/components/schemas/ErrorEnvelope"
5548
+ }
5549
+ }
5550
+ }
5551
+ },
5552
+ "426": {
5553
+ "description": "Client major below minClientVersion.",
5554
+ "content": {
5555
+ "application/json": {
5556
+ "schema": {
5557
+ "$ref": "#/components/schemas/UpgradeRequiredEnvelope"
5558
+ }
5559
+ }
5560
+ }
5561
+ }
5562
+ }
5563
+ }
5564
+ },
5565
+ "/api/chatty-voice/tools/execute": {
5566
+ "post": {
5567
+ "summary": "Execute a Chatty Voice tool by canonical `function` (or legacy `name`).",
5568
+ "description": "Body accepts either the canonical `function` field or the legacy `name` alias — at least one is required. The executor treats them as equivalent and dispatches to the same switch case in `tools.ts`. Tool arguments are passed through verbatim as an opaque JSON object.",
5569
+ "tags": [
5570
+ "chatty"
5571
+ ],
5572
+ "parameters": [
5573
+ {
5574
+ "name": "X-Client-Version",
5575
+ "in": "header",
5576
+ "required": false,
5577
+ "schema": {
5578
+ "type": "string",
5579
+ "example": "1.0.0"
5580
+ },
5581
+ "description": "Semver of the calling app build. Drives the 426 / soft-upgrade handshake."
5582
+ }
5583
+ ],
5584
+ "requestBody": {
5585
+ "content": {
5586
+ "application/json": {
5587
+ "schema": {
5588
+ "type": "object",
5589
+ "properties": {
5590
+ "function": {
5591
+ "type": "string",
5592
+ "minLength": 1
5593
+ },
5594
+ "name": {
5595
+ "type": "string",
5596
+ "minLength": 1
5597
+ },
5598
+ "arguments": {
5599
+ "type": "object",
5600
+ "additionalProperties": {}
5601
+ }
5602
+ }
5603
+ }
5604
+ }
5605
+ }
5606
+ },
5607
+ "responses": {
5608
+ "200": {
5609
+ "description": "Always returned when execution reaches the executor. `success: false` envelopes carry an `error` and (for permission denials) a `code` — including the missing/unknown function case.",
5610
+ "content": {
5611
+ "application/json": {
5612
+ "schema": {
5613
+ "type": "object",
5614
+ "properties": {
5615
+ "success": {
5616
+ "type": "boolean"
5617
+ },
5618
+ "message": {
5619
+ "type": "string"
5620
+ },
5621
+ "error": {
5622
+ "type": "string"
5623
+ },
5624
+ "code": {
5625
+ "type": "string"
5626
+ },
5627
+ "data": {},
5628
+ "action": {}
5629
+ },
5630
+ "required": [
5631
+ "success"
5632
+ ]
5633
+ }
5634
+ }
5635
+ }
5636
+ },
5637
+ "401": {
5638
+ "description": "Unauthenticated.",
5639
+ "content": {
5640
+ "application/json": {
5641
+ "schema": {
5642
+ "$ref": "#/components/schemas/ErrorEnvelope"
5643
+ }
5644
+ }
5645
+ }
5646
+ },
5647
+ "403": {
5648
+ "description": "Caller lacks the chatty-voice entitlement or a per-tool permission.",
5649
+ "content": {
5650
+ "application/json": {
5651
+ "schema": {
5652
+ "$ref": "#/components/schemas/ErrorEnvelope"
5653
+ }
5654
+ }
5655
+ }
5656
+ },
5657
+ "500": {
5658
+ "description": "Unhandled executor error. Body is `{ success: false, error }` (same envelope as 200).",
5659
+ "content": {
5660
+ "application/json": {
5661
+ "schema": {
5662
+ "type": "object",
5663
+ "properties": {
5664
+ "success": {
5665
+ "type": "boolean"
5666
+ },
5667
+ "message": {
5668
+ "type": "string"
5669
+ },
5670
+ "error": {
5671
+ "type": "string"
5672
+ },
5673
+ "code": {
5674
+ "type": "string"
5675
+ },
5676
+ "data": {},
5677
+ "action": {}
5678
+ },
5679
+ "required": [
5680
+ "success"
5681
+ ]
5682
+ }
5683
+ }
5684
+ }
5685
+ }
5686
+ }
5687
+ }
5688
+ },
5689
+ "/api/chatty-voice/ai-context": {
5690
+ "get": {
5691
+ "summary": "Fetch the Chatty Voice system prompt + load-status flags.",
5692
+ "tags": [
5693
+ "chatty"
5694
+ ],
5695
+ "parameters": [
5696
+ {
5697
+ "name": "X-Client-Version",
5698
+ "in": "header",
5699
+ "required": false,
5700
+ "schema": {
5701
+ "type": "string",
5702
+ "example": "1.0.0"
5703
+ },
5704
+ "description": "Semver of the calling app build. Drives the 426 / soft-upgrade handshake."
5705
+ }
5706
+ ],
5707
+ "responses": {
5708
+ "200": {
5709
+ "description": "System instructions + knowledge-base / workflow-stage load flags.",
5710
+ "content": {
5711
+ "application/json": {
5712
+ "schema": {
5713
+ "type": "object",
5714
+ "properties": {
5715
+ "instructions": {
5716
+ "type": "string"
5717
+ },
5718
+ "knowledgeBaseLoaded": {
5719
+ "type": "boolean"
5720
+ },
5721
+ "workflowStagesLoaded": {
5722
+ "type": "boolean"
5723
+ },
5724
+ "timestamp": {
5725
+ "type": "string"
5726
+ }
5727
+ },
5728
+ "required": [
5729
+ "instructions",
5730
+ "knowledgeBaseLoaded",
5731
+ "workflowStagesLoaded",
5732
+ "timestamp"
5733
+ ]
5734
+ }
5735
+ }
5736
+ }
5737
+ },
5738
+ "401": {
5739
+ "description": "Unauthenticated.",
5740
+ "content": {
5741
+ "application/json": {
5742
+ "schema": {
5743
+ "$ref": "#/components/schemas/ErrorEnvelope"
5744
+ }
5745
+ }
5746
+ }
5747
+ },
5748
+ "403": {
5749
+ "description": "Caller lacks the chatty-voice entitlement.",
5750
+ "content": {
5751
+ "application/json": {
5752
+ "schema": {
5753
+ "$ref": "#/components/schemas/ErrorEnvelope"
5754
+ }
5755
+ }
5756
+ }
5757
+ }
5758
+ }
5759
+ }
5760
+ },
5761
+ "/api/realtime-token": {
5762
+ "post": {
5763
+ "summary": "Mint an OpenAI Realtime ephemeral session token (single union object).",
5764
+ "description": "Body: `{ directWebRTC?: boolean }`. Response is a SINGLE union object — the directWebRTC, desktop server-proxied, and HTTP-fallback branches all share the same envelope. Only `fallback` is always present; every other field is optional and presence depends on the branch.",
5765
+ "tags": [
5766
+ "chatty"
5767
+ ],
5768
+ "parameters": [
5769
+ {
5770
+ "name": "X-Client-Version",
5771
+ "in": "header",
5772
+ "required": false,
5773
+ "schema": {
5774
+ "type": "string",
5775
+ "example": "1.0.0"
5776
+ },
5777
+ "description": "Semver of the calling app build. Drives the 426 / soft-upgrade handshake."
5778
+ }
5779
+ ],
5780
+ "requestBody": {
5781
+ "content": {
5782
+ "application/json": {
5783
+ "schema": {
5784
+ "type": "object",
5785
+ "properties": {
5786
+ "directWebRTC": {
5787
+ "type": "boolean"
5788
+ }
5789
+ }
5790
+ }
5791
+ }
5792
+ }
5793
+ },
5794
+ "responses": {
5795
+ "200": {
5796
+ "description": "Session minted (or fallback signalled). See union shape.",
5797
+ "content": {
5798
+ "application/json": {
5799
+ "schema": {
5800
+ "type": "object",
5801
+ "properties": {
5802
+ "sessionId": {
5803
+ "type": "string"
5804
+ },
5805
+ "model": {
5806
+ "type": "string"
5807
+ },
5808
+ "voice": {
5809
+ "type": "string"
5810
+ },
5811
+ "clientSecret": {
5812
+ "type": "string"
5813
+ },
5814
+ "fallback": {
5815
+ "type": "boolean"
5816
+ },
5817
+ "directWebRTC": {
5818
+ "type": "boolean"
5819
+ },
5820
+ "useWebRTC": {
5821
+ "type": "boolean"
5822
+ },
5823
+ "expiresInSeconds": {
5824
+ "type": "integer",
5825
+ "minimum": 0
5826
+ },
5827
+ "metadata": {
5828
+ "type": "object",
5829
+ "properties": {
5830
+ "organizationId": {
5831
+ "anyOf": [
5832
+ {
5833
+ "type": "string"
5834
+ },
5835
+ {
5836
+ "type": "number"
5837
+ }
5838
+ ]
5839
+ }
5840
+ },
5841
+ "required": [
5842
+ "organizationId"
5843
+ ]
5844
+ },
5845
+ "message": {
5846
+ "type": "string"
5847
+ }
5848
+ },
5849
+ "required": [
5850
+ "fallback"
5851
+ ]
5852
+ }
5853
+ }
5854
+ }
5855
+ },
5856
+ "401": {
5857
+ "description": "Unauthenticated.",
5858
+ "content": {
5859
+ "application/json": {
5860
+ "schema": {
5861
+ "$ref": "#/components/schemas/ErrorEnvelope"
5862
+ }
5863
+ }
5864
+ }
5865
+ },
5866
+ "403": {
5867
+ "description": "Caller lacks the chatty-voice entitlement.",
5868
+ "content": {
5869
+ "application/json": {
5870
+ "schema": {
5871
+ "$ref": "#/components/schemas/ErrorEnvelope"
5872
+ }
5873
+ }
5874
+ }
5875
+ },
5876
+ "405": {
5877
+ "description": "Method Not Allowed (POST only).",
5878
+ "content": {
5879
+ "application/json": {
5880
+ "schema": {
5881
+ "$ref": "#/components/schemas/ErrorEnvelope"
5882
+ }
5883
+ }
5884
+ }
5885
+ },
5886
+ "429": {
5887
+ "description": "Per-user rate limit on token mint.",
5888
+ "content": {
5889
+ "application/json": {
5890
+ "schema": {
5891
+ "$ref": "#/components/schemas/ErrorEnvelope"
5892
+ }
5893
+ }
5894
+ }
5895
+ },
5896
+ "500": {
5897
+ "description": "Mint failure — body still carries `fallback: true`.",
5898
+ "content": {
5899
+ "application/json": {
5900
+ "schema": {
5901
+ "type": "object",
5902
+ "properties": {
5903
+ "sessionId": {
5904
+ "type": "string"
5905
+ },
5906
+ "model": {
5907
+ "type": "string"
5908
+ },
5909
+ "voice": {
5910
+ "type": "string"
5911
+ },
5912
+ "clientSecret": {
5913
+ "type": "string"
5914
+ },
5915
+ "fallback": {
5916
+ "type": "boolean"
5917
+ },
5918
+ "directWebRTC": {
5919
+ "type": "boolean"
5920
+ },
5921
+ "useWebRTC": {
5922
+ "type": "boolean"
5923
+ },
5924
+ "expiresInSeconds": {
5925
+ "type": "integer",
5926
+ "minimum": 0
5927
+ },
5928
+ "metadata": {
5929
+ "type": "object",
5930
+ "properties": {
5931
+ "organizationId": {
5932
+ "anyOf": [
5933
+ {
5934
+ "type": "string"
5935
+ },
5936
+ {
5937
+ "type": "number"
5938
+ }
5939
+ ]
5940
+ }
5941
+ },
5942
+ "required": [
5943
+ "organizationId"
5944
+ ]
5945
+ },
5946
+ "message": {
5947
+ "type": "string"
5948
+ }
5949
+ },
5950
+ "required": [
5951
+ "fallback"
5952
+ ]
5953
+ }
5954
+ }
5955
+ }
5956
+ }
5957
+ }
5958
+ }
5959
+ },
5960
+ "/api/csrf-token": {
5961
+ "get": {
5962
+ "summary": "Mint a short-lived CSRF token for the WebRTC SDP exchange.",
5963
+ "description": "Returned token is required as `X-CSRF-Token` on POST /api/realtime/webrtc and is bound to the calling user for 5 minutes.",
5964
+ "tags": [
5965
+ "chatty"
5966
+ ],
5967
+ "parameters": [
5968
+ {
5969
+ "name": "X-Client-Version",
5970
+ "in": "header",
5971
+ "required": false,
5972
+ "schema": {
5973
+ "type": "string",
5974
+ "example": "1.0.0"
5975
+ },
5976
+ "description": "Semver of the calling app build. Drives the 426 / soft-upgrade handshake."
5977
+ }
5978
+ ],
5979
+ "responses": {
5980
+ "200": {
5981
+ "description": "Fresh CSRF token.",
5982
+ "content": {
5983
+ "application/json": {
5984
+ "schema": {
5985
+ "type": "object",
5986
+ "properties": {
5987
+ "token": {
5988
+ "type": "string",
5989
+ "minLength": 1
5990
+ }
5991
+ },
5992
+ "required": [
5993
+ "token"
5994
+ ]
5995
+ }
5996
+ }
5997
+ }
5998
+ },
5999
+ "401": {
6000
+ "description": "Unauthenticated.",
6001
+ "content": {
6002
+ "application/json": {
6003
+ "schema": {
6004
+ "$ref": "#/components/schemas/ErrorEnvelope"
6005
+ }
6006
+ }
6007
+ }
6008
+ },
6009
+ "403": {
6010
+ "description": "Caller lacks the chatty-voice entitlement.",
6011
+ "content": {
6012
+ "application/json": {
6013
+ "schema": {
6014
+ "$ref": "#/components/schemas/ErrorEnvelope"
6015
+ }
6016
+ }
6017
+ }
6018
+ }
6019
+ }
6020
+ }
6021
+ },
6022
+ "/api/realtime/webrtc": {
6023
+ "post": {
6024
+ "summary": "Server-proxied OpenAI Realtime SDP exchange (desktop branch).",
6025
+ "description": "Request body is JSON `{ sdp }`; the server mints a fresh OpenAI ephemeral client_secret, forwards the raw SDP to OpenAI's WebRTC endpoint, and returns the raw SDP answer as `application/sdp` text. CSRF-protected via `X-CSRF-Token` (see GET /api/csrf-token) and rate-limited to 3 req/min/IP.",
6026
+ "tags": [
6027
+ "chatty"
6028
+ ],
6029
+ "parameters": [
6030
+ {
6031
+ "name": "X-Client-Version",
6032
+ "in": "header",
6033
+ "required": false,
6034
+ "schema": {
6035
+ "type": "string",
6036
+ "example": "1.0.0"
6037
+ },
6038
+ "description": "Semver of the calling app build. Drives the 426 / soft-upgrade handshake."
6039
+ },
6040
+ {
6041
+ "name": "X-CSRF-Token",
6042
+ "in": "header",
6043
+ "required": true,
6044
+ "schema": {
6045
+ "type": "string"
6046
+ },
6047
+ "description": "CSRF token previously minted by GET /api/csrf-token."
6048
+ }
6049
+ ],
6050
+ "requestBody": {
6051
+ "content": {
6052
+ "application/json": {
6053
+ "schema": {
6054
+ "type": "object",
6055
+ "properties": {
6056
+ "sdp": {
6057
+ "type": "string",
6058
+ "minLength": 1
6059
+ }
6060
+ },
6061
+ "required": [
6062
+ "sdp"
6063
+ ]
6064
+ }
6065
+ }
6066
+ }
6067
+ },
6068
+ "responses": {
6069
+ "200": {
6070
+ "description": "Raw OpenAI SDP answer (text body, not JSON).",
6071
+ "content": {
6072
+ "application/sdp": {
6073
+ "schema": {
6074
+ "type": "string"
6075
+ }
6076
+ }
6077
+ }
6078
+ },
6079
+ "400": {
6080
+ "description": "Invalid SDP format.",
6081
+ "content": {
6082
+ "application/json": {
6083
+ "schema": {
6084
+ "$ref": "#/components/schemas/ErrorEnvelope"
6085
+ }
6086
+ }
6087
+ }
6088
+ },
6089
+ "401": {
6090
+ "description": "Unauthenticated.",
6091
+ "content": {
6092
+ "application/json": {
6093
+ "schema": {
6094
+ "$ref": "#/components/schemas/ErrorEnvelope"
6095
+ }
6096
+ }
6097
+ }
6098
+ },
6099
+ "403": {
6100
+ "description": "Caller lacks the chatty-voice entitlement, or CSRF token invalid.",
6101
+ "content": {
6102
+ "application/json": {
6103
+ "schema": {
6104
+ "$ref": "#/components/schemas/ErrorEnvelope"
6105
+ }
6106
+ }
6107
+ }
6108
+ },
6109
+ "429": {
6110
+ "description": "Rate limit (3 req/min/IP).",
6111
+ "content": {
6112
+ "application/json": {
6113
+ "schema": {
6114
+ "$ref": "#/components/schemas/ErrorEnvelope"
6115
+ }
6116
+ }
6117
+ }
6118
+ },
6119
+ "500": {
6120
+ "description": "SDP exchange failed locally.",
6121
+ "content": {
6122
+ "application/json": {
6123
+ "schema": {
6124
+ "$ref": "#/components/schemas/ErrorEnvelope"
6125
+ }
6126
+ }
6127
+ }
6128
+ },
6129
+ "502": {
6130
+ "description": "Local failure minting the OpenAI ephemeral client_secret required to authenticate the SDP exchange. Returned as a JSON envelope generated by this server: `{ error, status? }`.",
6131
+ "content": {
6132
+ "application/json": {
6133
+ "schema": {
6134
+ "type": "object",
6135
+ "properties": {
6136
+ "error": {
6137
+ "type": "string"
6138
+ },
6139
+ "status": {
6140
+ "type": "integer"
6141
+ }
6142
+ },
6143
+ "required": [
6144
+ "error"
6145
+ ]
6146
+ }
6147
+ }
6148
+ }
6149
+ },
6150
+ "default": {
6151
+ "description": "Upstream OpenAI SDP exchange error. Pass-through: this endpoint forwards OpenAI's HTTP status verbatim (typically 4xx/5xx) and the body is OpenAI's raw error payload — NOT a JSON envelope generated by this server. Content-Type and exact shape are determined by OpenAI; clients MUST treat any non-200 response on this endpoint as opaque error text unless they explicitly detect the 502 JSON envelope above.",
6152
+ "content": {
6153
+ "application/json": {
6154
+ "schema": {}
6155
+ },
6156
+ "text/plain": {
6157
+ "schema": {
6158
+ "type": "string"
6159
+ }
6160
+ }
6161
+ }
6162
+ }
6163
+ }
6164
+ }
5141
6165
  }
5142
6166
  },
5143
6167
  "webhooks": {}