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

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"

import { Devotel } from '@devotel-orbit/node';
import { readFileSync } from 'node:fs';

const orbit = new Devotel({ apiKey: process.env.ORBIT_API_KEY });

const upload = await orbit.files.upload({
  filename: 'promo.jpg',
  content: readFileSync('./promo.jpg'),
  content_type: 'image/jpeg',
});

console.log('file id:', upload.data.id);        // file_abc123
console.log('signed URL:', upload.data.url);    // 1-hour signed read URL

# The Python SDK doesn't wrap /files yet — use the request escape-hatch
# or any http client (source-only scope: /sdks#python-core-scope-not-full-parity).
import json
import urllib.request

boundary = "python-files-upload"
payload = [
    f"--{boundary}",
    'Content-Disposition: form-data; name="file"; filename="promo.jpg"',
    "Content-Type: image/jpeg",
    "",
]
with open("./promo.jpg", "rb") as f:
    body = (
        "\r\n".join(payload).encode()
        + b"\r\n"
        + f.read()
        + f"\r\n--{boundary}--\r\n".encode()
    )

req = urllib.request.Request(
    "https://api.orbit.devotel.io/api/v1/files/upload",
    data=body,
    method="POST",
    headers={
        "X-API-Key": "dv_live_sk_your_key_here",
        "Content-Type": f"multipart/form-data; boundary={boundary}",
    },
)
with urllib.request.urlopen(req) as resp:
    upload = json.loads(resp.read())

print("file id:", upload["data"]["id"])        # file_abc123
print("signed URL:", upload["data"]["url"])    # 1-hour signed read URL

The upload response carries the file ID and a signed URL:

{
  "data": {
    "id": "file_abc123",
    "filename": "promo.jpg",
    "content_type": "image/jpeg",
    "size": 48213,
    "uploaded_at": "2026-08-25T14:03:11Z",
    "url": "https://storage.googleapis.com/devotel-media/…"
  }
}

Pass the file ID to POST /api/v1/messages/sms (or serve the signed URL as the attachment) to send an MMS — the end-to-end send is in Attach the file to an MMS below.

Browse and clean up files

List, fetch, and delete round out the round trip — the Node SDK wraps all three as typed methods:

// Cursor-paginated list — each row carries a fresh signed URL.
const page = await orbit.files.list({ limit: 50 });
for (const f of page.data) console.log(f.id, f.filename, f.size_bytes);

// Metadata + a fresh signed URL for one file.
const file = await orbit.files.get('file_abc123');

// Remove it (also deletes the underlying object).
await orbit.files.delete('file_abc123');

Over REST the same three calls are GET /api/v1/files/, GET /api/v1/files/{id}, and DELETE /api/v1/files/{id} — the endpoint table above carries the full shapes.

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`).

# 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 route sits one level below the typed files surface — hit it
// through the SDK's low-level request helper.
const presign = await orbit.request(
  'GET',
  '/files/file_abc123/presign?ttl_ms=900000',
);
console.log(presign.data.url);         // presigned read URL
console.log(presign.data.expires_at);  // ISO 8601 UTC expiry
console.log(presign.data.ttl_ms);      // effective ttl after clamping

# Same escape-hatch from the Python SDK.
presign = client.request(
    "GET",
    "/files/file_abc123/presign",
    params={"ttl_ms": 900_000},
)
print(presign["data"]["url"])         # presigned read URL
print(presign["data"]["expires_at"])  # ISO 8601 UTC expiry
print(presign["data"]["ttl_ms"])      # effective ttl after clamping

The response:

{
  "data": {
    "url": "https://storage.googleapis.com/devotel-media/…",
    "expires_at": "2026-08-25T14:18:11Z",
    "ttl_ms": 900000
  }
}

A request for a file ID that does not exist in your tenant namespace responds 404; a ttl_ms outside the 1-minute-to-7-day band is clamped, not rejected.

Attach the file to an MMS

Uploading only stores the asset — sending it as an MMS is a second call that passes the returned signed URL as media_url:

upload=$(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")

url=$(echo "$upload" | jq -r '.data.url')

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\",
    \"body\": \"This weekend only — show this image for 20% off.\",
    \"media_url\": \"$url\"
  }"

const upload = await orbit.files.upload({
  filename: 'promo.jpg',
  content: readFileSync('./promo.jpg'),
  content_type: 'image/jpeg',
});

// The SMS endpoint auto-upgrades the send to MMS when media_url is set.
// media_url must resolve to a publicly fetchable HTTPS URL — the signed
// URL from the upload response qualifies.
await orbit.messages.sendSms({
  to: '+14155552671',
  body: 'This weekend only — show this image for 20% off.',
  media_url: upload.data.url,
});

upload = json.loads(urllib.request.urlopen(upload_request).read())

send = client.request(
    "POST",
    "/messages/sms",
    json_body={
        "to": "+14155552671",
        "body": "This weekend only — show this image for 20% off.",
        "media_url": upload["data"]["url"],
    },
)
print("message id:", send["data"]["id"])

Passing media_url turns the SMS into an MMS with the attachment inline — the send is rejected before dispatch if the URL fails the HTTPS fetch or the media-type check, so the upload’s signed read URL (which resolves over Google’s storage domain) is the reliable shape. Full MMS semantics (multi-attachment media_urls, the NANP coverage gate, media policy) live on the MMS channel page.

API Reference

All Endpoints

Files API: upload, list, and delete media attachments

Files API

Example — upload an image for an MMS

Browse and clean up files

Presigned download URLs

Attach the file to an MMS

See also

​Files API

​Example — upload an image for an MMS

​Browse and clean up files

​Presigned download URLs

​Attach the file to an MMS

​See also

Files API

Example — upload an image for an MMS

Browse and clean up files

Presigned download URLs

Attach the file to an MMS

See also