@serviceai/api-spec 1.1.22 → 1.1.24

package/types.d.ts

@@ -1278,6 +1278,552 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/chatty-voice/tools": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List the OpenAI-Realtime-compatible function tools the executor can run.
+         * @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.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: {
+                    /** @description Semver of the calling app build. Drives the 426 / soft-upgrade handshake. */
+                    "X-Client-Version"?: string;
+                };
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Bare array of tool definitions. */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @enum {string} */
+                            type: "function";
+                            function: {
+                                name: string;
+                                description: string;
+                                parameters: {
+                                    /** @enum {string} */
+                                    type: "object";
+                                    properties: {
+                                        [key: string]: {
+                                            [key: string]: unknown;
+                                        } & {
+                                            type: string | string[];
+                                            description?: string;
+                                            enum?: string[];
+                                            required?: string[];
+                                            additionalProperties?: boolean;
+                                        };
+                                    };
+                                    required?: string[];
+                                    additionalProperties?: boolean;
+                                };
+                            };
+                        }[];
+                    };
+                };
+                /** @description Unauthenticated. */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Caller lacks the chatty-voice entitlement. */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Client major below minClientVersion. */
+                426: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["UpgradeRequiredEnvelope"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/chatty-voice/tools/execute": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Execute a Chatty Voice tool by canonical `function` (or legacy `name`).
+         * @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.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: {
+                    /** @description Semver of the calling app build. Drives the 426 / soft-upgrade handshake. */
+                    "X-Client-Version"?: string;
+                };
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": {
+                        function?: string;
+                        name?: string;
+                        arguments?: {
+                            [key: string]: unknown;
+                        };
+                    };
+                };
+            };
+            responses: {
+                /** @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. */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            success: boolean;
+                            message?: string;
+                            error?: string;
+                            code?: string;
+                            data?: unknown;
+                            action?: unknown;
+                        };
+                    };
+                };
+                /** @description Unauthenticated. */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Caller lacks the chatty-voice entitlement or a per-tool permission. */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Unhandled executor error. Body is `{ success: false, error }` (same envelope as 200). */
+                500: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            success: boolean;
+                            message?: string;
+                            error?: string;
+                            code?: string;
+                            data?: unknown;
+                            action?: unknown;
+                        };
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/chatty-voice/ai-context": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Fetch the Chatty Voice system prompt + load-status flags. */
+        get: {
+            parameters: {
+                query?: never;
+                header?: {
+                    /** @description Semver of the calling app build. Drives the 426 / soft-upgrade handshake. */
+                    "X-Client-Version"?: string;
+                };
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description System instructions + knowledge-base / workflow-stage load flags. */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            instructions: string;
+                            knowledgeBaseLoaded: boolean;
+                            workflowStagesLoaded: boolean;
+                            timestamp: string;
+                        };
+                    };
+                };
+                /** @description Unauthenticated. */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Caller lacks the chatty-voice entitlement. */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/realtime-token": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Mint an OpenAI Realtime ephemeral session token (single union object).
+         * @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.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: {
+                    /** @description Semver of the calling app build. Drives the 426 / soft-upgrade handshake. */
+                    "X-Client-Version"?: string;
+                };
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": {
+                        directWebRTC?: boolean;
+                    };
+                };
+            };
+            responses: {
+                /** @description Session minted (or fallback signalled). See union shape. */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            sessionId?: string;
+                            model?: string;
+                            voice?: string;
+                            clientSecret?: string;
+                            fallback: boolean;
+                            directWebRTC?: boolean;
+                            useWebRTC?: boolean;
+                            expiresInSeconds?: number;
+                            metadata?: {
+                                organizationId: string | number;
+                            };
+                            message?: string;
+                        };
+                    };
+                };
+                /** @description Unauthenticated. */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Caller lacks the chatty-voice entitlement. */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Method Not Allowed (POST only). */
+                405: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Per-user rate limit on token mint. */
+                429: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Mint failure — body still carries `fallback: true`. */
+                500: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            sessionId?: string;
+                            model?: string;
+                            voice?: string;
+                            clientSecret?: string;
+                            fallback: boolean;
+                            directWebRTC?: boolean;
+                            useWebRTC?: boolean;
+                            expiresInSeconds?: number;
+                            metadata?: {
+                                organizationId: string | number;
+                            };
+                            message?: string;
+                        };
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/csrf-token": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Mint a short-lived CSRF token for the WebRTC SDP exchange.
+         * @description Returned token is required as `X-CSRF-Token` on POST /api/realtime/webrtc and is bound to the calling user for 5 minutes.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: {
+                    /** @description Semver of the calling app build. Drives the 426 / soft-upgrade handshake. */
+                    "X-Client-Version"?: string;
+                };
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Fresh CSRF token. */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            token: string;
+                        };
+                    };
+                };
+                /** @description Unauthenticated. */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Caller lacks the chatty-voice entitlement. */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/realtime/webrtc": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Server-proxied OpenAI Realtime SDP exchange (desktop branch).
+         * @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.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header: {
+                    /** @description Semver of the calling app build. Drives the 426 / soft-upgrade handshake. */
+                    "X-Client-Version"?: string;
+                    /** @description CSRF token previously minted by GET /api/csrf-token. */
+                    "X-CSRF-Token": string;
+                };
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": {
+                        sdp: string;
+                    };
+                };
+            };
+            responses: {
+                /** @description Raw OpenAI SDP answer (text body, not JSON). */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/sdp": string;
+                    };
+                };
+                /** @description Invalid SDP format. */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Unauthenticated. */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Caller lacks the chatty-voice entitlement, or CSRF token invalid. */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Rate limit (3 req/min/IP). */
+                429: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description SDP exchange failed locally. */
+                500: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @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? }`. */
+                502: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            error: string;
+                            status?: number;
+                        };
+                    };
+                };
+                /** @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. */
+                default: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": unknown;
+                        "text/plain": string;
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 export type webhooks = Record<string, never>;
 export interface components {
@@ -1302,7 +1848,7 @@ export interface components {
         };
         /** @description Cross-platform version handshake manifest. See docs/api-versioning.md. */
         VersionManifest: {
-            /** @example 1.1.22 */
+            /** @example 1.1.24 */
             apiVersion: string;
             /** @example 1.0.0 */
             minClientVersion: string;
@@ -1762,6 +2308,75 @@ export interface components {
             squareUpAngleRad: number;
             mirrorX: boolean;
         };
+        ChattyToolDefinition: {
+            /** @enum {string} */
+            type: "function";
+            function: {
+                name: string;
+                description: string;
+                parameters: {
+                    /** @enum {string} */
+                    type: "object";
+                    properties: {
+                        [key: string]: {
+                            [key: string]: unknown;
+                        } & {
+                            type: string | string[];
+                            description?: string;
+                            enum?: string[];
+                            required?: string[];
+                            additionalProperties?: boolean;
+                        };
+                    };
+                    required?: string[];
+                    additionalProperties?: boolean;
+                };
+            };
+        };
+        ChattyExecuteRequest: {
+            function?: string;
+            name?: string;
+            arguments?: {
+                [key: string]: unknown;
+            };
+        };
+        ChattyExecuteResponse: {
+            success: boolean;
+            message?: string;
+            error?: string;
+            code?: string;
+            data?: unknown;
+            action?: unknown;
+        };
+        ChattyAiContextResponse: {
+            instructions: string;
+            knowledgeBaseLoaded: boolean;
+            workflowStagesLoaded: boolean;
+            timestamp: string;
+        };
+        RealtimeTokenRequest: {
+            directWebRTC?: boolean;
+        };
+        RealtimeTokenResponse: {
+            sessionId?: string;
+            model?: string;
+            voice?: string;
+            clientSecret?: string;
+            fallback: boolean;
+            directWebRTC?: boolean;
+            useWebRTC?: boolean;
+            expiresInSeconds?: number;
+            metadata?: {
+                organizationId: string | number;
+            };
+            message?: string;
+        };
+        CsrfTokenResponse: {
+            token: string;
+        };
+        RealtimeWebrtcRequest: {
+            sdp: string;
+        };
     };
     responses: never;
     parameters: never;