> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mediamagicverify.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/authentication) and the [Quickstart](/quickstart)
* **Want to understand concepts?** Read [Core Concepts](/concepts/submissions)
* **Building an integration?** Follow the [Guides](/guides/file-upload)
* **Looking for specifics?** Check [API Reference](/health-check) or [Reference](/reference/rate-limiting)

## Main workflows

### Upload and submit

```mermaid theme={null}
graph LR
  A[Get upload URL] --> B[Upload file to Azure] --> C[Create submission]
```

See [File Upload Guide](/guides/file-upload) and [Submit Assets Guide](/guides/submit-assets).

### Track progress

```mermaid theme={null}
graph LR
  A[Submission created] --> B{Track}
  B --> C[Poll GET /submissions/id]
  B --> D[Subscribe to webhooks]
```

See [Poll Status Guide](/guides/poll-status) and [Webhook Subscriptions](/guides/webhook-subscriptions).

### Handle errors

```mermaid theme={null}
graph LR
  A[Inspect status code] --> B[Retry 429/500/502 with backoff] --> C[Surface 4xx to caller]
```

See [Error Handling Guide](/guides/error-handling) and [Error Codes Reference](/reference/error-codes).

## Authentication

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

```bash theme={null}
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](/reference/rate-limiting) for the full model and best practices.

## Base URL

All API requests are made to:

```text theme={null}
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](/reference/sandbox).

## 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "detail": "Submission not found"
}
```

Request validation failures (`422`) return a structured envelope:

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

See [Error Codes Reference](/reference/error-codes) for every status code and envelope.

## Support

* **Documentation**: See the guides and reference sections
* **Issues**: Check [Error Codes](/reference/error-codes)
* **Contact**: Visit [support](https://support.mediamagic.app)

## Examples

Quick reference for common tasks:

### Create a submission (Python)

```python theme={null}
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"}
        ],
        "sidekickIds": ["<sidekick-id>"],
    },
)

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

### Check status

```python theme={null}
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](/health-check) for all available endpoints.

## Next steps

1. [Set up authentication](/authentication)
2. [Try the quickstart](/quickstart)
3. [Read core concepts](/concepts/submissions)