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

Using the SDKs

The Node SDK publishes typed helpers for upload, list, get, and delete. The Python SDK publishes a core-scope client — /files sits outside its wrapped surface, so call it through the request escape hatch or a plain requests call. For Go, Ruby, and PHP the samples below use the plain standard-library HTTP form per the sample-writing policy (Go net/http, Ruby Net::HTTP, PHP curl); the header comments that previously leaked into this page are removed.

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

// Multipart upload over net/http — reading the file into memory keeps the
// sample small enough to show inline; swap in os.File for large assets.
package main

import (
	"bytes"
	"fmt"
	"mime/multipart"
	"net/http"
	"os"
)

func main() {
	var buf bytes.Buffer
	w := multipart.NewWriter(&buf)
	fw, _ := w.CreateFormFile("file", "promo.jpg")
	content, _ := os.ReadFile("./promo.jpg")
	fw.Write(content)
	w.WriteField("purpose", "mms_attachment")
	w.Close()
	req, _ := http.NewRequest(
		"POST",
		"https://api.orbit.devotel.io/api/v1/files/upload",
		&buf,
	)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", w.FormDataContentType())
	resp, _ := http.DefaultClient.Do(req)
	fmt.Println(resp.Status)
}

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/files/upload')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
boundary = 'ruby-files-upload'
req['Content-Type'] = "multipart/form-data; boundary=#{boundary}"
body = []
body << "--#{boundary}\r\n"
body << "Content-Disposition: form-data; name=\"file\"; filename=\"promo.jpg\"\r\n"
body << "Content-Type: image/jpeg\r\n\r\n"
body << File.binread('./promo.jpg')
body << "\r\n--#{boundary}\r\n"
body << "Content-Disposition: form-data; name=\"purpose\"\r\n\r\n"
body << "mms_attachment\r\n"
body << "--#{boundary}--\r\n"
req.body = body.join
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts JSON.parse(res.body)['data']['id']

<?php
$file = new CURLFile('./promo.jpg', 'image/jpeg', 'promo.jpg');
$ch = curl_init('https://api.orbit.devotel.io/api/v1/files/upload');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, [
  'file' => $file,
  'purpose' => 'mms_attachment',
]);
echo curl_exec($ch);

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.

List files

List returns files newest-first, cursor-paginated. The data array carries one row per file (each with a fresh 1-hour signed url), and meta.pagination carries cursor plus has_more for the next page:

curl "https://api.orbit.devotel.io/api/v1/files/?limit=50" \
  -H "X-API-Key: dv_live_sk_your_key_here"

const page = await orbit.files.list({ limit: 50 });
for (const f of page.data.items) console.log(f.id, f.filename, f.size);

// Pass the returned cursor back as `cursor` on the next call while has_more is true.
const { cursor, has_more } = page.pagination;

# /files sits outside the wrapped SDK surface — the request escape-hatch.
page = client.request("GET", "/files", params={"limit": 50})
for f in page["data"]["items"]:
    print(f["id"], f["filename"], f["size"])

# Pass cursor back as a query param while has_more is true.
cursor = page["pagination"]["cursor"]
has_more = page["pagination"]["has_more"]

// Decode the list envelope — items plus the pagination cursor.
req, _ := http.NewRequest("GET",
	"https://api.orbit.devotel.io/api/v1/files/?limit=50", nil)
req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var page struct {
	Data struct {
		Items []struct {
			ID       string `json:"id"`
			Filename string `json:"filename"`
		} `json:"items"`
	} `json:"data"`
	Pagination struct {
		Cursor  string `json:"cursor"`
		HasMore bool   `json:"has_more"`
	} `json:"pagination"`
}
json.NewDecoder(resp.Body).Decode(&page)
for _, f := range page.Data.Items {
	fmt.Println(f.ID, f.Filename)
}
// Pass page.Pagination.Cursor back as ?cursor= while HasMore is true.

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/files/?limit=50')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
page = JSON.parse(res.body)
page['data']['items'].each { |f| puts "#{f['id']} #{f['filename']}" }

# Pass cursor back as ?cursor= while has_more is true.
cursor = page['pagination']['cursor']
has_more = page['pagination']['has_more']

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/files/?limit=50');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
]);
$page = json_decode(curl_exec($ch), true);
foreach ($page['data']['items'] as $f) {
  echo $f['id'], ' ', $f['filename'], "\n";
}

// Pass cursor back as ?cursor= while has_more is true.
$cursor = $page['pagination']['cursor'];
$has_more = $page['pagination']['has_more'];

Each list page looks like:

{
  "data": {
    "items": [
      {
        "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/…"
      }
    ]
  },
  "pagination": {
    "cursor": "eyJvZmZzZXQiOjUwfQ",
    "has_more": true
  }
}

Get a file

Get returns one file’s metadata plus a fresh signed read URL in a single call. The data envelope carries the file’s id, url, filename, content_type, size, and uploaded_at; the url lives for one hour unless you passed a longer ttl_ms at upload time.

curl https://api.orbit.devotel.io/api/v1/files/file_abc123 \
  -H "X-API-Key: dv_live_sk_your_key_here"

const file = await orbit.files.get('file_abc123');
console.log(file.data.id, file.data.url); // url is valid for 1 hour

resp = client.request("GET", "/files/file_abc123")
print(resp["data"]["id"], resp["data"]["url"])  # url is valid for 1 hour

// GET one file — decode the body, not just the status line.
req, _ := http.NewRequest("GET",
	"https://api.orbit.devotel.io/api/v1/files/file_abc123", nil)
req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var got struct {
	Data struct {
		ID  string `json:"id"`
		URL string `json:"url"`
	} `json:"data"`
}
json.NewDecoder(resp.Body).Decode(&got)
fmt.Println(got.Data.ID, got.Data.URL) // url is valid for 1 hour

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/files/file_abc123')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
file = JSON.parse(res.body)
puts file['data']['id'], file['data']['url'] # url is valid for 1 hour

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/files/file_abc123');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
]);
$file = json_decode(curl_exec($ch), true);
echo $file['data']['id'], ' ', $file['data']['url']; // url is valid for 1 hour

A file ID that does not exist in your tenant namespace responds 404.

Delete a file

Delete removes the file row and the underlying storage object. The response is 204 No Content, so there is no response body to read on success — check the status code.

curl -X DELETE https://api.orbit.devotel.io/api/v1/files/file_abc123 \
  -H "X-API-Key: dv_live_sk_your_key_here"

await orbit.files.delete('file_abc123'); // resolves on 204

client.request("DELETE", "/files/file_abc123")  # 204 No Content on success

// Delete — 204 No Content is the success signal.
req, _ := http.NewRequest("DELETE",
	"https://api.orbit.devotel.io/api/v1/files/file_abc123", nil)
req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
fmt.Println(resp.StatusCode) // 204

require 'net/http'

uri = URI('https://api.orbit.devotel.io/api/v1/files/file_abc123')
req = Net::HTTP::Delete.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.code # 204

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/files/file_abc123');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
]);
curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_RESPONSE_CODE); // 204

A file ID that does not exist responds 404; an already-deleted ID does the same. The full per-op request/response shapes are in the file upload endpoint reference.

Presigned download URLs

The signed URL returned on upload (and from GET /api/v1/files/{id}) is short-lived — 1 hour by default. 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. The response declares when the URL dies with expires_at (an ISO 8601 instant): subtract the current time to get the remaining lifetime. 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

// ttl_ms=900000 asks for a 15-minute URL (1-minute floor, 7-day ceiling).
req, _ := http.NewRequest(
	"GET",
	"https://api.orbit.devotel.io/api/v1/files/file_abc123/presign?ttl_ms=900000",
	nil,
)
req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var presign struct {
	Data struct {
		URL       string `json:"url"`
		ExpiresAt string `json:"expires_at"`
	} `json:"data"`
}
json.NewDecoder(resp.Body).Decode(&presign)
// Derive the remaining lifetime from expiry minus now — the server states
// the expiry instant, not a duration.
expiresAt, _ := time.Parse(time.RFC3339, presign.Data.ExpiresAt)
fmt.Println(presign.Data.URL, "expires in", time.Until(expiresAt))

require 'net/http'
require 'json'
require 'time'

# ttl_ms=900000 asks for a 15-minute URL (1-minute floor, 7-day ceiling).
uri = URI('https://api.orbit.devotel.io/api/v1/files/file_abc123/presign?ttl_ms=900000')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
presign = JSON.parse(res.body)
expires_at = Time.iso8601(presign['data']['expires_at'])
# Remaining lifetime is expiry minus now — the server states the expiry
# instant, not a duration.
puts presign['data']['url'], "expires in #{expires_at - Time.now} seconds"

<?php
// ttl_ms=900000 asks for a 15-minute URL (1-minute floor, 7-day ceiling).
$ch = curl_init('https://api.orbit.devotel.io/api/v1/files/file_abc123/presign?ttl_ms=900000');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
]);
$presign = json_decode(curl_exec($ch), true);
$data = $presign['data'];
$expiresAt = new DateTimeImmutable($data['expires_at']);
echo $data['url'];
// Remaining lifetime is the expiry instant minus now ($expiresAt->diff(new
// DateTimeImmutable())) — the server states an expiry instant, not a duration.

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"])

// Upload first, then post the signed URL as media_url — the SMS route
// auto-upgrades to MMS when media_url is present.
uploadReq, _ := http.NewRequest(
	"POST",
	"https://api.orbit.devotel.io/api/v1/files/upload",
	&buf, // the multipart body from the upload example above
)
uploadReq.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
uploadReq.Header.Set("Content-Type", w.FormDataContentType())
uploadResp, _ := http.DefaultClient.Do(uploadReq)
defer uploadResp.Body.Close()

sendReq, _ := http.NewRequest(
	"POST",
	"https://api.orbit.devotel.io/api/v1/messages/sms",
	bytes.NewBuffer([]byte(`{
  "to": "+14155552671",
  "body": "This weekend only — show this image for 20% off.",
  "media_url": "<signed URL from the upload response>"
}`)),
)
sendReq.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
sendReq.Header.Set("Content-Type", "application/json")
http.DefaultClient.Do(sendReq)

require 'net/http'

upload = JSON.parse(upload_res.body) # from the upload example above

uri = URI('https://api.orbit.devotel.io/api/v1/messages/sms')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "to": '+14155552671',
  "body": 'This weekend only — show this image for 20% off.',
  "media_url": upload['data']['url']
}.to_json
Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }

<?php
$upload = json_decode($uploadResponse, true); // from the upload example above

$ch = curl_init('https://api.orbit.devotel.io/api/v1/messages/sms');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'to' => '+14155552671',
  'body' => 'This weekend only — show this image for 20% off.',
  'media_url' => $upload['data']['url'],
]));
echo curl_exec($ch);

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

Using the SDKs

Example — upload an image for an MMS

List files

Get a file

Delete a file

Presigned download URLs

Attach the file to an MMS

See also

​Files API

​Using the SDKs

​Example — upload an image for an MMS

​List files

​Get a file

​Delete a file

​Presigned download URLs

​Attach the file to an MMS

​See also

Files API

Using the SDKs

Example — upload an image for an MMS

List files

Get a file

Delete a file

Presigned download URLs

Attach the file to an MMS

See also