Files API

Files endpoints exposed by the Devotel CPaaS API Base path: /api/v1/files Endpoint count: 5

title: “Errors worth branching on” description: “Per-endpoint failure templates matching the envelope — what actually fires, what to retry, what to surface to the operator.”

Errors worth branching on

These five failures cover the upload create + download (POST /api/v1/files, GET /api/v1/files//download), hammered by attachment pickers across the dashboard. Each block below is a full { error, meta } envelope as the API returns it, and the matrix at the bottom answers retry vs surface for the same five classes. For the platform-wide decision table these branches plug into, see the error handling guide.

401 — Unauthorized

  {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "The API key is invalid, expired, or lacks the required scope.",
      "status": 401
    },
    "meta": {
      "request_id": "req_filesa1",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 401 on this page is the bearer key failing before the route ran — it never means the resource is wrong. Rotate the key or re-mint the scoped token; retrying the same request changes nothing.

403 — Forbidden

  {
    "error": {
      "code": "FORBIDDEN",
      "message": "The key is valid but does not have the scope this operation requires.",
      "status": 403
    },
    "meta": {
      "request_id": "req_filesa1f",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 403 means the key authenticated but the operation is gated by scope — check the key’s scopes on the developer page; a 403 is never a data-not-found shape.

422 — Schema

  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "The request failed input validation.",
      "status": 422,
      "details": { "field": "content_type", "value": "application/x-msdownload", "expected": "one of the allow-listed MIME types (image/*, application/pdf, text/csv)" }
    },
    "meta": {
      "request_id": "req_filesb2",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 422 means the payload did not match the request schema — branch on error.details.field and resend with an allow-listed MIME type on the upload instead of blind-retrying the same body.

429 — Rate

  {
    "error": {
      "code": "RATE_LIMITED",
      "message": "Too many requests in the current window.",
      "status": 429,
      "details": { "retry_after": 12 }
    },
    "meta": {
      "request_id": "req_filesc3",
      "timestamp": "2026-09-03T12:00:00Z",
      "docs_url": "https://docs.orbit.devotel.io/errors/RATE_LIMITED"
    }
  }

The Retry-After header and error.details.retry_after are both set on every 429 — resend the SAME request after the lower of the two.

402 — Feature gate

  {
    "error": {
      "code": "FILE_SCAN_QUARANTINED",
      "message": "This upload is temporarily quarantined by the content scanner.",
      "status": 402,
      "details": { "scan_id": "scan_0192", "scan_eta_seconds": 7 }
    },
    "meta": {
      "request_id": "req_filesd4",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

Poll the scan status and retry the download once scan_status flips to clean. The full recovery walk — the scan state machine, polling bounds, and how to escalate a wrong verdict — is on FILE_SCAN_QUARANTINED recovery.

60-second retry matrix

Class	Meaning	Branch response
401 `UNAUTHORIZED`	the bearer key itself fails	Surface. Rotate the key or re-mint the scoped token; do not retry the same request.
403 `FORBIDDEN`	the key lacks this operation’s scope	Surface. Fix the key’s scope set; a retry with the same key never heals it.
422 `VALIDATION_ERROR`	the payload does not match the schema	Fix, then resend intentionally. Branch on `error.details.field`; a blind retry repeats the same 422.
429 `RATE_LIMITED`	the window quota is exhausted	Retry after `error.details.retry_after` (or the `Retry-After` header) with the same request body.
`FILE_SCAN_QUARANTINED` (402 feature gate)	page-specific gating	Branch on `error.code`. Poll the scan status and retry the download once scan_status flips to clean.

List files

GET /api/v1/files

Lists uploaded files for the tenant with cursor-based pagination. Each row carries a fresh 1-hour signed read URL.

string

Opaque cursor for the next page (from previous response meta.pagination.cursor)

any

Number of items per page (default 25). Values above the page-size cap are silently clamped; negative, fractional, or unparseable values fall back to the default. Never 422s.

string (enum: true|false)

Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.

cURL

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

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/files', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/files", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/files", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/files')
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) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/files');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": [
    {
      "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
      "url": "https://example.com",
      "filename": "string",
      "content_type": "string",
      "size": 0,
      "uploaded_at": "1970-01-01T00:00:00.000Z"
    }
  ],
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z",
    "pagination": {
      "cursor": "string",
      "has_more": false,
      "total": 0
    }
  }
}

Get a file by ID

GET /api/v1/files/{id}

Returns metadata + a fresh 1-hour signed read URL for a single file. Responds 404 when the file ID does not exist in the tenant namespace.

string

required

Resource identifier

string (enum: true|false)

cURL

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

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/files/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/files/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/files/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/files/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3')
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) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/files/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {
    "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
    "url": "https://example.com",
    "filename": "string",
    "content_type": "string",
    "size": 0,
    "uploaded_at": "1970-01-01T00:00:00.000Z"
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Presign a file URL

GET /api/v1/files/{id}/presign

Mints a fresh S3-style presigned read URL for an existing object with a caller-controlled lifetime. Pass ttl_ms (60000..604800000 / 1 minute..7 days); omit for the conservative 1-hour default. Responds 404 when the file ID does not exist in the tenant namespace.

string

required

Resource identifier

integer

Signed-URL lifetime in milliseconds (clamped to a 60000 floor / 604800000 ceiling). Omit for the 1-hour default.

string (enum: true|false)

cURL

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

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/files/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/presign', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/files/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/presign", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/files/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/presign", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/files/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/presign')
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) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/files/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/presign');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {
    "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
    "url": "https://example.com",
    "filename": "string",
    "content_type": "string",
    "size": 0,
    "expires_at": "1970-01-01T00:00:00.000Z",
    "ttl_ms": 0
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Upload a file

POST /api/v1/files/upload

Uploads a single file (multipart/form-data, field name file) to the tenant media bucket and returns a signed read URL. The signed URL defaults to a 1-hour TTL; pass ttl_ms to pin a longer-lived URL (capped at 7 days, the GCS V4-signing maximum). Mime type must be in the server allow-list; oversized uploads return 413.

integer

Signed-URL lifetime in milliseconds (1..604800000 / 7 days). Omit for the conservative 1-hour default.

string

Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the Idempotency-Replay: true response header.

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/files/upload" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/files/upload', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/files/upload", headers=headers, json={})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/files/upload", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

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']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$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'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

{
  "data": {
    "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
    "url": "https://example.com",
    "filename": "string",
    "content_type": "string",
    "size": 0,
    "uploaded_at": "1970-01-01T00:00:00.000Z"
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "status": 0,
    "details": {}
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z",
    "docs_url": "https://example.com"
  }
}

Delete a file

DELETE /api/v1/files/{id}

Deletes a file from the tenant media bucket. Returns 204 on success and 404 when the file ID does not exist in the tenant namespace.

string

required

Resource identifier

string (enum: true|false)

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/files/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/files/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.delete("https://api.orbit.devotel.io/api/v1/files/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", headers=headers, json={})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("DELETE", "https://api.orbit.devotel.io/api/v1/files/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/files/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3')
req = Net::HTTP::Delete.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/files/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

Response: 204 No Content

API Reference

All Endpoints

Files API

Files API

title: “Errors worth branching on” description: “Per-endpoint failure templates matching the envelope — what actually fires, what to retry, what to surface to the operator.”

Errors worth branching on

401 — Unauthorized

403 — Forbidden

422 — Schema

429 — Rate

402 — Feature gate

60-second retry matrix

List files

Get a file by ID

Presign a file URL

Upload a file

Delete a file

​Files API

​title: “Errors worth branching on” description: “Per-endpoint failure templates matching the envelope — what actually fires, what to retry, what to surface to the operator.”

​Errors worth branching on

​401 — Unauthorized

​403 — Forbidden

​422 — Schema

​429 — Rate

​402 — Feature gate

​60-second retry matrix

​List files

​Get a file by ID

​Presign a file URL

​Upload a file

​Delete a file

Files API

title: “Errors worth branching on” description: “Per-endpoint failure templates matching the envelope — what actually fires, what to retry, what to surface to the operator.”

Errors worth branching on

401 — Unauthorized

403 — Forbidden

422 — Schema

429 — Rate

402 — Feature gate

60-second retry matrix

List files

Get a file by ID

Presign a file URL

Upload a file

Delete a file