> ## 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.

# Files API

> Upload, list, and delete files used by messages, agents, knowledge bases, and other surfaces. 25 MB upload cap.

# Files API

Generic file storage for everything that needs an attachment — MMS images, WhatsApp media, agent-side documents, message templates, campaign assets. Files live in Cloud Storage; URLs are signed and time-limited.

**Base path:** `/api/v1/files`

**Authentication:** API key (`X-API-Key`) or session JWT.

**Upload limits:** 25 MB per file (multipart form data).

| Method   | Path                         | Purpose                             |
| -------- | ---------------------------- | ----------------------------------- |
| `POST`   | `/api/v1/files/upload`       | Upload a file (multipart)           |
| `GET`    | `/api/v1/files/`             | List files                          |
| `GET`    | `/api/v1/files/{id}`         | Get file metadata + signed URL      |
| `GET`    | `/api/v1/files/{id}/presign` | Mint a fresh presigned download URL |
| `DELETE` | `/api/v1/files/{id}`         | Delete a file                       |

## Example — upload an image for an MMS

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/files/upload \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -F "file=@./promo.jpg" \
  -F "purpose=mms_attachment"
```

The response includes the file ID and a signed URL; pass the file ID to `POST /api/v1/messages/sms` (with `media_url` set to the signed URL) to send an MMS.

## Presigned download URLs

The signed URL returned on upload (and from `GET /api/v1/files/{id}`) is short-lived. When you need a fresh download link — or one with a different lifetime — call `GET /api/v1/files/{id}/presign` to mint a new S3-style presigned read URL for an existing object.

Use the optional `ttl_ms` query parameter to control how long the URL stays valid:

| Parameter | Type         | Description                                                                                                                                |
| --------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `ttl_ms`  | integer (ms) | Signed-URL lifetime in milliseconds. Omit for the 1-hour default. Clamped to a 1-minute floor (`60000`) and a 7-day ceiling (`604800000`). |

```bash theme={null}
# Mint a download URL that stays valid for 15 minutes (900000 ms)
curl https://api.orbit.devotel.io/api/v1/files/file_abc123/presign?ttl_ms=900000 \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

The response returns the presigned `url` along with `expires_at` (ISO 8601 UTC) and the effective `ttl_ms` after clamping. A request for a file ID that does not exist in your tenant namespace responds `404`.

## See also

* [Messaging API → MMS](/api-reference/endpoints/messaging) — attach a file to an outbound message