API REFERENCE / FILE DELIVERY
GET /v1/files/{file_id}/content
This is the streaming API: read only the bytes needed for playback, preview, seek, or resume. Pin version_id so the content cannot change halfway through a stream. A normal request streams a full version; Range requests a slice. The API may use a Mac, peer, or permitted cloud copy internally, but this endpoint does not guarantee a direct P2P route.
Request fields
| Location | Field | Type | Required | Description |
|---|---|---|---|---|
| Header | Authorization | string | Yes | Credential scoped to the authorized resource. |
| Path | file_id | string | Yes | Stable Atom file ID. |
| Query | version_id | string | Recommended | Pin bytes to one immutable version. |
| Header | Range | string (byte range) | No | Byte range for preview, seek, or resume. |
| Header | If-Range | string (version tag) | No | Only resume when the version still matches. |
Request example
Example request
GET /v1/files/file_789/content?version_id=ver_012
Authorization: Bearer <scoped token>
Range: bytes=0-65535HTTP status codes
| Status | Meaning |
|---|---|
200 OK | Full file body when no byte range is requested. |
206 Partial Content | Success response shown below. |
400 Bad Request | Invalid version or request syntax. |
401 Unauthorized | Missing, expired, or invalid credential. |
403 Forbidden | Credential is valid but lacks the required scope or role. |
404 Not Found | File or pinned version does not exist or is not visible. |
416 Range Not Satisfiable | Requested bytes fall outside this version. |
429 Too Many Requests | Rate limit reached; honor Retry-After when provided. |
503 Service Unavailable | Service temporarily unavailable; retry safely. |
Response fields
| Field | Type | Example |
|---|---|---|
body | binary stream | File bytes |
Response example
Example response
206 Partial Content
Accept-Ranges: bytes
Content-Range: bytes 0-65535/4194304
Content-Type: application/pdf
ETag: "ver_012"
<binary bytes>How it works
Seek and resumeUse
Range and a version-pinned ETag; If-Range can prevent combining bytes from different versions.AvailabilityIf the source is offline and no authorized copy exists, return an explicit unavailable result rather than inventing a cloud fallback.
TransportExpose delivery route and metered bytes in diagnostics or usage records, not provider credentials or device addresses.
HTTP 206, 416, range validation, cache policy, and media-player behavior require contract and integration tests before release. A separate stream-session endpoint is unnecessary unless native or P2P transport negotiation proves it useful.