# rtcStats API (v1.0)

API for third-party applications to **upload**, **analyze**, or use the **MCP Streamable HTTP** endpoint at `/api/rtcstats/v1.0/mcp`.

Uses Bearer token authentication.

**Note:** Need to create an application token in Settings from your paid account.

Base URL: `https://www.rtcstats.com`

## Authentication

- **BearerAuth**: http (bearer JWT). Use header: Authorization: Bearer

## Endpoints

### POST /api/rtcstats/v1.0/upload — Upload

Upload and store a WebRTC dump file or a rtcstats file to your account using a chunked flow.

The API works in two steps:
- First upload chunks via multipart/form-data
- Then assemble via application/json

The API consumes one credit if successful.

**Request body:**

- `multipart/form-data`: object { chunk, fileId, chunkIndex }
  - `chunk` (required) — string (binary)
  - `fileId` (required) — string. Client-generated id for this chunked upload (same value for all chunks and assemble).
  - `chunkIndex` (required) — string
- `application/json`: object { fileId, assemble, fileName }
  - `fileId` (required) — string. Same id used when uploading chunks.
  - `assemble` (required) — boolean
  - `fileName` (required) — string

**Responses:**

- `200` Success — object { success, rtcstatsId, rtcstatsUrl, embedUrl }
- `400` Invalid request — [Error](#error)
- `401` Missing or invalid token — [Error](#error)
- `402` No credits available — [Error](#error)
- `413` File exceeds size limit — [Error](#error)
- `500` Processing error — [Error](#error)

### POST /api/rtcstats/v1.0/analyze — Analyze

Upload a webrtc-internal file or a rtcstats file, process it and return summary, observations and scores. Optional query `save=true` (or `save=1`) also persists the dump like `/upload`.

This API consumes one credit if successful.

**Parameters:**

- `save` (query) — string. When `true` or `1`, store the file in the account in addition to returning the analysis JSON.

**Request body:**

- `application/octet-stream`: string (binary)

**Responses:**

- `200` Success — object { data, rtcstatsId, rtcstatsUrl, embedUrl }
- `400` Invalid request — [Error](#error)
- `401` Missing or invalid token — [Error](#error)
- `402` No credits available — [Error](#error)
- `413` File exceeds size limit — [Error](#error)
- `415` Parsing issue — [Error](#error)
- `500` Processing error — [Error](#error)

### POST /api/rtcstats/v1.0/mcp — MCP Streamable HTTP

Model Context Protocol **Streamable HTTP** transport.
Use an MCP client with this URL.
Send `Authorization: Bearer` with your application JWT on requests that invoke tools.
Exposes tools:
- `get_quota`
- `list_sessions`
- `get_session`

**Request body:**

MCP JSON-RPC payload (when applicable).

- `application/json`: object

**Responses:**

- `200` Success (MCP Streamable HTTP) — string
- `400` Bad request — [McpStreamableHttpTransportError](#mcpstreamablehttptransporterror)
- `404` MCP Session Not found — [McpStreamableHttpTransportError](#mcpstreamablehttptransporterror)

### GET /api/rtcstats/v1.0/quota — Quota

Returns total allowed credits and remaining credits for the account. Include the purchased credits.

**Responses:**

- `200` Success — [QuotaResponse](#quotaresponse)
- `401` Missing or invalid token — [Error](#error)
- `500` Server error — [Error](#error)

### GET /api/rtcstats/v1.0/sessions — List sessions

Returns existing stored sessions for the token account ordered by creation date (newest first). All filters are optional. Different filters are AND-combined; multiple values within one filter are OR-combined.

**Parameters:**

- `name` (query) — array of string. Filter sessions whose title contains ANY of these substrings
- `observationTags` (query) — array of string. Filter sessions whose observations carry ANY of these tags. Comma-separated. Valid tags: `connectivity`, `security`, `audio`, `video`, `datachannel`, `outbound`, `inbound`, `peripheral`, `behavior`, `network`, `configuration`, `cpu`, `bug`.
- `os` (query) — string. Filter sessions by operating system (exact match). Examples: `macOS`, `Windows`, `Linux`, `Android`, `iPhone`, `iPad`.
- `browser` (query) — string. Filter sessions by browser (exact match). Examples: `Chrome`, `Safari`, `Firefox`, `Edge`.
- `browserVersion` (query) — string. Filter sessions by major browser version (exact match, e.g. `142`).
- `userId` (query) — string. Filter sessions by the end-user identifier carried in the rtcstats JWT (summary metadata user).
- `conferenceId` (query) — string. Filter sessions by the conference identifier carried in the rtcstats JWT (summary metadata conference).
- `sessionId` (query) — string. Filter sessions by the session identifier carried in the rtcstats JWT (summary metadata session).
- `hasCritical` (query) — boolean. When `true`, only sessions with at least one critical-severity observation.
- `hasHigh` (query) — boolean. When `true`, only sessions with at least one high-severity observation.
- `hasMedium` (query) — boolean. When `true`, only sessions with at least one medium-severity observation.
- `hasLowScore` (query) — boolean. When `true`, only sessions whose experience score is low (`< 60`).
- `hasMediumScore` (query) — boolean. When `true`, only sessions whose experience score is medium (`60` to `79`).
- `hasHighScore` (query) — boolean. When `true`, only sessions whose experience score is high (`>= 80`).

**Responses:**

- `200` Success — [SessionsListResponse](#sessionslistresponse)
- `401` Missing or invalid token — [Error](#error)
- `500` Server error — [Error](#error)

### GET /api/rtcstats/v1.0/sessions/{rtcstatsId} — Retrieve Session

Returns the session detail including summary, observations and scores.

**Parameters:**

- `rtcstatsId` (path, required) — string (uuid). The rtcstats session identifier

**Responses:**

- `200` Success — object { data, rtcstatsId, rtcstatsUrl, embedUrl }
- `400` Invalid session id — [Error](#error)
- `401` Missing or invalid token — [Error](#error)
- `404` Session not found for this account — [Error](#error)
- `422` Reprocess failed — [Error](#error)
- `500` Server error — [Error](#error)

### DELETE /api/rtcstats/v1.0/sessions/{rtcstatsId} — Delete session

Deletes a stored session by its identifier.

**Parameters:**

- `rtcstatsId` (path, required) — string (uuid). The rtcstats session identifier

**Responses:**

- `200` Success — object { success }
- `400` Invalid id — [Error](#error)
- `401` Missing or invalid token — [Error](#error)
- `404` Not found — [Error](#error)
- `500` Server error — [Error](#error)

## Schemas

### Error

- `error` (required) — string
- `errorCode` (required) — string

### AnalyzeResponseData

Session payload peer-connections, observations and scores.

- `callStart` — string (date-time). First observed call activity timestamp.
- `callEnd` — string (date-time). Last observed call activity timestamp.
- `durationMs` — integer. Total call duration in milliseconds.
- `userAgentData` — object. Browser, platform, hardware and screen information.
- `pConnectionsNumber` — integer. Number of RTCPeerConnections observed during the session.
- `pConnections` — object. Per-PeerConnection details keyed by peer connection id.
- `streams` — object. Peer-stream metrics (audio, video, data) keyed by stream id.
- `transports` — object. ICE transport and candidate-pair information per PeerConnection.
- `aggregatedStats` — object. Session-wide aggregated metrics (jitter, RTT, bitrate, packet loss, MoS) with avg/min/max.
- `metadata` — object. Client protocol and custom flags.
- `connectivity` — string. Resolved connectivity type for the session.
- `title` — string. Human-readable session title (often derived from the call URL).
- `fileName` — string. Internal name of the stored dump file.
- `fileSize` — integer. Size of the uploaded dump in bytes.
- `experienceScore` — number. Overall experience score (0-100). 0 when there is no media data to score against.
- `audioScore` — number, nullable. Audio quality score (1-5). Null when no audio stream is present.
- `videoScore` — number, nullable. Video quality score (1-5). Null when no video stream is present.
- `connectivityScore` — number, nullable. Connectivity score (1-5). Null when no peer connection produced a connectivity score (e.g. no valid candidate pair).
- `observationsScore` — integer. Aggregated severity score derived from observations. Maximum (40) when no observations were produced; lower as severity penalties are applied.
- `tagClouds` — array of object. Tag-cloud entries derived from the session.
- `id` — string (uuid). Session identifier (same as rtcstatsId).
- `created_at` — string (date-time), nullable. Row creation timestamp. Null on `POST /analyze` without `?save=true` (the dump is not persisted).
- `uploaded_by` — string (uuid), nullable. Identifier of the account/user that uploaded the dump. Null on `POST /analyze` without `?save=true`.
- `uploaded_by_email` — string (email), nullable. Email of the uploader. Null on `POST /analyze` without `?save=true`.
- `public_link` — string, nullable. Share token for the public viewer.
- `description` — string, nullable. Optional free-text description.
- `tags` — array of string. User-defined tags attached to the session.
- `observations` — array of object. Detected issues and insights with severity, source, category and supporting indicators.
- `features` — object. Boolean and value flags about devices, network and capabilities used during the session.
- `observationsCount` — object. Counts of observations grouped by severity (critical, high, medium, low, info).
- `aiSummary` — string, nullable. Optional AI-generated session summary.

### McpStreamableHttpTransportError

JSON-RPC 2.0 envelope returned by the MCP Streamable HTTP transport for **HTTP-level** failures (before or outside the SSE stream). This is not the same shape as tool errors from `tools/call`, which are delivered with HTTP 200 inside the stream as JSON-RPC responses.

- `jsonrpc` (required) — string enum: `2.0`
- `error` (required) — object { code, message, data }
- `id` (required) — any, nullable. Always `null` for transport-level errors.

### McpJsonRpcSseDataLine

One JSON object carried in a single SSE `data:` line after a successful POST that contained JSON-RPC **requests**. Either `result` (success) or `error` (failure) is present; `id` matches the client request.

- `jsonrpc` (required) — string enum: `2.0`
- `id` (required) — any. Request id (string or number) from the client; omitted only for responses that omit id per JSON-RPC rules.
- `result` — any. Success payload (e.g. `initialize`, `tools/list`, `tools/call` with `content` / `structuredContent`).
- `error` — object { code, message, data }. JSON-RPC error for this request id (e.g. MCP or tool failure).

### QuotaResponse

- `accountName` (required) — string. Account display name.
- `accountPlan` (required) — string enum: `developer`, `trial_developer`, `enterprise`. Effective plan for the account.
- `allowedCredits` (required) — number. Total credits allowed for the account (monthly allocation plus purchased)
- `remainingCredits` (required) — number. Credits available.

### SessionListItem

- `rtcstatsId` (required) — string (uuid)
- `createdAt` (required) — string (date-time). When the session row was created.
- `sessionStart` (required) — string, nullable. Call start from summary when available.
- `sessionEnd` (required) — string, nullable. Call end from summary when available.
- `title` (required) — string
- `rtcstatsUrl` (required) — string. Dashboard URL to open the rtcstats session.
- `embedUrl` — string. URL to open the session in the embedded viewer. Only present on the Enterprise plan.
- `abstract` (required) — [SessionAbstract](#sessionabstract), nullable. Denormalized session summary used to drive the list filters. `null` for rows that have not been indexed yet.

### SessionAbstract

Same shape as the stored `summary_index` jsonb column. Returned alongside each session in the list so clients can render badges or compute their own filters without a second call. Every property is always present.

- `observationFlags` (required) — array of string. Unique flag names of observations with severity critical/high/medium.
- `observationTags` (required) — array of string. Unique tag-cloud tags with a non-zero critical/high/medium contribution.
- `browser` (required) — string, nullable
- `browserVersion` (required) — string, nullable. Major browser version only (e.g. `142`).
- `os` (required) — string, nullable
- `osVersion` (required) — string, nullable
- `conferenceId` (required) — string, nullable
- `sessionId` (required) — string, nullable
- `userId` (required) — string, nullable
- `experienceScore` (required) — number, nullable
- `connectivity` (required) — string, nullable
- `observationsCritical` (required) — integer
- `observationsHigh` (required) — integer
- `observationsMedium` (required) — integer
- `scoreBand` (required) — string enum: `low`, `medium`, `high`, `unrated`. Experience-score band: `high` (>= 80), `medium` (60..79), `low` (< 60), or `unrated` when there is no score.

### SessionsListResponse

- `total` (required) — integer. Number of sessions in `data`.
- `data` (required) — array of [SessionListItem](#sessionlistitem)