MP4EDocs
Open Studio

REST API Reference

Programmatic access to MP4E video processing and metadata management

Overview#

The MP4E REST API allows you to programmatically upload videos, manage metadata, trigger AI processing, and integrate MP4E into your own applications.

Base URL
https://api.mp4e.com
Format
JSON
Rate Limits
API requests are limited to 100 requests per minute for free tier accounts. Pro accounts have higher limits. See response headers for current usage.

Authentication#

All API requests require authentication using an API key passed in the request header.

Request Header
curl -X GET "https://api.mp4e.com/api/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

You can generate API keys in the Studio Settings.

HeaderValue
AuthorizationBearer YOUR_API_KEY
Content-Typeapplication/json

Videos#

Endpoints for managing video files and projects.

GET/api/videos

List all videos in your account

Response
{
  "videos": [
    {
      "id": "video_abc123",
      "name": "Product Demo",
      "status": "processed",
      "duration": 120.5,
      "thumbnail": "https://cdn.mp4e.com/thumbs/video_abc123.jpg",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T12:45:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "pageSize": 20
}
GET/api/videos/:id

Get details for a specific video

Parameters
id(path)- Video ID
Response
{
  "id": "video_abc123",
  "name": "Product Demo",
  "status": "processed",
  "duration": 120.5,
  "width": 1920,
  "height": 1080,
  "fps": 30,
  "fileSize": 52428800,
  "streamUrl": "https://cdn.mp4e.com/stream/video_abc123.mp4",
  "thumbnail": "https://cdn.mp4e.com/thumbs/video_abc123.jpg",
  "metadata": { ... },
  "createdAt": "2024-01-15T10:30:00Z"
}
POST/api/videos/upload

Upload a new video file

Parameters
file(form)- Video file (MP4, MOV, WebM)
name(form)- Display name (optional)
autoProcess(form)- Auto-start AI processing (default: false)
Example
curl -X POST "https://api.mp4e.com/api/videos/upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@product_demo.mp4" \
  -F "name=Product Demo" \
  -F "autoProcess=true"
Response
{
  "id": "video_abc123",
  "name": "Product Demo",
  "status": "uploading",
  "uploadProgress": 0
}
DELETE/api/videos/:id

Delete a video and all associated data

Parameters
id(path)- Video ID
Response
{ "success": true }

Metadata#

Endpoints for reading and writing video metadata.

GET/api/videos/:id/metadata

Get the full metadata for a video

Parameters
id(path)- Video ID
version(query)- Specific version number (optional)
Response
{
  "schemaVersion": "2.0",
  "videoDetails": {
    "totalFrames": 3615,
    "fps": 30,
    "width": 1920,
    "height": 1080
  },
  "objects": { ... },
  "layers": [
    { "id": "layer_main", "name": "Main", "overlays": [ ... ] }
  ],
  "variables": [ ... ],
  "rules": [ ... ]
}
PATCH/api/videos/:id/metadata

Update video metadata (partial update)

Parameters
id(path)- Video ID
Request Body
{
  "layers": [
    {
      "id": "layer_main",
      "name": "Main",
      "overlays": [
        {
          "id": "overlay_new",
          "name": "New CTA Button",
          "position": { "x": 0.9, "y": 0.1 },
          "plugin": { "type": "core:button", "config": { "text": "Shop Now" } }
        }
      ]
    }
  ]
}
Response
{
  "success": true,
  "version": 15,
  "updatedAt": "2024-01-15T14:30:00Z"
}
GET/api/videos/:id/export

Export video with embedded metadata

Parameters
id(path)- Video ID
format(query)- Export format: mp4e (default), json
Response
{
  "downloadUrl": "https://cdn.mp4e.com/exports/video_abc123_mp4e.mp4",
  "expiresAt": "2024-01-16T14:30:00Z",
  "fileSize": 54321000
}
GET/api/videos/:id/versions

Get metadata version history

Parameters
id(path)- Video ID
Response
{
  "versions": [
    { "version": 15, "createdAt": "2024-01-15T14:30:00Z", "description": "Added CTA overlay" },
    { "version": 14, "createdAt": "2024-01-15T12:00:00Z", "description": "Updated variables" },
    { "version": 13, "createdAt": "2024-01-15T10:30:00Z", "description": "Initial processing" }
  ],
  "currentVersion": 15
}

Objects#

Endpoints for managing tracked objects within videos.

GET/api/videos/:id/objects

List all tracked objects in a video

Parameters
id(path)- Video ID
Response
{
  "objects": [
    {
      "id": "obj_001",
      "label": "person",
      "userLabel": "Host",
      "confidence": 0.95,
      "firstFrame": 0,
      "lastFrame": 450,
      "frameCount": 451
    },
    {
      "id": "obj_002",
      "label": "laptop",
      "userLabel": null,
      "confidence": 0.89,
      "firstFrame": 120,
      "lastFrame": 380,
      "frameCount": 261
    }
  ]
}
PATCH/api/videos/:id/objects/:objectId

Update object properties

Parameters
id(path)- Video ID
objectId(path)- Object ID
Request Body
{
  "userLabel": "MacBook Pro M3",
  "customData": {
    "price": 1999,
    "sku": "MBP-M3-14",
    "category": "electronics"
  }it
}
Response
{
  "success": true,
  "object": {
    "id": "obj_002",
    "label": "laptop",
    "userLabel": "MacBook Pro M3",
    "customData": { ... }
  }
}
DELETE/api/videos/:id/objects/:objectId

Remove an object from tracking

Parameters
id(path)- Video ID
objectId(path)- Object ID
Response
{ "success": true }
POST/api/videos/:id/objects/surface

Create a planar surface tracking object (for billboards, screens, etc.)

Request Body
{
  "name": "TV Screen",
  "frame": 100,
  "corners": [
    { "x": 0.2, "y": 0.3 },
    { "x": 0.8, "y": 0.3 },
    { "x": 0.8, "y": 0.7 },
    { "x": 0.2, "y": 0.7 }
  ]
}
Response
{
  "success": true,
  "objectId": "surface_001",
  "trackedFrames": 250
}

Processing#

Endpoints for AI-powered video analysis and object detection.

POST/api/videos/:id/process

Start AI object detection and tracking

Parameters
id(path)- Video ID
Request Body
{
  "fps": 5,
  "confidence": 0.25,
  "labels": ["person", "product", "car"],
  "enableClip": true
}
Response
{
  "jobId": "job_xyz789",
  "status": "queued",
  "estimatedTime": 120
}
GET/api/videos/:id/process/status

Check processing job status

Parameters
id(path)- Video ID
Response
{
  "status": "processing",
  "progress": 65,
  "currentFrame": 1950,
  "totalFrames": 3000,
  "objectsDetected": 12,
  "eta": 45
}
POST/api/videos/:id/process/cancel

Cancel an in-progress processing job

Parameters
id(path)- Video ID
Response
{
  "success": true,
  "status": "cancelled"
}

Error Handling#

The API uses standard HTTP status codes and returns detailed error information.

StatusMeaning
200Success
201Created
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API key
403Forbidden - Insufficient permissions
404Not Found - Resource doesn't exist
409Conflict - Version mismatch
429Too Many Requests - Rate limit exceeded
500Internal Server Error
Error Response Format
{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "The 'fps' parameter must be between 1 and 30",
    "field": "fps",
    "details": {
      "min": 1,
      "max": 30,
      "provided": 60
    }
  }
}
Rate Limit Headers
Check these headers to monitor your API usage:
  • X-RateLimit-Limit - Requests allowed per window
  • X-RateLimit-Remaining - Requests remaining
  • X-RateLimit-Reset - Unix timestamp when limit resets
Previous
Export & Deploy
Next
TypeScript Types