RealCall Session API | Reality Defender

Overview

Reality Defender provides several 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, RealCall 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 remaining endpoints retrieve real-time results for a session using the session_id. The caller controls how long to wait for the analysis result, making them suitable for either polling or blocking interactions. As of the latest release, the recording_stop endpoint can also return results directly, so a single call can both stop the stream and return its final conclusion.

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.

Start and Stop Recording

You can configure RealCall 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: The recording.stop event itself is fire-and-forget — it is not an error to send a start event to a session already recording, or a stop event to a session already stopped. Such events are silently accepted. See Stop Recording for how the response behaves when the referenced session does not exist.

Start Recording

Endpoint

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

Headers

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

Request Body

{
  "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

Stop Recording

Stops recording the current stream for a session. In addition to ending the recording, this endpoint returns the session’s analysis results in the same response — combining the stop action and result retrieval into a single call. Optionally, it can wait for the stream that was just stopped to produce its final result before returning.

Endpoint

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

Headers

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

Query Parameters

Parameter	Required	Description
`timeout`	No	Maximum time in seconds to wait for the stopped stream’s result. If omitted, 0, or negative, the endpoint does not wait and returns whatever results are currently available. If greater than 0, the endpoint waits up to that many seconds (capped at 10 seconds) for the most recently started stream to produce a result before returning.

Request Body

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

Response

The response body is a JSON array of results, identical in shape to /stream_results (an empty array [] when no results are available). Results are ordered by stream creation time, newest first, so results[0] corresponds to the stream that was just stopped.

Example cURL Request (stop, return immediately)

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"

Example cURL Request (stop, wait up to 5 seconds for the result)

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?timeout=5"

Timeout Behavior

The recording.stop event is always published first; this part of the call is fire-and-forget.
After publishing the stop, the endpoint looks up the current results for the session and returns immediately when the most recently started stream has already produced its result, or when timeout is omitted or 0.
When timeout > 0 and the stopped stream has not yet produced a result, the request blocks — re-checking once per second — until that stream finishes (whether its verdict is conclusive or INCONCLUSIVE) or the timeout elapses, whichever comes first. On timeout it returns the current results (possibly an empty array).
Only the most recently started stream gates the wait. Other (older) streams that are slow or never complete will not hold the response open.

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 and returns the session’s results (optionally waiting; see Stop Recording). RealCall pauses and waits for the next `recording_start` call.
Automatic Stop	If RealCall reaches a conclusion (e.g., a threat is detected), it will automatically stop listening if configured to do so.

Retrieving Analysis Results

Several 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
`/recording_stop`	All conclusions (0 or more)	Yes (`timeout` parameter, up to 10 seconds)	Stop a stream and retrieve its result in one call (see Stop Recording)

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.

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": "INCONCLUSIVE",
  "created_at": "2025-03-15T15:26:45.927786Z",
  "languages": [
    {
      "language": "",
      "supported": false
    }
  ],
  "metadata": {},
  "milliseconds_to_conclusion": 5409,
  "probability": -1,
  "reason": "prerecorded_machine_response",
  "session_id": "2z3ExBoJa3qlgCnjhxkD8kjyhXL",
  "stream_id": "2z3ExBoJa3qlgCnjhxkD8kjyhXL",
  "updated_at": "2025-03-15T15:26:45.927786Z"
}

The reason field is a short, machine-readable explanation that accompanies certain conclusions. When the pipeline’s Content Classification Flags (CCF) detection detects a prerecorded machine response, the conclusion is INCONCLUSIVE and the reason is prerecorded_machine_response, as shown above.

The field is also populated for other INCONCLUSIVE results. For example, "reason": "not enough speech for CCF" when there was not enough speech to reach a verdict.

For most other conclusions it is an empty string.

Note: CCF is disabled by default. To enable it, see Optional: Enable CCF in Setup and Testing.

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. Results are ordered by stream creation time, newest first, so results[0] is the most recently created stream.

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": "INCONCLUSIVE",
    "reason": "prerecorded_machine_response",
    "probability": -1,
    "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",
    "reason": "",
    "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": {}
  }
]

Long Polling Behavior

When using /stream_result (or /recording_stop with a timeout), 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 the current status (an empty result/array, or `404 Not Found` for `/stream_result`)
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.

Response Codes

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

Setup and Testing

To begin using the Session API, you 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.os.realitydefender.xyz/. 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, then click Settings.

Step 3: Navigate to API Keys.

On the Settings page, select API Keys.

Step 4: Generate a new key.

Click Add API Key in the upper-right corner. The new API key will appear on your screen.

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 the 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 the session_id in the column to open a slide-in panel on the right 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.

Optional: Enable CCF

CCF helps RealCall recognize when a call is dominated by known system voices, such as voicemail greetings, IVR prompts, or call-screening bots. When CCF is enabled, these calls can return an Inconclusive result with a clear reason, such as prerecorded_machine_response, instead of being incorrectly flagged as Manipulated.

To enable CCF, go to Settings > General, then toggle on Content Classification Flags.

Summary

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