Reality Defender Session API | Reality Defender

Overview

Reality Defender provides three endpoints in support of deepfake detection for real-time media. The first two endpoints control when to start and stop recording of a real-time stream. By default, Reality Defender integrations begin recording once the session arrives at the platform (also known as "immediate start"), and recording stops once a determination has been made as to whether the session contains manipulated media. These API endpoints allow customers greater control over this default configuration.

The third endpoint retrieves real-time results for a session using the session_id. The caller controls how long to wait for the analysis result, making it suitable for either polling or blocking interactions.

Prerequisites

Requirement	Description
API Key	Generated from the Reality Defender dashboard.
Organization ID	The unique identifier for your organization, provided by Reality Defender.
Session ID	The identifier for the session to be modified or queried, provided by your integration.
Track	For sessions with multiple audio tracks (e.g., stereo), the text name identifying the track. Not required for mono integrations.

1. Start and Stop Recording

Reality Defender can be configured to start in a paused state, meaning it will not listen to or analyze media until explicitly instructed. This is useful for integrations — such as SIPREC — where recording should only begin after an internal routing decision has been made.

Start and stop events may occur multiple times during a single session. Reality Defender assigns a unique stream ID to each recording generated within a session.

Note: It is not an error to send a start event to a session already recording, a stop event to a session already stopped, or a start or stop event for a session that does not exist. All such events are silently ignored.

1.1 Start Recording

Endpoint

POST https://app.session-api.voiceguard.realitydefender.xyz/recording_start

Headers

X-API-KEY: <your-api-key-here>

Request Body

json

{
"session_id": <session_id>,
"track": "external"
}

Example cURL Request

curl -X POST \
-H "Content-Type: application/json" \
-H "X-API-KEY: <your-api-key-here>" \
-d '{"session_id": <session_id>,"track": "external"}' \
https://app.session-api.voiceguard.realitydefender.xyz/recording_start

1.2 Stop Recording

Endpoint

POST https://app.session-api.voiceguard.realitydefender.xyz/recording_stop

Headers

X-API-KEY: <your-api-key-here>

Request Body

json

{
"session_id": <session_id>,
"track": "external"
}

Example cURL Request

curl -X POST \
-H "Content-Type: application/json" \
-H "X-API-KEY: <your-api-key-here>" \
-d '{"session_id": <session_id>,"track": "external"}' \
https://app.session-api.voiceguard.realitydefender.xyz/recording_stop

1.3 Behavior and Considerations

Event	Behavior
Start Recording	If no recording is in progress, a new stream begins. If recording is already active, this call has no effect and does not create a new stream.
Stop Recording	Ends the current recording stream. Reality Defender pauses and waits for the next `recording_start` call.
Automatic Stop	If Reality Defender reaches a conclusion (e.g., a threat is detected), it will automatically stop listening if configured to do so.

2. Retrieving Analysis Results

Two endpoints are available for retrieving stream analysis results:

Endpoint	Returns	Timeout Support	Use Case
`/stream_result`	A single conclusion	Yes (`timeout` parameter, up to 10 minutes)	Long polling; environments with exactly one stream per session
`/stream_results`	All conclusions (0 or more)	No	Immediate polling; environments with multiple streams per session

Note: stream_results returns an empty array when no results are ready. Invoking code should wait at least 1 second before retrying.

Endpoints

GET https://app.session-api.voiceguard.realitydefender.xyz/stream_result GET https://app.session-api.voiceguard.realitydefender.xyz/stream_results

Headers

X-API-KEY: <your-api-key-here>

Query Parameters

Parameter	Required	Description
`session_id`	Yes	The unique identifier of the session to retrieve results for.
`timeout`	No	Maximum time in seconds to wait for a result when using long polling. Default: 60 seconds. Maximum: 10 minutes. Valid for `/stream_result` only.

2.1 stream_result

Use this endpoint when there is exactly one stream per session. Returns a single conclusion and accepts a timeout parameter to support long polling.

Example stream_result cURL Request

curl -X GET \
-H "X-API-KEY: <your-api-key-here>" \
"https://app.session-api.voiceguard.realitydefender.xyz/stream_result?session_id=<session_id>&timeout=5"

Example stream_result Response

{
  "call_id": "2z3ExDe246qkmfzVbP1KWZYBYnu",
  "conclusion": "ARTIFICIAL",
  "created_at": "2025-03-15T15:26:45.927786Z",
  "languages": [
    {
      "language": "",
      "supported": false
    }
  ],
  "metadata": {},
  "milliseconds_to_conclusion": 5409,
  "probability": 0.9999563694000244,
  "session_id": "2z3ExBoJa3qlgCnjhxkD8kjyhXL",
  "stream_id": "2z3ExBoJa3qlgCnjhxkD8kjyhXL",
  "updated_at": "2025-03-15T15:26:45.927786Z"
}

2.2 stream_results

Use this endpoint when there may be multiple stream recordings associated with a single session. Returns all conclusions found, or an empty array if none are ready.

Example stream_results cURL Request

curl -X GET \
-H "X-API-KEY: <your-api-key-here>" \
"https://app.session-api.voiceguard.realitydefender.xyz/stream_results?session_id=<session_id>"

Example stream_results Response

[
  {
    "stream_id": "2z3ExBoJa3qlgCnjhxkD8kjyhXL",
    "call_id": "2z3ExDe246qkmfzVbP1KWZYBYnu", 
    "session_id": "2z3ExBoJa3qlgCnjhxkD8kjyhXL",
    "conclusion": "ARTIFICIAL",
    "probability": 0.9999563694000244,
    "languages": [
      {
        "language": "ENGLISH",
        "supported": true
      }
    ],
    "milliseconds_to_conclusion": 5409,
    "created_at": "2025-03-16T15:26:45.927786Z",
    "updated_at": "2025-03-16T15:26:45.927786Z",
    "metadata": {}
  },
  {
    "stream_id": "2z3ExBoJa3qlgCnjhxkD8kjyhXL-2",
    "call_id": "2z3ExDe246qkmfzVbP1KWZYBYnu",
    "session_id": "2z3ExBoJa3qlgCnjhxkD8kjyhXL", 
    "conclusion": "AUTHENTIC",
    "probability": 0.85,
    "languages": [
      {
        "language": "SPANISH", 
        "supported": true
      }
    ],
    "milliseconds_to_conclusion": 7000,
    "created_at": "2025-03-16T15:26:46.123456Z",
    "updated_at": "2025-03-16T15:26:46.123456Z",
    "metadata": {}
  }
]

2.3 Long Polling Behavior

When using /stream_result, the request is held open until one of the following occurs:

Condition	Outcome
A result becomes available	Returns `200 OK` with the result
An error occurs (other than not found)	Returns the appropriate error code
The `timeout` duration is reached	Returns current status, typically `404 Not Found`
Client disconnects	Request ends immediately

This mechanism reduces the need for frequent polling and allows clients to receive analysis results as soon as they are ready.

3. Response Codes

Code	Description
`200`	Successful execution
`400`	Missing required parameters
`401`	Invalid or missing API key
`403`	Organization ID does not match session organization ID
`404`	Session, stream, or result not found (or timed out)
`500`	Internal server error

4. Setup and Testing

To begin using the Session API, you will need access to the Reality Defender dashboard. Contact your account manager for access.

Step 1: Log In to the Dashboard

The platform URL is https://app.voiceguard.realitydefender.xyz/login. If your account has access to multiple organizations, choose the organization where you will be performing your testing.

Your screen will look similar to this after logging in.

Step 2: Access your organization settings.

In the bottom-left corner, click your username to open the organization settings pop-up.

Step 3: Navigate to API Keys.

Click Settings, then select API Keys.

Step 4: Generate a new key.

Click Add API Key in the upper-right corner. Your screen will then display the new API key.

Step 5: Copy and store the key.

Click the copy icon to the right of the key to copy it to your clipboard. Store the key in your environment or a credentials manager — do not embed it in your source code. You can return to this screen at any time to retrieve or generate a new key.

With your API key, you can now perform test calls into the platform (use the telephone number provided by your account manager) or upload single-speaker mono wav files using the Upload audio button above your account name on the left-hand side. After submitting media for analysis, click the Calls tab on the left-hand side of the screen to view call history.

Step 6: Retrieve the session ID.

The Session API requires the session_id, which is the first column under the Call header in the table. Click on the session_id in the column and a slide-in panel will appear on the right-hand side of the screen, displaying the different segments that make up the stream.

Step 7: Copy the session ID.

At the top of that panel there is a copy icon next to the session_id. Click this to copy it to your clipboard.

With your API key and session_id you can now use cURL, Postman, or custom scripts to invoke the Session API.

Note: The recording start/stop endpoints are only testable during an active session. Stream result retrieval works both during and after a session.

Summary

Endpoint	Method	Purpose
`/recording_start`	POST	Begin recording a session stream
`/recording_stop`	POST	Stop recording a session stream
`/stream_result`	GET	Retrieve a single analysis result; supports long polling
`/stream_results`	GET	Retrieve all analysis results for a session

How to Integrate Reality Defender with Amazon Connect

How to Integrate Reality Defender with Genesys Cloud AudioHook

Reality Defender Live Media Scan: WebSocket Interface

Navigating the Dashboard