Introduction

Welcome to the MediaMagic API documentation

This documentation covers the MediaMagic API — a public REST API for programmatically submitting media assets for processing and retrieving analysis results.

What is the MediaMagic API?

The MediaMagic API enables you to:

• Upload media files (video, audio, documents) to secure cloud storage
• Submit files for processing and analysis
• Track processing status in real-time via polling or webhooks
• Retrieve detailed results including topics, issues, evidence, and contributors

Getting started

Pick a starting point based on your needs:

• New to the API? Start with Authentication and the Quickstart
• Want to understand concepts? Read Core Concepts
• Building an integration? Follow the Guides
• Looking for specifics? Check API Reference or Reference

Main workflows

Upload and submit

See File Upload Guide and Submit Assets Guide.

Track progress

See Poll Status Guide and Webhook Subscriptions.

Handle errors

See Error Handling Guide and Error Codes Reference.

Authentication

All API requests require an X-API-Key header with a workspace-scoped API key.

curl -H "X-API-Key: your-api-key-here" \
  https://mm-midmarket-integrations-api-preview.azurewebsites.net/api/integrations/submissions

Get your API key from the control plane.

Rate limits

Rate limits are tier-based and resolved per API key. Requests are organized into buckets (uploads, submission reads and writes, webhook reads and writes, and sandbox), each with its own limit determined by your plan. When you exceed a bucket’s limit the API returns 429 Too Many Requests with a Retry-After header telling you how many seconds to wait. If your plan is not authorized for the API at all, requests return 402.

The exact limits depend on your tier — check the control plane or contact support for your workspace’s limits.

See Rate Limiting for the full model and best practices.

Base URL

All API requests are made to:

https://mm-midmarket-integrations-api-preview.azurewebsites.net

Every endpoint lives under /api/integrations/.... To test without incurring processing costs, use a sandbox API key (prefixed sk_test_) against the same base URL. See Sandbox Guide.

API response format

All responses are JSON. Resource responses are returned directly — there is no universal envelope wrapper. For example, creating a submission returns the resource at the top level:

{
  "submissionId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "submitted",
  "assets": [
    { "assetId": "a1b2", "versionGroupId": "g1", "versionNumber": 1 }
  ]
}

Errors come in a few shapes depending on the failure. Most domain errors return a detail message:

{
  "detail": "Submission not found"
}

Request validation failures (422) return a structured envelope:

{
  "error": "validation_error",
  "message": "Request payload is invalid.",
  "fields": [
    { "field": "endpointUrl", "message": "URL must use HTTPS" }
  ]
}

See Error Codes Reference for every status code and envelope.

Support

• Documentation: See the guides and reference sections
• Issues: Check Error Codes
• Contact: Visit support

Examples

Quick reference for common tasks:

Create a submission (Python)

import requests

API_BASE = "https://mm-midmarket-integrations-api-preview.azurewebsites.net"

response = requests.post(
    f"{API_BASE}/api/integrations/submissions",
    headers={"X-API-Key": "your-api-key-here"},
    json={
        "assets": [
            {"blobPath": "660e8400-.../campaign-video.mp4"}
        ]
    },
)

submission = response.json()
print(f"Submission ID: {submission['submissionId']}")

Check status

submission_id = submission["submissionId"]

response = requests.get(
    f"{API_BASE}/api/integrations/submissions/{submission_id}",
    headers={"X-API-Key": "your-api-key-here"},
)

status = response.json()
print(f"Status: {status['status']}")

See the API Reference for all available endpoints.

Next steps

1. Set up authentication
2. Try the quickstart
3. Read core concepts