> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage uploaded files with the Media Library

> Browse every file uploaded across your workspace, mint fresh share links on demand, and delete assets you no longer need — from Settings → Media, plus the matching Files API calls.

# Media Library

Files uploaded anywhere in your workspace — images dropped into an
[email Builder block](/guides/email-visual-builder), WhatsApp/RCS and MMS
attachments from a message composer, recorded greetings, uploaded
[email attachments](/guides/email-attachments), LOA documents from number
porting — land in one tenant-owned storage namespace. The Media Library is the
console for that namespace: browse what you have, mint a fresh link to serve
it again, and remove what you no longer need.

<Note>
  Access requires an **owner**, **admin**, or **developer** role — the page
  itself is gated to those roles, matching the role gate the server applies
  to upload and delete.
</Note>

## 1. What the Media Library is for

Every upload surface in Orbit writes to the same tenant media bucket: the
visual email Builder's image blocks, message-composer attachments
(WhatsApp, RCS, MMS, email), voicemail greetings, and porting documents.
Until now the only way to touch those files was at upload time — nothing
listed them afterward. The Media Library closes that loop. Use it to:

* Find the file ID of an asset before you reference it over the API.
* Re-serve an asset whose link expired — more on expiry below.
* Remove assets after a campaign ends or a template is retired.

## 2. Where the console lives

Open **Settings → Media** in the dashboard. The page is gated to owner,
admin, and developer roles; other roles see the settings navigation without
a Media entry.

## 3. Browse and search the file table

The console lists every uploaded file with its name, MIME type, size, and
upload timestamp (rendered in your timezone). Use the filter field above the
table to narrow by **file name or MIME type** — the two identifiers people
recall when hunting a file. The filter narrows the pages already loaded;
if the result set is empty, load more pages with the **Load more** button at
the bottom and the filter widens with it.

## 4. Re-serve an asset: presigned URLs and expiry

Every file is stored privately. It is readable only through a **presigned
(signed) read URL** — a time-limited link signed by the platform. Signed
URLs expire, which is the point: a stale link stops working instead of
leaking the asset forever.

* **Default lifetime: 1 hour.** Upload responses and list rows mint a
  1-hour link unless a longer lifetime was requested at upload.
* **Maximum lifetime: 7 days.** An explicit `ttl_ms` on upload or presign
  can stretch the link to the signing ceiling (7 days).
* **The console re-mints on click.** The copy-link (clipboard) and open
  (new tab) actions on each row call the presign endpoint and hand you a
  link that starts its lifetime fresh at that moment.

When a recipient reports a broken image in a month-old email template, the
cause is almost always a link that outlived its signed window — re-mint and
update the template, and consider a longer `ttl_ms` on the next upload.

## 5. Delete files safely

The delete action opens a confirmation dialog before anything happens. The
dialog warns that deletion is permanent and that **anything still linking
to the file breaks** — draft email templates whose image blocks reference
the file, saved message composers, and recording references.

There is no usage check: the platform does not block deletion of a
referenced file, because the references inside draft templates are yours to
manage. Search your templates for the file's signed URL or file ID before
confirming.

## 6. Worked examples over the API

Three console operations map to three endpoints on `https://api.orbit.devotel.io`.
List and presign are readable with a `files:read` API key; delete requires
`files:write`. The full upload + schema detail lives in the
[Files API reference](/api-reference/files).

### List files

```bash cURL theme={null}
curl -X GET "https://api.orbit.devotel.io/api/v1/files?limit=25" \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

The response is page-based: pass the returned `meta.pagination.cursor` back
as `cursor` to fetch the next page. Each row carries a fresh 1-hour signed
URL, an `id` of the form `file_*`, and the upload metadata.

### Mint a presigned URL

```bash cURL theme={null}
curl -X GET "https://api.orbit.devotel.io/api/v1/files/file_x3k9/presign?ttl_ms=86400000" \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

`ttl_ms` is optional and clamped between 1 minute and 7 days; omit it for
the 1-hour default. The response adds two fields to the usual metadata —
`expires_at`, the UTC timestamp at which the link dies, and `ttl_ms`, the
effective lifetime after clamping — so you know exactly how long the link
you hand to someone is good for. A 404 means the file ID is not in your
tenant namespace.

### Delete a file

```bash cURL theme={null}
curl -X DELETE "https://api.orbit.devotel.io/api/v1/files/file_x3k9" \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

Returns **204 No Content** on success; 404 if the ID never existed. Delete
is audited.

## See also

* [Files API](/api-reference/files) — upload endpoint, MIME allow-list, and
  full schema.
* [Build an email template visually](/guides/email-visual-builder) — image
  blocks upload through this storage.
* [Email attachments](/guides/email-attachments) — reference uploaded files
  by URL when sending.
* [Video Room Embed Demo](/guides/developer-video-embed-demo) — another
  developer-console surface alongside the Media Library.