---
title: "Recording links"
description: "Open, list and turn off recording links over the API, so a bot or help desk can ask someone without Faylee for a screen recording."
canonical: https://faylee.app/docs/api/recording-links
---

# Recording links

A recording link lets someone without Faylee, such as a customer, record their screen in the browser and send it to your workspace. The API opens and closes these links, so a support bot or a script can ask for a recording as part of a ticket. For how the person on the other end records, see [Recording links](https://faylee.app/docs/support/recording-links.md).

What comes in through a link is filed under the member who opened it, in the folder the link names. It is a `video` recording with `reporter_name` and `reporter_email` set from what the sender typed.

## The recording link object

| Field | Type | Notes |
| --- | --- | --- |
| `id` | integer | |
| `title` | string | Shown to the person recording |
| `message` | string or null | Shown to the person recording |
| `external_ref` | string or null | Your reference for the link, such as a ticket URL or id |
| `url` | string | The address to send. Uses the workspace's own link domain when it has a verified one |
| `expires_at` | string or null | ISO 8601. `null` means the link never expires |
| `created_at` | string | ISO 8601 |
| `blocked_reason` | string or null | Why the link no longer accepts recordings, or `null` while it does |

`blocked_reason` is set when the link has expired, was turned off, or the member who opened it has left the workspace. It is a sentence you can show to a person, for example `This link has expired. Ask whoever sent it for a new one.`

## Open a link

`POST /recording_links` with a `recording_link` object.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `title` | string | yes | Up to 120 characters |
| `message` | string | no | Instructions for the person recording |
| `external_ref` | string | no | The ticket or conversation the link is for. It comes back in the `recording_link.completed` webhook |
| `expires_in_days` | integer | no | `1`, `7` or `30`. Any other value, or none, means the link never expires |
| `folder_id` | integer | no | Where recordings sent through the link are filed. A folder from [`GET /folders`](https://faylee.app/docs/api/uploading#choose-a-folder) |

```bash
curl -X POST https://app.faylee.app/api/v1/recording_links \
  -H "Authorization: Bearer $FAYLEE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recording_link": {
      "title": "Show us the export problem",
      "message": "Open the report, click Export, and narrate what you expected.",
      "external_ref": "https://acme.zendesk.com/agent/tickets/4821",
      "expires_in_days": 7
    }
  }'
```

`201` returns the link:

```json
{
  "id": 77,
  "title": "Show us the export problem",
  "message": "Open the report, click Export, and narrate what you expected.",
  "external_ref": "https://acme.zendesk.com/agent/tickets/4821",
  "expires_at": "2026-10-08T09:12:44.000Z",
  "created_at": "2026-10-01T09:12:44.000Z",
  "url": "https://app.faylee.app/record/3mQ8xYfL2vNc7RtA9kWpZs4e",
  "blocked_reason": null
}
```

Send `url` to the person you want a recording from. A missing title, or a folder from another workspace, gets `422`. Opening a link is written to the workspace's audit log.

## List open links

`GET /recording_links` returns the workspace's links that have not been turned off, newest first, up to 100:

```json
{
  "recording_links": [
    {
      "id": 77,
      "title": "Show us the export problem",
      "message": "Open the report, click Export, and narrate what you expected.",
      "external_ref": "https://acme.zendesk.com/agent/tickets/4821",
      "expires_at": "2026-10-08T09:12:44.000Z",
      "created_at": "2026-10-01T09:12:44.000Z",
      "url": "https://app.faylee.app/record/3mQ8xYfL2vNc7RtA9kWpZs4e",
      "blocked_reason": null
    }
  ]
}
```

Expired links stay in the list with `blocked_reason` set until you turn them off.

## Turn a link off

`DELETE /recording_links/:id` stops the link from accepting recordings and returns `204`. Recordings already sent through it stay in the workspace. Turning a link off is written to the audit log.

```bash
curl -X DELETE https://app.faylee.app/api/v1/recording_links/77 \
  -H "Authorization: Bearer $FAYLEE_TOKEN"
```

Anyone who opens the link afterwards is told it no longer accepts recordings.

## Know when a recording comes in

Subscribe a [webhook endpoint](https://faylee.app/docs/api/webhooks.md) to `recording_link.completed`. Faylee sends it when someone finishes sending a recording through a link. Its `data.recording` has `source` set to `recording_link` and a `recording_link` object with the link's `id`, `title` and `external_ref`, so you can match the recording to the ticket that asked for it.

:::note
`recording_link.completed` is sent as soon as the upload completes, and the recording may still be `processing` if the sender blurred parts of the video. `recording.ready` follows when it can be watched.
:::