@serviceai/api-spec 1.1.22 → 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.
- package/openapi.json +1026 -2
- package/openapi.yaml +630 -2
- package/package.json +1 -1
- package/types.d.ts +616 -1
package/openapi.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
openapi: 3.1.0
|
|
2
2
|
info:
|
|
3
3
|
title: ServiceAi API
|
|
4
|
-
version: 1.1.
|
|
4
|
+
version: 1.1.24
|
|
5
5
|
description: >-
|
|
6
6
|
Source-of-truth API contract for ServiceAi. Generated from `shared/schema.ts` Zod schemas by
|
|
7
7
|
`scripts/build-api-spec.ts`. Versioning policy: see `docs/api-versioning.md`. The hand-written docs/ios-contract.md
|
|
@@ -78,7 +78,7 @@ components:
|
|
|
78
78
|
properties:
|
|
79
79
|
apiVersion:
|
|
80
80
|
type: string
|
|
81
|
-
example: 1.1.
|
|
81
|
+
example: 1.1.24
|
|
82
82
|
minClientVersion:
|
|
83
83
|
type: string
|
|
84
84
|
example: 1.0.0
|
|
@@ -1693,6 +1693,169 @@ components:
|
|
|
1693
1693
|
description: >-
|
|
1694
1694
|
Persisted floor-plan PNG render-frame. `mirrorX` is derived from `scans.client_mirror_applied` (negate when
|
|
1695
1695
|
false). Null sentinel: ANY required column NULL → `null` is emitted instead of a partial frame.
|
|
1696
|
+
ChattyToolDefinition:
|
|
1697
|
+
type: object
|
|
1698
|
+
properties:
|
|
1699
|
+
type:
|
|
1700
|
+
type: string
|
|
1701
|
+
enum:
|
|
1702
|
+
- function
|
|
1703
|
+
function:
|
|
1704
|
+
type: object
|
|
1705
|
+
properties:
|
|
1706
|
+
name:
|
|
1707
|
+
type: string
|
|
1708
|
+
minLength: 1
|
|
1709
|
+
description:
|
|
1710
|
+
type: string
|
|
1711
|
+
parameters:
|
|
1712
|
+
type: object
|
|
1713
|
+
properties:
|
|
1714
|
+
type:
|
|
1715
|
+
type: string
|
|
1716
|
+
enum:
|
|
1717
|
+
- object
|
|
1718
|
+
properties:
|
|
1719
|
+
type: object
|
|
1720
|
+
additionalProperties:
|
|
1721
|
+
allOf:
|
|
1722
|
+
- type: object
|
|
1723
|
+
additionalProperties: {}
|
|
1724
|
+
- type: object
|
|
1725
|
+
properties:
|
|
1726
|
+
type:
|
|
1727
|
+
anyOf:
|
|
1728
|
+
- type: string
|
|
1729
|
+
- type: array
|
|
1730
|
+
items:
|
|
1731
|
+
type: string
|
|
1732
|
+
description:
|
|
1733
|
+
type: string
|
|
1734
|
+
enum:
|
|
1735
|
+
type: array
|
|
1736
|
+
items:
|
|
1737
|
+
type: string
|
|
1738
|
+
required:
|
|
1739
|
+
type: array
|
|
1740
|
+
items:
|
|
1741
|
+
type: string
|
|
1742
|
+
additionalProperties:
|
|
1743
|
+
type: boolean
|
|
1744
|
+
required:
|
|
1745
|
+
- type
|
|
1746
|
+
required:
|
|
1747
|
+
type: array
|
|
1748
|
+
items:
|
|
1749
|
+
type: string
|
|
1750
|
+
additionalProperties:
|
|
1751
|
+
type: boolean
|
|
1752
|
+
required:
|
|
1753
|
+
- type
|
|
1754
|
+
- properties
|
|
1755
|
+
required:
|
|
1756
|
+
- name
|
|
1757
|
+
- description
|
|
1758
|
+
- parameters
|
|
1759
|
+
required:
|
|
1760
|
+
- type
|
|
1761
|
+
- function
|
|
1762
|
+
ChattyExecuteRequest:
|
|
1763
|
+
type: object
|
|
1764
|
+
properties:
|
|
1765
|
+
function:
|
|
1766
|
+
type: string
|
|
1767
|
+
minLength: 1
|
|
1768
|
+
name:
|
|
1769
|
+
type: string
|
|
1770
|
+
minLength: 1
|
|
1771
|
+
arguments:
|
|
1772
|
+
type: object
|
|
1773
|
+
additionalProperties: {}
|
|
1774
|
+
ChattyExecuteResponse:
|
|
1775
|
+
type: object
|
|
1776
|
+
properties:
|
|
1777
|
+
success:
|
|
1778
|
+
type: boolean
|
|
1779
|
+
message:
|
|
1780
|
+
type: string
|
|
1781
|
+
error:
|
|
1782
|
+
type: string
|
|
1783
|
+
code:
|
|
1784
|
+
type: string
|
|
1785
|
+
data: {}
|
|
1786
|
+
action: {}
|
|
1787
|
+
required:
|
|
1788
|
+
- success
|
|
1789
|
+
ChattyAiContextResponse:
|
|
1790
|
+
type: object
|
|
1791
|
+
properties:
|
|
1792
|
+
instructions:
|
|
1793
|
+
type: string
|
|
1794
|
+
knowledgeBaseLoaded:
|
|
1795
|
+
type: boolean
|
|
1796
|
+
workflowStagesLoaded:
|
|
1797
|
+
type: boolean
|
|
1798
|
+
timestamp:
|
|
1799
|
+
type: string
|
|
1800
|
+
required:
|
|
1801
|
+
- instructions
|
|
1802
|
+
- knowledgeBaseLoaded
|
|
1803
|
+
- workflowStagesLoaded
|
|
1804
|
+
- timestamp
|
|
1805
|
+
RealtimeTokenRequest:
|
|
1806
|
+
type: object
|
|
1807
|
+
properties:
|
|
1808
|
+
directWebRTC:
|
|
1809
|
+
type: boolean
|
|
1810
|
+
RealtimeTokenResponse:
|
|
1811
|
+
type: object
|
|
1812
|
+
properties:
|
|
1813
|
+
sessionId:
|
|
1814
|
+
type: string
|
|
1815
|
+
model:
|
|
1816
|
+
type: string
|
|
1817
|
+
voice:
|
|
1818
|
+
type: string
|
|
1819
|
+
clientSecret:
|
|
1820
|
+
type: string
|
|
1821
|
+
fallback:
|
|
1822
|
+
type: boolean
|
|
1823
|
+
directWebRTC:
|
|
1824
|
+
type: boolean
|
|
1825
|
+
useWebRTC:
|
|
1826
|
+
type: boolean
|
|
1827
|
+
expiresInSeconds:
|
|
1828
|
+
type: integer
|
|
1829
|
+
minimum: 0
|
|
1830
|
+
metadata:
|
|
1831
|
+
type: object
|
|
1832
|
+
properties:
|
|
1833
|
+
organizationId:
|
|
1834
|
+
anyOf:
|
|
1835
|
+
- type: string
|
|
1836
|
+
- type: number
|
|
1837
|
+
required:
|
|
1838
|
+
- organizationId
|
|
1839
|
+
message:
|
|
1840
|
+
type: string
|
|
1841
|
+
required:
|
|
1842
|
+
- fallback
|
|
1843
|
+
CsrfTokenResponse:
|
|
1844
|
+
type: object
|
|
1845
|
+
properties:
|
|
1846
|
+
token:
|
|
1847
|
+
type: string
|
|
1848
|
+
minLength: 1
|
|
1849
|
+
required:
|
|
1850
|
+
- token
|
|
1851
|
+
RealtimeWebrtcRequest:
|
|
1852
|
+
type: object
|
|
1853
|
+
properties:
|
|
1854
|
+
sdp:
|
|
1855
|
+
type: string
|
|
1856
|
+
minLength: 1
|
|
1857
|
+
required:
|
|
1858
|
+
- sdp
|
|
1696
1859
|
parameters: {}
|
|
1697
1860
|
paths:
|
|
1698
1861
|
/api/version:
|
|
@@ -3243,4 +3406,469 @@ paths:
|
|
|
3243
3406
|
application/json:
|
|
3244
3407
|
schema:
|
|
3245
3408
|
$ref: '#/components/schemas/ErrorEnvelope'
|
|
3409
|
+
/api/chatty-voice/tools:
|
|
3410
|
+
get:
|
|
3411
|
+
summary: List the OpenAI-Realtime-compatible function tools the executor can run.
|
|
3412
|
+
description: >-
|
|
3413
|
+
Returns the canonical Chatty Voice tool catalogue as a BARE ARRAY of `ChattyToolDefinition` envelopes (no
|
|
3414
|
+
wrapping object). Each entry is executable via POST /api/chatty-voice/tools/execute.
|
|
3415
|
+
tags:
|
|
3416
|
+
- chatty
|
|
3417
|
+
parameters:
|
|
3418
|
+
- *ref_2
|
|
3419
|
+
responses:
|
|
3420
|
+
'200':
|
|
3421
|
+
description: Bare array of tool definitions.
|
|
3422
|
+
content:
|
|
3423
|
+
application/json:
|
|
3424
|
+
schema:
|
|
3425
|
+
type: array
|
|
3426
|
+
items:
|
|
3427
|
+
type: object
|
|
3428
|
+
properties:
|
|
3429
|
+
type:
|
|
3430
|
+
type: string
|
|
3431
|
+
enum:
|
|
3432
|
+
- function
|
|
3433
|
+
function:
|
|
3434
|
+
type: object
|
|
3435
|
+
properties:
|
|
3436
|
+
name:
|
|
3437
|
+
type: string
|
|
3438
|
+
minLength: 1
|
|
3439
|
+
description:
|
|
3440
|
+
type: string
|
|
3441
|
+
parameters:
|
|
3442
|
+
type: object
|
|
3443
|
+
properties:
|
|
3444
|
+
type:
|
|
3445
|
+
type: string
|
|
3446
|
+
enum:
|
|
3447
|
+
- object
|
|
3448
|
+
properties:
|
|
3449
|
+
type: object
|
|
3450
|
+
additionalProperties:
|
|
3451
|
+
allOf:
|
|
3452
|
+
- type: object
|
|
3453
|
+
additionalProperties: {}
|
|
3454
|
+
- type: object
|
|
3455
|
+
properties:
|
|
3456
|
+
type:
|
|
3457
|
+
anyOf:
|
|
3458
|
+
- type: string
|
|
3459
|
+
- type: array
|
|
3460
|
+
items:
|
|
3461
|
+
type: string
|
|
3462
|
+
description:
|
|
3463
|
+
type: string
|
|
3464
|
+
enum:
|
|
3465
|
+
type: array
|
|
3466
|
+
items:
|
|
3467
|
+
type: string
|
|
3468
|
+
required:
|
|
3469
|
+
type: array
|
|
3470
|
+
items:
|
|
3471
|
+
type: string
|
|
3472
|
+
additionalProperties:
|
|
3473
|
+
type: boolean
|
|
3474
|
+
required:
|
|
3475
|
+
- type
|
|
3476
|
+
required:
|
|
3477
|
+
type: array
|
|
3478
|
+
items:
|
|
3479
|
+
type: string
|
|
3480
|
+
additionalProperties:
|
|
3481
|
+
type: boolean
|
|
3482
|
+
required:
|
|
3483
|
+
- type
|
|
3484
|
+
- properties
|
|
3485
|
+
required:
|
|
3486
|
+
- name
|
|
3487
|
+
- description
|
|
3488
|
+
- parameters
|
|
3489
|
+
required:
|
|
3490
|
+
- type
|
|
3491
|
+
- function
|
|
3492
|
+
'401':
|
|
3493
|
+
description: Unauthenticated.
|
|
3494
|
+
content:
|
|
3495
|
+
application/json:
|
|
3496
|
+
schema:
|
|
3497
|
+
$ref: '#/components/schemas/ErrorEnvelope'
|
|
3498
|
+
'403':
|
|
3499
|
+
description: Caller lacks the chatty-voice entitlement.
|
|
3500
|
+
content:
|
|
3501
|
+
application/json:
|
|
3502
|
+
schema:
|
|
3503
|
+
$ref: '#/components/schemas/ErrorEnvelope'
|
|
3504
|
+
'426':
|
|
3505
|
+
description: Client major below minClientVersion.
|
|
3506
|
+
content:
|
|
3507
|
+
application/json:
|
|
3508
|
+
schema:
|
|
3509
|
+
$ref: '#/components/schemas/UpgradeRequiredEnvelope'
|
|
3510
|
+
/api/chatty-voice/tools/execute:
|
|
3511
|
+
post:
|
|
3512
|
+
summary: Execute a Chatty Voice tool by canonical `function` (or legacy `name`).
|
|
3513
|
+
description: >-
|
|
3514
|
+
Body accepts either the canonical `function` field or the legacy `name` alias — at least one is required. The
|
|
3515
|
+
executor treats them as equivalent and dispatches to the same switch case in `tools.ts`. Tool arguments are
|
|
3516
|
+
passed through verbatim as an opaque JSON object.
|
|
3517
|
+
tags:
|
|
3518
|
+
- chatty
|
|
3519
|
+
parameters:
|
|
3520
|
+
- *ref_2
|
|
3521
|
+
requestBody:
|
|
3522
|
+
content:
|
|
3523
|
+
application/json:
|
|
3524
|
+
schema:
|
|
3525
|
+
type: object
|
|
3526
|
+
properties:
|
|
3527
|
+
function:
|
|
3528
|
+
type: string
|
|
3529
|
+
minLength: 1
|
|
3530
|
+
name:
|
|
3531
|
+
type: string
|
|
3532
|
+
minLength: 1
|
|
3533
|
+
arguments:
|
|
3534
|
+
type: object
|
|
3535
|
+
additionalProperties: {}
|
|
3536
|
+
responses:
|
|
3537
|
+
'200':
|
|
3538
|
+
description: >-
|
|
3539
|
+
Always returned when execution reaches the executor. `success: false` envelopes carry an `error` and (for
|
|
3540
|
+
permission denials) a `code` — including the missing/unknown function case.
|
|
3541
|
+
content:
|
|
3542
|
+
application/json:
|
|
3543
|
+
schema:
|
|
3544
|
+
type: object
|
|
3545
|
+
properties:
|
|
3546
|
+
success:
|
|
3547
|
+
type: boolean
|
|
3548
|
+
message:
|
|
3549
|
+
type: string
|
|
3550
|
+
error:
|
|
3551
|
+
type: string
|
|
3552
|
+
code:
|
|
3553
|
+
type: string
|
|
3554
|
+
data: {}
|
|
3555
|
+
action: {}
|
|
3556
|
+
required:
|
|
3557
|
+
- success
|
|
3558
|
+
'401':
|
|
3559
|
+
description: Unauthenticated.
|
|
3560
|
+
content:
|
|
3561
|
+
application/json:
|
|
3562
|
+
schema:
|
|
3563
|
+
$ref: '#/components/schemas/ErrorEnvelope'
|
|
3564
|
+
'403':
|
|
3565
|
+
description: Caller lacks the chatty-voice entitlement or a per-tool permission.
|
|
3566
|
+
content:
|
|
3567
|
+
application/json:
|
|
3568
|
+
schema:
|
|
3569
|
+
$ref: '#/components/schemas/ErrorEnvelope'
|
|
3570
|
+
'500':
|
|
3571
|
+
description: 'Unhandled executor error. Body is `{ success: false, error }` (same envelope as 200).'
|
|
3572
|
+
content:
|
|
3573
|
+
application/json:
|
|
3574
|
+
schema:
|
|
3575
|
+
type: object
|
|
3576
|
+
properties:
|
|
3577
|
+
success:
|
|
3578
|
+
type: boolean
|
|
3579
|
+
message:
|
|
3580
|
+
type: string
|
|
3581
|
+
error:
|
|
3582
|
+
type: string
|
|
3583
|
+
code:
|
|
3584
|
+
type: string
|
|
3585
|
+
data: {}
|
|
3586
|
+
action: {}
|
|
3587
|
+
required:
|
|
3588
|
+
- success
|
|
3589
|
+
/api/chatty-voice/ai-context:
|
|
3590
|
+
get:
|
|
3591
|
+
summary: Fetch the Chatty Voice system prompt + load-status flags.
|
|
3592
|
+
tags:
|
|
3593
|
+
- chatty
|
|
3594
|
+
parameters:
|
|
3595
|
+
- *ref_2
|
|
3596
|
+
responses:
|
|
3597
|
+
'200':
|
|
3598
|
+
description: System instructions + knowledge-base / workflow-stage load flags.
|
|
3599
|
+
content:
|
|
3600
|
+
application/json:
|
|
3601
|
+
schema:
|
|
3602
|
+
type: object
|
|
3603
|
+
properties:
|
|
3604
|
+
instructions:
|
|
3605
|
+
type: string
|
|
3606
|
+
knowledgeBaseLoaded:
|
|
3607
|
+
type: boolean
|
|
3608
|
+
workflowStagesLoaded:
|
|
3609
|
+
type: boolean
|
|
3610
|
+
timestamp:
|
|
3611
|
+
type: string
|
|
3612
|
+
required:
|
|
3613
|
+
- instructions
|
|
3614
|
+
- knowledgeBaseLoaded
|
|
3615
|
+
- workflowStagesLoaded
|
|
3616
|
+
- timestamp
|
|
3617
|
+
'401':
|
|
3618
|
+
description: Unauthenticated.
|
|
3619
|
+
content:
|
|
3620
|
+
application/json:
|
|
3621
|
+
schema:
|
|
3622
|
+
$ref: '#/components/schemas/ErrorEnvelope'
|
|
3623
|
+
'403':
|
|
3624
|
+
description: Caller lacks the chatty-voice entitlement.
|
|
3625
|
+
content:
|
|
3626
|
+
application/json:
|
|
3627
|
+
schema:
|
|
3628
|
+
$ref: '#/components/schemas/ErrorEnvelope'
|
|
3629
|
+
/api/realtime-token:
|
|
3630
|
+
post:
|
|
3631
|
+
summary: Mint an OpenAI Realtime ephemeral session token (single union object).
|
|
3632
|
+
description: >-
|
|
3633
|
+
Body: `{ directWebRTC?: boolean }`. Response is a SINGLE union object — the directWebRTC, desktop
|
|
3634
|
+
server-proxied, and HTTP-fallback branches all share the same envelope. Only `fallback` is always present; every
|
|
3635
|
+
other field is optional and presence depends on the branch.
|
|
3636
|
+
tags:
|
|
3637
|
+
- chatty
|
|
3638
|
+
parameters:
|
|
3639
|
+
- *ref_2
|
|
3640
|
+
requestBody:
|
|
3641
|
+
content:
|
|
3642
|
+
application/json:
|
|
3643
|
+
schema:
|
|
3644
|
+
type: object
|
|
3645
|
+
properties:
|
|
3646
|
+
directWebRTC:
|
|
3647
|
+
type: boolean
|
|
3648
|
+
responses:
|
|
3649
|
+
'200':
|
|
3650
|
+
description: Session minted (or fallback signalled). See union shape.
|
|
3651
|
+
content:
|
|
3652
|
+
application/json:
|
|
3653
|
+
schema:
|
|
3654
|
+
type: object
|
|
3655
|
+
properties:
|
|
3656
|
+
sessionId:
|
|
3657
|
+
type: string
|
|
3658
|
+
model:
|
|
3659
|
+
type: string
|
|
3660
|
+
voice:
|
|
3661
|
+
type: string
|
|
3662
|
+
clientSecret:
|
|
3663
|
+
type: string
|
|
3664
|
+
fallback:
|
|
3665
|
+
type: boolean
|
|
3666
|
+
directWebRTC:
|
|
3667
|
+
type: boolean
|
|
3668
|
+
useWebRTC:
|
|
3669
|
+
type: boolean
|
|
3670
|
+
expiresInSeconds:
|
|
3671
|
+
type: integer
|
|
3672
|
+
minimum: 0
|
|
3673
|
+
metadata:
|
|
3674
|
+
type: object
|
|
3675
|
+
properties:
|
|
3676
|
+
organizationId:
|
|
3677
|
+
anyOf:
|
|
3678
|
+
- type: string
|
|
3679
|
+
- type: number
|
|
3680
|
+
required:
|
|
3681
|
+
- organizationId
|
|
3682
|
+
message:
|
|
3683
|
+
type: string
|
|
3684
|
+
required:
|
|
3685
|
+
- fallback
|
|
3686
|
+
'401':
|
|
3687
|
+
description: Unauthenticated.
|
|
3688
|
+
content:
|
|
3689
|
+
application/json:
|
|
3690
|
+
schema:
|
|
3691
|
+
$ref: '#/components/schemas/ErrorEnvelope'
|
|
3692
|
+
'403':
|
|
3693
|
+
description: Caller lacks the chatty-voice entitlement.
|
|
3694
|
+
content:
|
|
3695
|
+
application/json:
|
|
3696
|
+
schema:
|
|
3697
|
+
$ref: '#/components/schemas/ErrorEnvelope'
|
|
3698
|
+
'405':
|
|
3699
|
+
description: Method Not Allowed (POST only).
|
|
3700
|
+
content:
|
|
3701
|
+
application/json:
|
|
3702
|
+
schema:
|
|
3703
|
+
$ref: '#/components/schemas/ErrorEnvelope'
|
|
3704
|
+
'429':
|
|
3705
|
+
description: Per-user rate limit on token mint.
|
|
3706
|
+
content:
|
|
3707
|
+
application/json:
|
|
3708
|
+
schema:
|
|
3709
|
+
$ref: '#/components/schemas/ErrorEnvelope'
|
|
3710
|
+
'500':
|
|
3711
|
+
description: 'Mint failure — body still carries `fallback: true`.'
|
|
3712
|
+
content:
|
|
3713
|
+
application/json:
|
|
3714
|
+
schema:
|
|
3715
|
+
type: object
|
|
3716
|
+
properties:
|
|
3717
|
+
sessionId:
|
|
3718
|
+
type: string
|
|
3719
|
+
model:
|
|
3720
|
+
type: string
|
|
3721
|
+
voice:
|
|
3722
|
+
type: string
|
|
3723
|
+
clientSecret:
|
|
3724
|
+
type: string
|
|
3725
|
+
fallback:
|
|
3726
|
+
type: boolean
|
|
3727
|
+
directWebRTC:
|
|
3728
|
+
type: boolean
|
|
3729
|
+
useWebRTC:
|
|
3730
|
+
type: boolean
|
|
3731
|
+
expiresInSeconds:
|
|
3732
|
+
type: integer
|
|
3733
|
+
minimum: 0
|
|
3734
|
+
metadata:
|
|
3735
|
+
type: object
|
|
3736
|
+
properties:
|
|
3737
|
+
organizationId:
|
|
3738
|
+
anyOf:
|
|
3739
|
+
- type: string
|
|
3740
|
+
- type: number
|
|
3741
|
+
required:
|
|
3742
|
+
- organizationId
|
|
3743
|
+
message:
|
|
3744
|
+
type: string
|
|
3745
|
+
required:
|
|
3746
|
+
- fallback
|
|
3747
|
+
/api/csrf-token:
|
|
3748
|
+
get:
|
|
3749
|
+
summary: Mint a short-lived CSRF token for the WebRTC SDP exchange.
|
|
3750
|
+
description: >-
|
|
3751
|
+
Returned token is required as `X-CSRF-Token` on POST /api/realtime/webrtc and is bound to the calling user for 5
|
|
3752
|
+
minutes.
|
|
3753
|
+
tags:
|
|
3754
|
+
- chatty
|
|
3755
|
+
parameters:
|
|
3756
|
+
- *ref_2
|
|
3757
|
+
responses:
|
|
3758
|
+
'200':
|
|
3759
|
+
description: Fresh CSRF token.
|
|
3760
|
+
content:
|
|
3761
|
+
application/json:
|
|
3762
|
+
schema:
|
|
3763
|
+
type: object
|
|
3764
|
+
properties:
|
|
3765
|
+
token:
|
|
3766
|
+
type: string
|
|
3767
|
+
minLength: 1
|
|
3768
|
+
required:
|
|
3769
|
+
- token
|
|
3770
|
+
'401':
|
|
3771
|
+
description: Unauthenticated.
|
|
3772
|
+
content:
|
|
3773
|
+
application/json:
|
|
3774
|
+
schema:
|
|
3775
|
+
$ref: '#/components/schemas/ErrorEnvelope'
|
|
3776
|
+
'403':
|
|
3777
|
+
description: Caller lacks the chatty-voice entitlement.
|
|
3778
|
+
content:
|
|
3779
|
+
application/json:
|
|
3780
|
+
schema:
|
|
3781
|
+
$ref: '#/components/schemas/ErrorEnvelope'
|
|
3782
|
+
/api/realtime/webrtc:
|
|
3783
|
+
post:
|
|
3784
|
+
summary: Server-proxied OpenAI Realtime SDP exchange (desktop branch).
|
|
3785
|
+
description: >-
|
|
3786
|
+
Request body is JSON `{ sdp }`; the server mints a fresh OpenAI ephemeral client_secret, forwards the raw SDP to
|
|
3787
|
+
OpenAI's WebRTC endpoint, and returns the raw SDP answer as `application/sdp` text. CSRF-protected via
|
|
3788
|
+
`X-CSRF-Token` (see GET /api/csrf-token) and rate-limited to 3 req/min/IP.
|
|
3789
|
+
tags:
|
|
3790
|
+
- chatty
|
|
3791
|
+
parameters:
|
|
3792
|
+
- *ref_2
|
|
3793
|
+
- name: X-CSRF-Token
|
|
3794
|
+
in: header
|
|
3795
|
+
required: true
|
|
3796
|
+
schema:
|
|
3797
|
+
type: string
|
|
3798
|
+
description: CSRF token previously minted by GET /api/csrf-token.
|
|
3799
|
+
requestBody:
|
|
3800
|
+
content:
|
|
3801
|
+
application/json:
|
|
3802
|
+
schema:
|
|
3803
|
+
type: object
|
|
3804
|
+
properties:
|
|
3805
|
+
sdp:
|
|
3806
|
+
type: string
|
|
3807
|
+
minLength: 1
|
|
3808
|
+
required:
|
|
3809
|
+
- sdp
|
|
3810
|
+
responses:
|
|
3811
|
+
'200':
|
|
3812
|
+
description: Raw OpenAI SDP answer (text body, not JSON).
|
|
3813
|
+
content:
|
|
3814
|
+
application/sdp:
|
|
3815
|
+
schema:
|
|
3816
|
+
type: string
|
|
3817
|
+
'400':
|
|
3818
|
+
description: Invalid SDP format.
|
|
3819
|
+
content:
|
|
3820
|
+
application/json:
|
|
3821
|
+
schema:
|
|
3822
|
+
$ref: '#/components/schemas/ErrorEnvelope'
|
|
3823
|
+
'401':
|
|
3824
|
+
description: Unauthenticated.
|
|
3825
|
+
content:
|
|
3826
|
+
application/json:
|
|
3827
|
+
schema:
|
|
3828
|
+
$ref: '#/components/schemas/ErrorEnvelope'
|
|
3829
|
+
'403':
|
|
3830
|
+
description: Caller lacks the chatty-voice entitlement, or CSRF token invalid.
|
|
3831
|
+
content:
|
|
3832
|
+
application/json:
|
|
3833
|
+
schema:
|
|
3834
|
+
$ref: '#/components/schemas/ErrorEnvelope'
|
|
3835
|
+
'429':
|
|
3836
|
+
description: Rate limit (3 req/min/IP).
|
|
3837
|
+
content:
|
|
3838
|
+
application/json:
|
|
3839
|
+
schema:
|
|
3840
|
+
$ref: '#/components/schemas/ErrorEnvelope'
|
|
3841
|
+
'500':
|
|
3842
|
+
description: SDP exchange failed locally.
|
|
3843
|
+
content:
|
|
3844
|
+
application/json:
|
|
3845
|
+
schema:
|
|
3846
|
+
$ref: '#/components/schemas/ErrorEnvelope'
|
|
3847
|
+
'502':
|
|
3848
|
+
description: >-
|
|
3849
|
+
Local failure minting the OpenAI ephemeral client_secret required to authenticate the SDP exchange. Returned
|
|
3850
|
+
as a JSON envelope generated by this server: `{ error, status? }`.
|
|
3851
|
+
content:
|
|
3852
|
+
application/json:
|
|
3853
|
+
schema:
|
|
3854
|
+
type: object
|
|
3855
|
+
properties:
|
|
3856
|
+
error:
|
|
3857
|
+
type: string
|
|
3858
|
+
status:
|
|
3859
|
+
type: integer
|
|
3860
|
+
required:
|
|
3861
|
+
- error
|
|
3862
|
+
default:
|
|
3863
|
+
description: >-
|
|
3864
|
+
Upstream OpenAI SDP exchange error. Pass-through: this endpoint forwards OpenAI's HTTP status verbatim
|
|
3865
|
+
(typically 4xx/5xx) and the body is OpenAI's raw error payload — NOT a JSON envelope generated by this
|
|
3866
|
+
server. Content-Type and exact shape are determined by OpenAI; clients MUST treat any non-200 response on
|
|
3867
|
+
this endpoint as opaque error text unless they explicitly detect the 502 JSON envelope above.
|
|
3868
|
+
content:
|
|
3869
|
+
application/json:
|
|
3870
|
+
schema: {}
|
|
3871
|
+
text/plain:
|
|
3872
|
+
schema:
|
|
3873
|
+
type: string
|
|
3246
3874
|
webhooks: {}
|