# Recordings

## List recordings

> Returns a paginated list of recordings. Members see only their own recordings; admins see all recordings in the account.<br>

```json
{"openapi":"3.0.3","info":{"title":"Screendesk API v2","version":"2.0.0"},"servers":[{"url":"https://app.screendesk.io/api/v2","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API token obtained from Screendesk account settings"}},"schemas":{"Pagination":{"type":"object","description":"Pagination metadata","properties":{"count":{"type":"integer","description":"Total number of records"},"page":{"type":"integer","description":"Current page number"},"items":{"type":"integer","description":"Number of items per page"},"pages":{"type":"integer","description":"Total number of pages"},"next_page":{"type":"integer","nullable":true,"description":"Next page number (absent if on last page)"},"prev_page":{"type":"integer","nullable":true,"description":"Previous page number (absent if on first page)"},"last_page":{"type":"integer","description":"Last page number"},"from":{"type":"integer","description":"Index of the first item on this page"},"to":{"type":"integer","description":"Index of the last item on this page"}}},"Recording":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"title":{"type":"string","nullable":true},"summary":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"metadata":{"$ref":"#/components/schemas/RecordingMetadata"},"technical_details":{"$ref":"#/components/schemas/TechnicalDetails"},"console_logs":{"type":"string","nullable":true,"description":"Raw console log output captured during the recording"},"customer":{"$ref":"#/components/schemas/Customer"},"user":{"$ref":"#/components/schemas/RecordingUser"},"room_insights":{"nullable":true,"description":"Live call session insights. Null for non-live recordings.","allOf":[{"$ref":"#/components/schemas/RoomInsights"}]}}},"RecordingMetadata":{"type":"object","properties":{"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"duration":{"type":"integer","nullable":true,"description":"Recording duration in seconds"},"impressions_count":{"type":"integer","description":"Number of times the recording has been viewed"},"recording_type":{"type":"string","enum":["Received","Sent","Live"],"description":"The type of recording"},"recording_source":{"type":"string","description":"Human-readable source label (e.g. \"Zendesk Ticket\", \"Intercom Operator\")"},"url":{"type":"string","format":"uri","description":"Public URL to view the recording"},"helpdesk_info":{"$ref":"#/components/schemas/HelpdeskInfo"}}},"HelpdeskInfo":{"type":"object","description":"Information about the associated helpdesk ticket or conversation","properties":{"platform":{"type":"string","enum":["zendesk","intercom","freshdesk","freshdesk_chat","helpscout","jira","screendesk app"]},"conversation_id":{"type":"string","nullable":true},"ticket_id":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true},"operator_id":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"issue_id":{"type":"string","nullable":true}}},"TechnicalDetails":{"type":"object","properties":{"vendor":{"type":"string","nullable":true},"ip_address":{"type":"string","nullable":true},"timezone":{"type":"string","nullable":true},"network_type":{"type":"string","nullable":true},"isp":{"type":"string","nullable":true}}},"Customer":{"type":"object","properties":{"email":{"type":"string","format":"email","nullable":true}}},"RecordingUser":{"type":"object","nullable":true,"description":"The agent/user who owns this recording. Null if no user is associated.","properties":{"email":{"type":"string","format":"email"},"name":{"type":"string"}}},"RoomInsights":{"type":"object","description":"Session-level insights for live video calls","properties":{"started_at":{"type":"string","format":"date-time","nullable":true},"ended_at":{"type":"string","format":"date-time","nullable":true},"duration":{"type":"integer","nullable":true,"description":"Call duration in seconds (inferred from started_at and ended_at)"},"total_participant_minutes":{"type":"number","nullable":true},"total_unique_participants":{"type":"integer","nullable":true},"participants_insights":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/ParticipantInsight"}}}},"ParticipantInsight":{"type":"object","properties":{"participant_id":{"type":"string"},"display_name":{"type":"string","nullable":true},"role":{"type":"string","nullable":true},"browser":{"type":"string","nullable":true},"os":{"type":"string","nullable":true},"device":{"type":"string","nullable":true},"device_type":{"type":"string","nullable":true},"user_agent":{"type":"string","nullable":true},"joined_at":{"type":"string","format":"date-time","nullable":true},"left_at":{"type":"string","format":"date-time","nullable":true}}},"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}},"responses":{"Unauthorized":{"description":"Invalid or missing API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"API access not enabled or insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/recordings":{"get":{"operationId":"listRecordings","summary":"List recordings","description":"Returns a paginated list of recordings. Members see only their own recordings; admins see all recordings in the account.\n","tags":["Recordings"],"parameters":[{"name":"page","in":"query","description":"Page number (defaults to 1)","required":false,"schema":{"type":"integer","minimum":1,"default":1}}],"responses":{"200":{"description":"A paginated list of recordings","content":{"application/json":{"schema":{"type":"object","properties":{"pagination":{"$ref":"#/components/schemas/Pagination"},"records":{"type":"array","items":{"$ref":"#/components/schemas/Recording"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}}}}
```

## Get a recording

> Returns a single recording by UUID.

```json
{"openapi":"3.0.3","info":{"title":"Screendesk API v2","version":"2.0.0"},"servers":[{"url":"https://app.screendesk.io/api/v2","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API token obtained from Screendesk account settings"}},"parameters":{"RecordingUUID":{"name":"uuid","in":"path","required":true,"description":"The recording's UUID","schema":{"type":"string","format":"uuid"}}},"schemas":{"Recording":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"title":{"type":"string","nullable":true},"summary":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"metadata":{"$ref":"#/components/schemas/RecordingMetadata"},"technical_details":{"$ref":"#/components/schemas/TechnicalDetails"},"console_logs":{"type":"string","nullable":true,"description":"Raw console log output captured during the recording"},"customer":{"$ref":"#/components/schemas/Customer"},"user":{"$ref":"#/components/schemas/RecordingUser"},"room_insights":{"nullable":true,"description":"Live call session insights. Null for non-live recordings.","allOf":[{"$ref":"#/components/schemas/RoomInsights"}]}}},"RecordingMetadata":{"type":"object","properties":{"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"duration":{"type":"integer","nullable":true,"description":"Recording duration in seconds"},"impressions_count":{"type":"integer","description":"Number of times the recording has been viewed"},"recording_type":{"type":"string","enum":["Received","Sent","Live"],"description":"The type of recording"},"recording_source":{"type":"string","description":"Human-readable source label (e.g. \"Zendesk Ticket\", \"Intercom Operator\")"},"url":{"type":"string","format":"uri","description":"Public URL to view the recording"},"helpdesk_info":{"$ref":"#/components/schemas/HelpdeskInfo"}}},"HelpdeskInfo":{"type":"object","description":"Information about the associated helpdesk ticket or conversation","properties":{"platform":{"type":"string","enum":["zendesk","intercom","freshdesk","freshdesk_chat","helpscout","jira","screendesk app"]},"conversation_id":{"type":"string","nullable":true},"ticket_id":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true},"operator_id":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"issue_id":{"type":"string","nullable":true}}},"TechnicalDetails":{"type":"object","properties":{"vendor":{"type":"string","nullable":true},"ip_address":{"type":"string","nullable":true},"timezone":{"type":"string","nullable":true},"network_type":{"type":"string","nullable":true},"isp":{"type":"string","nullable":true}}},"Customer":{"type":"object","properties":{"email":{"type":"string","format":"email","nullable":true}}},"RecordingUser":{"type":"object","nullable":true,"description":"The agent/user who owns this recording. Null if no user is associated.","properties":{"email":{"type":"string","format":"email"},"name":{"type":"string"}}},"RoomInsights":{"type":"object","description":"Session-level insights for live video calls","properties":{"started_at":{"type":"string","format":"date-time","nullable":true},"ended_at":{"type":"string","format":"date-time","nullable":true},"duration":{"type":"integer","nullable":true,"description":"Call duration in seconds (inferred from started_at and ended_at)"},"total_participant_minutes":{"type":"number","nullable":true},"total_unique_participants":{"type":"integer","nullable":true},"participants_insights":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/ParticipantInsight"}}}},"ParticipantInsight":{"type":"object","properties":{"participant_id":{"type":"string"},"display_name":{"type":"string","nullable":true},"role":{"type":"string","nullable":true},"browser":{"type":"string","nullable":true},"os":{"type":"string","nullable":true},"device":{"type":"string","nullable":true},"device_type":{"type":"string","nullable":true},"user_agent":{"type":"string","nullable":true},"joined_at":{"type":"string","format":"date-time","nullable":true},"left_at":{"type":"string","format":"date-time","nullable":true}}},"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}},"responses":{"Unauthorized":{"description":"Invalid or missing API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"API access not enabled or insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/recordings/{uuid}":{"get":{"operationId":"getRecording","summary":"Get a recording","description":"Returns a single recording by UUID.","tags":["Recordings"],"parameters":[{"$ref":"#/components/parameters/RecordingUUID"}],"responses":{"200":{"description":"Recording details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Recording"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Update a recording

> Updates a recording's title, summary, or description. Admin only.

```json
{"openapi":"3.0.3","info":{"title":"Screendesk API v2","version":"2.0.0"},"servers":[{"url":"https://app.screendesk.io/api/v2","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API token obtained from Screendesk account settings"}},"parameters":{"RecordingUUID":{"name":"uuid","in":"path","required":true,"description":"The recording's UUID","schema":{"type":"string","format":"uuid"}}},"schemas":{"Recording":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"title":{"type":"string","nullable":true},"summary":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"metadata":{"$ref":"#/components/schemas/RecordingMetadata"},"technical_details":{"$ref":"#/components/schemas/TechnicalDetails"},"console_logs":{"type":"string","nullable":true,"description":"Raw console log output captured during the recording"},"customer":{"$ref":"#/components/schemas/Customer"},"user":{"$ref":"#/components/schemas/RecordingUser"},"room_insights":{"nullable":true,"description":"Live call session insights. Null for non-live recordings.","allOf":[{"$ref":"#/components/schemas/RoomInsights"}]}}},"RecordingMetadata":{"type":"object","properties":{"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"duration":{"type":"integer","nullable":true,"description":"Recording duration in seconds"},"impressions_count":{"type":"integer","description":"Number of times the recording has been viewed"},"recording_type":{"type":"string","enum":["Received","Sent","Live"],"description":"The type of recording"},"recording_source":{"type":"string","description":"Human-readable source label (e.g. \"Zendesk Ticket\", \"Intercom Operator\")"},"url":{"type":"string","format":"uri","description":"Public URL to view the recording"},"helpdesk_info":{"$ref":"#/components/schemas/HelpdeskInfo"}}},"HelpdeskInfo":{"type":"object","description":"Information about the associated helpdesk ticket or conversation","properties":{"platform":{"type":"string","enum":["zendesk","intercom","freshdesk","freshdesk_chat","helpscout","jira","screendesk app"]},"conversation_id":{"type":"string","nullable":true},"ticket_id":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true},"operator_id":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"issue_id":{"type":"string","nullable":true}}},"TechnicalDetails":{"type":"object","properties":{"vendor":{"type":"string","nullable":true},"ip_address":{"type":"string","nullable":true},"timezone":{"type":"string","nullable":true},"network_type":{"type":"string","nullable":true},"isp":{"type":"string","nullable":true}}},"Customer":{"type":"object","properties":{"email":{"type":"string","format":"email","nullable":true}}},"RecordingUser":{"type":"object","nullable":true,"description":"The agent/user who owns this recording. Null if no user is associated.","properties":{"email":{"type":"string","format":"email"},"name":{"type":"string"}}},"RoomInsights":{"type":"object","description":"Session-level insights for live video calls","properties":{"started_at":{"type":"string","format":"date-time","nullable":true},"ended_at":{"type":"string","format":"date-time","nullable":true},"duration":{"type":"integer","nullable":true,"description":"Call duration in seconds (inferred from started_at and ended_at)"},"total_participant_minutes":{"type":"number","nullable":true},"total_unique_participants":{"type":"integer","nullable":true},"participants_insights":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/ParticipantInsight"}}}},"ParticipantInsight":{"type":"object","properties":{"participant_id":{"type":"string"},"display_name":{"type":"string","nullable":true},"role":{"type":"string","nullable":true},"browser":{"type":"string","nullable":true},"os":{"type":"string","nullable":true},"device":{"type":"string","nullable":true},"device_type":{"type":"string","nullable":true},"user_agent":{"type":"string","nullable":true},"joined_at":{"type":"string","format":"date-time","nullable":true},"left_at":{"type":"string","format":"date-time","nullable":true}}},"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}},"responses":{"Unauthorized":{"description":"Invalid or missing API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"API access not enabled or insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/recordings/{uuid}":{"patch":{"operationId":"updateRecording","summary":"Update a recording","description":"Updates a recording's title, summary, or description. Admin only.","tags":["Recordings"],"parameters":[{"$ref":"#/components/parameters/RecordingUUID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"recording":{"type":"object","properties":{"title":{"type":"string","description":"The recording title"},"summary":{"type":"string","nullable":true,"description":"A short summary"},"description":{"type":"string","nullable":true,"description":"A detailed description"}}}}}}}},"responses":{"200":{"description":"Updated recording","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Recording"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```