Skip to main content
WSS
Beta — this API is under active development and may change without notice.
bearerAuth
type:http

API key authentication. Include your API key in the Authorization header as 'Bearer <api_key>'.

headers
type:object
X-Client-Request-Id
type:string

Optional identifier supplied by the client to correlate this request with their own logs. When provided, the value is recorded alongside the server-assigned correlation ID in Interhuman logs to aid lookup and support investigations. This header is not echoed back in the response; the server returns its own correlation ID in the X-Correlation-ID HTTP response header.

Sec-WebSocket-Protocol
type:string

Authentication transport for clients that cannot set an Authorization header on a WebSocket connection, such as the browser WebSocket API. Send the literal subprotocol marker access_token followed by your credential, as a comma-separated subprotocol list:

In browser JavaScript, pass the same pair as the constructor's subprotocol array:

access_token is the required literal marker and <credential> is your bearer credential. In a browser, this should be a short-lived access token minted server-side by the client tokens endpoint (POST /v1/client_tokens) — never your API key. The server selects and echoes access_token as the negotiated subprotocol, never the credential. Treat the credential as a secret: never log it.

Example: access_token, <credential>
Video (bytes)

Binary video segment sent by the client for analysis. Each segment must not exceed 32MB. Accepts the following formats: mp4, avi, mov, mkv, mpeg-ts, mpeg-2-ts, webm.

Session Close
type:object

Inbound session.close text frame.

Realtime Session Config
type:object

Caller-supplied session configuration for the realtime endpoint.

Transcript Update
type:object

Inbound transcript.updated text frame.

Coverage Degraded
type:object

Reports that one or more analysis windows were analyzed with partial visual coverage. Emitted when a window decodes materially less video than the window span while its audio runs to the end — typically a stream whose keyframe interval exceeds the analysis window (a static screen share, a long-GOP encoder). This is an informational notice, not an error: the session stays open, the windows were analyzed (audio plus whatever video decoded) and are billed normally. data.ranges lists the affected time ranges in absolute session-cumulative seconds; data.reason is currently always video_gap.

Coverage Dropped
type:object

Reports that analysis coverage was reduced under backpressure. Emitted when the analysis pipeline saturates and has to skip buffered video. This is an informational notice, not an error: the session stays open, subsequent windows continue uninterrupted, and the dropped portions of the video are not billed. data.ranges lists the skipped time ranges in absolute session-cumulative seconds.

Error
type:object

Reports an error encountered while processing the stream. data.code carries the machine-readable error id (sub-type), and data.segment identifies the incoming caller segment when the failure maps to a specific chunk (size validation, quota); analysis-time failures that do not map to one chunk carry data.segment: null.

Recommendation Generated
type:object

Reports a periodic recommendation of the conversation so far. Recommendation is emitted only when all three conditions hold: the caller supplies realtime_recommendation_instructions in session.config, at least one signal has been detected, and at least one transcript has been received since the previous recommendation. Once enabled it is paced by the session-config realtime_recommendation_frequency (high/medium/low mapped to 10/20/30 seconds of analyzed video).

Session Closing
type:object

Acknowledges that an inbound session.close text frame was accepted. From this point the server rejects new binary video frames, finishes analyzing the video it already accepted (emitting the normal result envelopes in order), emits final lifecycle envelopes for still-open analysis state, sends session.ended, and closes the WebSocket. data.max_drain_seconds is the maximum time the caller should wait for session.ended after this acknowledgment; the session closes earlier when the accepted work finishes sooner.

Session Ended
type:object

The final message of a gracefully closed session. Emitted after every already-accepted analysis window has drained (or the max_drain_seconds deadline advertised on session.closing expired) and after the final lifecycle envelopes for still-open analysis state. No further analysis messages follow; the server closes the WebSocket (close code 1000) immediately after sending it.

Session Ready
type:object

Acknowledges that the v1 realtime session is established. Emitted exactly once per session, immediately after the server accepts the WebSocket handshake. Carries the session-level contract (idle / max-duration timeouts, segment size constraints, supported session-config options) so the caller can adapt its producer side without round-tripping rejections. supported_session_config_options advertises the values the server accepts for realtime_recommendation_instructions, realtime_recommendation_frequency, and analysis_groups.

Session Updated
type:object

Acknowledges that an inbound realtime_session_config_v1 text frame was accepted. Carries the consolidated post-apply realtime config (realtime_recommendation_instructions / realtime_recommendation_frequency / analysis_groups).

Signal Detected
type:object

Reports that a social signal has transitioned from inactive to active. Emitted once when the signal type is first detected for the session, and again only when the signal becomes active after a prior signal.ended. data.start uses absolute session-cumulative time.

Signal Ended
type:object

Reports that a previously active social signal is no longer active. Emitted when a signal type that was active in the previous analyzed window is not present in the current window. data.end uses absolute session-cumulative time.

Signal Updated
type:object

Reports that an already-active social signal experienced a change in probability. Emitted when an active signal type's probability has changed from the previous value reported for that signal type (either signal.detected or a prior signal.updated). data.start uses absolute session-cumulative time.