​

Manage media quarantines and upload policy in Settings → Media

The Media Library guide covers the day-to-day browse and clean-up loop: list uploads, mint a fresh share link, delete what you no longer need. This guide is the administrative half of the same console — what to do when the content scanner holds a file, and how your tenant’s own intake rules decide which uploads ever reach the scanner.

​

1. Where the page lives

Open Settings → Media in the dashboard. The console is gated to the owner, admin, and developer roles — the same roles the server requires for upload and delete — so those operators see both halves of the surface: the file table from the browse loop, and the quarantine states the scanner assigns to the files in it.

​

2. Two consoles, one storage model

Read these two first; this guide does not repeat them:

• The media asset store — object keys, the content-type gates, the 25 MB ceiling, and why signed URLs are the only egress.
• Manage uploaded files with the Media Library — the browse → re-serve → delete loop on the same page.

What they do not cover is the scanner’s verdict layer. Every upload moves through three states — pending, clean, quarantined — and a download or attachment fetch on a file that is not yet clean returns 402 FILE_SCAN_QUARANTINED. The states, and what each one means, are in Troubleshooting: FILE_SCAN_QUARANTINED. The remaining piece is policy, and it is tenant-owned on purpose: your organization chooses which content types and sizes its intake accepts, so the scanner’s verdict rate is a knob you hold, not a platform mandate imposed on you. The console is where you see the outcome of that policy per file.

​

3. Console map: the four actions on the table

The console is one file table over your tenant namespace with an action per row. Four affordances cover the surface:

• Browse / filter — the search box above the table narrows by file name or MIME type; the table carries every upload with its name, type, size, and upload timestamp. Use it to find the file_* id of an artifact before you reference it from code. (Walkthrough: Media Library guide §3.)
• Copy link — the clipboard button on a row calls the presign endpoint, mints a signed URL that starts its lifetime fresh at that moment, and drops it on your clipboard. This is the documented answer to a dead link — re-mint on click instead of guessing how much of the signed window is left. (Media Library guide §4.)
• Open — the external-link button mints a fresh presigned URL the same way, then opens it in a new tab for a visual check of the asset before you embed it anywhere.
• Delete — the trash button opens a confirmation dialog that warns that deletion is permanent and anything still linking to the file breaks. Check templates and drafts for the file’s URL or id before you confirm. (Media Library guide §5.)

Upload itself is a write that every surface funnels into this table: the visual email Builder’s image blocks, the message composer’s attachment picker, voicemail greeting uploads, and the example below all push the same POST /files/upload. When a human picks the file, use any of those pickers; when code references it, use the API as in the example.

​

4. Worked example: upload a greeting → 7-day URL → send it on an MMS

One file, one pass through the whole pipeline. Upload a campaign greeting once, mint a link that survives the week the template says it needs, and attach it to an outbound MMS send.

1. Upload the file. POST one multipart form with a single file field — ask for the longest lifetime up front, because the URL is about to sit in a saved send request:
   cURL

   curl -X POST "https://api.orbit.devotel.io/api/v1/files/upload?ttl_ms=604800000" \
     -H "X-API-Key: dv_live_sk_your_key_here" \
     -F "file=@greeting.wav;type=audio/wav"
   
   ttl_ms=604800000 is the 7-day signing ceiling. The response carries the file_* id and a signed URL whose ttl_ms field shows the effective lifetime after clamping:
   Result

   {
     "data": {
       "id": "file_g9h2k",
       "url": "https://storage.googleapis.com/orbit-media/…signed…",
       "filename": "greeting.wav",
       "content_type": "audio/wav",
       "size": 312800
     },
     "meta": {}
   }
   
2. Mint (or re-mint) the 7-day URL. After the signed window closes — or whenever you skipped the TTL at upload — call the presign endpoint on the file id; this is exactly what the Copy link and Open actions on the console do behind the scenes:
   cURL

   curl -X GET "https://api.orbit.devotel.io/api/v1/files/file_g9h2k/presign?ttl_ms=604800000" \
     -H "X-API-Key: dv_live_sk_your_key_here"
   
   The envelope answers with a url, expires_at, and the effective ttl_ms, so you know how long the link you store is good for. Clamping is server-side: ask for more than 7 days and you get 7 days.
3. Attach it to the send. There is no separate MMS endpoint — POST /messages/sms upgrades to MMS the moment a media_urls entry points at your freshly minted link:
   cURL

   curl -X POST "https://api.orbit.devotel.io/api/v1/messages/sms" \
     -H "X-API-Key: dv_live_sk_your_key_here" \
     -H "Content-Type: application/json" \
     -d '{
       "to": "+14155552671",
       "from": "+18005551234",
       "body": "Listen to this week's greeting.",
       "media_urls": ["https://storage.googleapis.com/orbit-media/…signed…"]
     }'
   
4. See the resolved asset in the response. The send accepts or rejects the attachment at intake: 202 with the queued message id and the resolved media_urls echoed back. A send whose preflight fetch of that URL returns non-2xx is refused at intake with a 422 media_url validation failed envelope instead of accepting and breaking downstream — a dead signature, a file id outside your tenant, or a non-https link all fail fast at this step, which is the point of working backward from the expires_at you got in step 2. MMS attachments deliver to NANP (+1) recipients; past that, a 422 MMS_NANP_ONLY covers the reach limit — see the media-rich messaging guide for the carrier classes.

​

5. Worked loop: flagged asset → quarantine → re-enable → adjust policy

Use this loop whenever a recipient reports a broken image or attachment, or a download call returns the 402 above.

1. Find the flagged asset. Open Settings → Media and filter the table by the file name from the recipient’s message, or by the file ID your API call returned. The filter narrows by file name or MIME type.
2. Read the quarantine state. Fetch the same row over the API with GET /api/v1/files/{id} and look at its scan fields. pending means the scanner has not answered yet — wait out the ETA and poll again. clean means the scanner passed it and the block was something else. quarantined means the scanner flagged the content itself.
3. Re-enable or remove. A pending file re-enables itself when the scan completes — downloads succeed the moment the row flips to clean, with no re-upload. A quarantined file never heals: replace the artifact with a cleaned version and upload that instead. If the verdict looks wrong on a business-critical file, escalate it with the file ID and the scan ID from the 402 response instead of re-uploading the same bytes.
4. Adjust the policy. When quarantines cluster, they cluster on what your intake admits. Tighten the allow-list to the content types your flows genuinely use, keep size ceilings at the 25 MB per-file ceiling or lower, and restrict which members and endpoints can push uploads. Each of those is yours to set per tenant — the scanner only ever sees what your intake lets through.

​

6. Governance and audit

Quarantine decisions and file deletions are tenant events: uploads and deletes emit audit entries you can review under Compliance > Audit, and the media policy you set sits next to the other tenant compliance evidence. When you assemble a compliance profile for an audit, the scan states and the intake rules are the parts of the media surface worth citing — see Assemble a compliance profile for that workflow.

​

See also

• Manage uploaded files with the Media Library — the browse/list/delete loop on the same console.
• The media asset store — the storage model behind both consoles.
• Troubleshooting: FILE_SCAN_QUARANTINED — the 402 envelope, the scan state machine, and escalation.
• Assemble a compliance profile — where quarantine and policy evidence lands for audit.
• Files API — upload, presign, list, and delete.