Skip to main content
The media management endpoints provide comprehensive control over device media events, including listing, uploading, downloading, and deleting media files.

​
Get device paths

GET /api/gallery/:device/paths

Get the file system paths for uploading media to a device

​
Path parameters

​
device
string
required
Device identifier

​
Response

​
success
boolean
required
Indicates if the request was successful
​
paths
object
required
File system paths for the device
​
paths.incoming
string
Path where new files should be uploaded
​
paths.thumbnails
string
Path where thumbnail files should be uploaded

​
Example request

curl "http://localhost:8001/api/gallery/device123/paths" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response: 
{
  "success": true,
  "paths": {
    "incoming": "/data/gallery/device123/incoming",
    "thumbnails": "/data/gallery/device123/thumbnails"
  }
}

​
List media events

GET /api/gallery/:device/events

List all media events for a device with optional type filtering

​
Path parameters

​
device
string
required
Device identifier

​
Query parameters

​
media_type
string
Filter by media type: image, video, audio, document, other
​
limit
number
default:50
Maximum number of events to return
​
offset
number
default:0
Number of events to skip for pagination

​
Response

Returns an array of event objects.
​
id
string
required
Unique event identifier
​
name
string
required
Event filename
​
media_type
string
required
Media type classification
​
size
number
File size in bytes
​
has_thumbnail
boolean
Whether a thumbnail is available
​
created
string
ISO 8601 timestamp of event creation

​
Example request

curl "http://localhost:8001/api/gallery/device123/events?media_type=video" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Upload media event

POST /api/gallery/:device/upload

Upload a media event with optional thumbnail

​
Path parameters

​
device
string
required
Device identifier

​
Request body (multipart/form-data)

​
name
string
required
Event filename
​
event
file
required
Media file to upload
​
thumbnail
file
Optional thumbnail image
​
media_type
string
Media type: image, video, audio, document, other
​
has_thumbnail
boolean
default:false
Indicates if a thumbnail is included
​
metadata
string
JSON string of additional metadata

​
Response

​
success
boolean
required
Indicates if upload was successful
​
eventId
string
ID of the created event

​
Example request

curl -X POST "http://localhost:8001/api/gallery/device123/upload" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "name=capture.jpg" \
  -F "event=@/path/to/capture.jpg" \
  -F "media_type=image" \
  -F "metadata={\"timestamp\":\"2024-03-20T10:00:00Z\"}"
Response: 
{
  "success": true,
  "eventId": "evt_abc123"
}

​
Get upload URL

GET /api/gallery/:device/upload-url

Get pre-signed URLs for uploading media files

​
Path parameters

​
device
string
required
Device identifier

​
Query parameters

​
filename
string
required
Name of the file to upload
​
thumbnail
boolean
default:false
Whether to also get a thumbnail upload URL

​
Response

​
success
boolean
required
Indicates if the request was successful
​
upload_url
string
required
Pre-signed URL for uploading the media file
​
thumbnail_upload_url
string
Pre-signed URL for uploading the thumbnail (if requested)

​
Example request

curl "http://localhost:8001/api/gallery/device123/upload-url?filename=video.mp4&thumbnail=true" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response: 
{
  "success": true,
  "upload_url": "https://storage.example.com/upload/abc123",
  "thumbnail_upload_url": "https://storage.example.com/upload/thumb_abc123"
}
Upload to the pre-signed URL: 
curl -X PUT "https://storage.example.com/upload/abc123" \
  --upload-file /path/to/video.mp4

​
Get media statistics

GET /api/gallery/:device/stats

Get media statistics with type breakdown

​
Path parameters

​
device
string
required
Device identifier

​
Response

​
total_events
number
required
Total number of media events
​
total_size
number
required
Total size of all media in bytes
​
by_type
object
required
Breakdown of events and size by media type

​
Example request

curl "http://localhost:8001/api/gallery/device123/stats" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response: 
{
  "total_events": 150,
  "total_size": 2147483648,
  "by_type": {
    "image": {
      "count": 100,
      "size": 524288000
    },
    "video": {
      "count": 45,
      "size": 1610612736
    },
    "audio": {
      "count": 5,
      "size": 12582912
    }
  }
}

​
Delete media event

DELETE /api/gallery/:device/events/:eventId

Delete a specific media event

​
Path parameters

​
device
string
required
Device identifier
​
eventId
string
required
Event identifier to delete

​
Response

​
success
boolean
required
Indicates if deletion was successful

​
Example request

curl -X DELETE "http://localhost:8001/api/gallery/device123/events/evt_abc123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response: 
{
  "success": true
}

​
Pull specific event

POST /api/gallery/:device/pull/:eventId

Pull a specific event from the device

​
Path parameters

​
device
string
required
Device identifier
​
eventId
string
required
Event identifier to pull from device

​
Response

​
success
boolean
required
Indicates if the pull was successful
​
eventId
string
ID of the pulled event

​
Example request

curl -X POST "http://localhost:8001/api/gallery/device123/pull/evt_abc123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response: 
{
  "success": true,
  "eventId": "evt_abc123"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us