Sample Responses

Every RealtimeX API response uses the same top-level JSON shape. Your client can branch on success, show message to users or logs, and read data when the call succeeds.

Endpoint pages include full success samples (and often error samples). This page documents the shared envelope, common data shapes, and how pagination is returned for list endpoints.

{
  "success": true,
  "message": "Description of the result",
  "data": {},
  "error": null
}

Always check the HTTP status code together with success. A 401/403/404 response will still use this envelope.

Single resource

Get / update endpoints typically return one document under data:

{
  "success": true,
  "message": "Settings fetched successfully",
  "data": {
    "_id": "6a57...739c",
    "clientId": "6a57...f0c0",
    "settings": {
      "videoCallEnabled": true,
      "pushNotificationEnabled": true
    },
    "limits": {
      "maxParticipantsPerGroup": 256
    }
  },
  "error": null
}

Action result

Some writes return the updated entity (mute, ban, resolve report). Use the returned fields to refresh badges without an extra GET when the payload is complete enough for your UI.

Many list endpoints nest items under data.list and include a data.pagination object:

{
  "success": true,
  "message": "Reports fetched successfully",
  "data": {
    "list": [
      {
        "_id": "6a58...80ee",
        "reason": "Spam content",
        "status": "pending"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalCount": 1,
      "hasNextPage": false,
      "hasPreviousPage": false,
      "pageSize": 10
    }
  },
  "error": null
}

Exact list field names can vary slightly by older endpoints. Prefer the sample on the specific endpoint page when integrating.

Failures keep the same envelope with success: false and usually data: null:

{
  "success": false,
  "message": "No token, authorization denied",
  "data": null,
  "error": "Unauthorized"
}

See Error codes and Status codes for how to map HTTP status values to recovery behavior.

1. Read the HTTP status (2xx vs 4xx/5xx) from your HTTP client.
2. Parse JSON and check success.
3. On success, bind data (or data.list) into state.
4. On failure, show message and branch on status (refresh token on 401, fix validation on 400, etc.).

• Type the envelope once in your SDK ({ success, message, data, error }) and reuse it for every call.
• Do not assume data is always an object — list endpoints nest arrays; some deletes may return null.
• Prefer server message for operator tools; map known codes to friendlier copy for end users.
• Log message + HTTP status for support tickets; avoid logging tokens from request headers.