API Overview

The Mend Media Processing Engine provides a REST API for asynchronous media processing tasks. All jobs are queued and processed by worker processes.

Base URL

http://localhost:8080/api/v1

Authentication

How to Authenticate

Include your API key in one of the following ways:

X-API-Key Header
Authorization Bearer

curl -H "X-API-Key: your_api_key_here" \
  http://localhost:8080/api/v1/jobs/image/resize

Recommended

curl -H "Authorization: Bearer your_api_key_here" \
  http://localhost:8080/api/v1/jobs/image/resize

For detailed authentication setup, see the Authentication Guide.

Response Format

All endpoints return JSON responses.

Success Response 202 Accepted

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "message": "Job queued for processing"
}

Error Response 400/500

{
  "error": "Error message description"
}

API Endpoints

Image Operations Resize, optimize, watermark, and analyze images

Video Operations Generate thumbnails and extract frames

Audio Operations Convert audio between formats

Batch Operations Process multiple jobs as a batch

Job Management Check status and stream updates

Health & Queue Stats Monitor system health and queue status

Job Status Flow

graph LR
    A[Submit Job] --> B[pending]
    B --> C[processing]
    C --> D[completed]
    C --> E[failed]

pending

Job is queued and waiting for a worker

processing

Worker is actively processing the job

completed

Job finished successfully

failed

Job encountered an error

Common Request Parameters

Source and Destination

All job types require source and destination parameters:

Parameter	Type	Required	Description
`source_bucket`	string	✅	S3 bucket containing the source file
`source_key`	string	✅	S3 key (path) to the source file
`dest_bucket`	string	✅	S3 bucket for the output file
`dest_key`	string	✅	S3 key (path) for the output file

Optional Parameters

Parameter	Type	Description
`webhook_url`	string	URL to receive job completion notifications
`webhook_style`	string	`default` or `discord` for webhook format
`request_id`	string	Custom ID for request tracing

Rate Limits

Webhooks

Subscribe to job completion events by providing a webhook_url in your request:

{
  "source_bucket": "my-bucket",
  "source_key": "image.jpg",
  "dest_bucket": "my-bucket",
  "dest_key": "resized.jpg",
  "width": 800,
  "height": 600,
  "webhook_url": "https://your-domain.com/webhook",
  "webhook_style": "default"
}

Learn more in the Webhooks Guide.

Server-Sent Events

Subscribe to real-time job updates via SSE:

curl -N http://localhost:8080/api/v1/jobs/{job_id}/stream

Learn more in the SSE Guide.

Error Codes

Code	Description
200	Success (for GET requests)
202	Accepted (job queued)
400	Bad Request (invalid parameters)
401	Unauthorized (missing/invalid API key)
404	Not Found (job doesn’t exist)
500	Internal Server Error
503	Service Unavailable (dependencies unhealthy)

Public Endpoints

These endpoints do not require authentication:

Health Check

GET /health - Check service health

Metrics

GET /metrics - Prometheus metrics

API Docs

GET /swagger/* - Interactive API documentation

SDK Support

Example with JavaScript:

const response = await fetch('http://localhost:8080/api/v1/jobs/image/resize', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key_here'
  },
  body: JSON.stringify({
    source_bucket: 'my-bucket',
    source_key: 'image.jpg',
    dest_bucket: 'my-bucket',
    dest_key: 'resized.jpg',
    width: 800,
    height: 600
  })
});

const data = await response.json();
console.log('Job ID:', data.job_id);

Next Steps

Try the Quick Start Get hands-on with your first API call

Explore Image Operations Learn about image processing endpoints

Set Up Webhooks Get real-time job notifications