Quickstart

Prerequisites

A MediaMagic workspace and API key
curl, Python, or Node.js installed
A media file to upload (video, audio, or document)

Step 1: Generate an upload URL

First, generate a presigned URL for uploading your file:

curl -X POST https://api.northell.io/nhl/prod/mediamagic-verify-integrations/api/uploads/url \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "campaign-video.mp4",
    "contentType": "video/mp4"
  }'

import requests

API_BASE = "https://api.northell.io/nhl/prod/mediamagic-verify-integrations"

response = requests.post(
    f"{API_BASE}/api/uploads/url",
    headers={"X-API-Key": "your-api-key-here"},
    json={
        "filename": "campaign-video.mp4",
        "contentType": "video/mp4",
    },
)

result = response.json()
print(f"Upload URL: {result['uploadUrl']}")
print(f"Blob path: {result['blobPath']}")

const fetch = require("node-fetch");

const API_BASE = "https://api.northell.io/nhl/prod/mediamagic-verify-integrations";

const response = await fetch(`${API_BASE}/api/uploads/url`, {
  method: "POST",
  headers: {
    "X-API-Key": "your-api-key-here",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    filename: "campaign-video.mp4",
    contentType: "video/mp4"
  })
});

const result = await response.json();
console.log("Upload URL:", result.uploadUrl);
console.log("Blob path:", result.blobPath);

Response:

{
  "uploadUrl": "https://<account>.blob.core.windows.net/assets/<path>?<sas>",
  "blobPath": "660e8400-e29b-41d4-a716-446655440000/campaign-video.mp4",
  "expiresAt": "2026-06-03T13:00:00Z"
}

The presigned URL expires after one hour. Request it shortly before you upload, then PUT the file straight to Azure Blob Storage.

Step 2: Upload your file

Use the presigned URL to upload your file directly to Azure Blob Storage:

curl -X PUT "https://<account>.blob.core.windows.net/assets/<path>?<sas>" \
  -H "x-ms-blob-type: BlockBlob" \
  --data-binary @campaign-video.mp4

upload_url = result["uploadUrl"]

with open("campaign-video.mp4", "rb") as f:
    requests.put(
        upload_url,
        headers={"x-ms-blob-type": "BlockBlob"},
        data=f,
    )

const fs = require("fs");

const uploadUrl = result.uploadUrl;
const fileData = fs.readFileSync("campaign-video.mp4");

await fetch(uploadUrl, {
  method: "PUT",
  headers: {
    "x-ms-blob-type": "BlockBlob",
    "Content-Length": fileData.length
  },
  body: fileData
});

Step 3: Create a submission

Now create a submission with your uploaded asset. sidekickIds is required — at least one sidekick must run. Fetch the IDs available to your workspace from List available sidekicks.

curl -X POST https://api.northell.io/nhl/prod/mediamagic-verify-integrations/api/submissions \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "assets": [
      { "blobPath": "660e8400-e29b-41d4-a716-446655440000/campaign-video.mp4" }
    ],
    "sidekickIds": ["<sidekick-id>"]
  }'

response = requests.post(
    f"{API_BASE}/api/submissions",
    headers={"X-API-Key": "your-api-key-here"},
    json={
        "assets": [
            {"blobPath": result["blobPath"]}
        ],
        "sidekickIds": ["<sidekick-id>"],
    },
)

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

const response = await fetch(`${API_BASE}/api/submissions`, {
  method: "POST",
  headers: {
    "X-API-Key": "your-api-key-here",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    assets: [
      { blobPath: result.blobPath }
    ],
    sidekickIds: ["<sidekick-id>"]
  })
});

const submission = await response.json();
console.log("Submission ID:", submission.submissionId);

Asset objects only accept blobPath (and an optional previousSubmissionId for versioning). Do not send filename or contentType here — those come from the upload step.

Response (201 Created):

{
  "submissionId": "550e8400-e29b-41d4-a716-446655440000",
  "workflowId": "asset-admission-trigger-550e8400-...",
  "ablyChannel": "submission:550e8400-...",
  "status": "queued",
  "assets": [
    { "assetId": "a1b2", "versionGroupId": "g1", "versionNumber": 1 }
  ]
}

A new submission starts as queued: its assets are accepted and waiting for a free review slot. Processing begins as slots free up — usually within seconds.

Step 4: Check the status

Poll the submission endpoint to see when processing completes. Note there is no /status suffix — you read the status from the submission resource itself:

curl -H "X-API-Key: your-api-key-here" \
  https://api.northell.io/nhl/prod/mediamagic-verify-integrations/api/submissions/550e8400-e29b-41d4-a716-446655440000

submission_id = submission["submissionId"]

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

status = response.json()
print(f"Status: {status['status']} ({status['progressPercent']}%)")
for asset in status["assets"]:
    print(f"  {asset['assetId']}: issues={asset['issueCount']}")

const submissionId = submission.submissionId;

const response = await fetch(
  `${API_BASE}/api/submissions/${submissionId}`,
  { headers: { "X-API-Key": "your-api-key-here" } }
);

const status = await response.json();
console.log(`Status: ${status.status} (${status.progressPercent}%)`);
status.assets.forEach(asset => {
  console.log(`  ${asset.assetId}: issues=${asset.issueCount}`);
});

Status response (200 OK):

{
  "submissionId": "550e8400-...",
  "workflowId": null,
  "workspaceId": "660e8400-...",
  "status": "processing",
  "progressPercent": 40,
  "createdAt": "2026-06-03T12:00:00Z",
  "startedAt": "2026-06-03T12:00:05Z",
  "completedAt": null,
  "errorMessage": null,
  "assets": [
    {
      "assetId": "a1b2",
      "versionGroupId": "g1",
      "versionNumber": 1,
      "issueCount": null,
      "errorMessage": null,
      "errorType": null,
      "isRetryable": false,
      "retryCount": 0,
      "workflowId": "asset-review-...",
      "startedAt": "2026-06-03T12:00:05Z",
      "completedAt": null
    }
  ],
  "isRetryable": false
}

status is one of uploading, submitted, queued, processing, complete, partial, or failed. Keep polling until it reaches a terminal complete, partial, or failed state, then stop (queued is non-terminal — it means the submission’s assets are waiting for a free review slot). For production workloads, prefer webhooks over tight polling.workflowId is an internal processing reference and is often null — don’t key any logic off it. Use submissionId for tracking, and assets[].processingStatus for per-asset progress.

Step 5: Get the results

Once the asset reaches complete, retrieve its result by fetching the asset directly (no /results suffix):

curl -H "X-API-Key: your-api-key-here" \
  https://api.northell.io/nhl/prod/mediamagic-verify-integrations/api/submissions/550e8400-.../assets/a1b2

asset_id = status["assets"][0]["assetId"]

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

asset = response.json()
print(f"Status: {asset['status']}, issues: {asset['issueCount']}")
for issue in asset["issues"]:
    print(f"  [{issue['severity']}] {issue['ruleCode']}: {issue['summary']}")

const assetId = status.assets[0].assetId;

const response = await fetch(
  `${API_BASE}/api/submissions/${submissionId}/assets/${assetId}`,
  { headers: { "X-API-Key": "your-api-key-here" } }
);

const asset = await response.json();
console.log(`Status: ${asset.status}, issues: ${asset.issueCount}`);
asset.issues.forEach(issue => {
  console.log(`  [${issue.severity}] ${issue.ruleCode}: ${issue.summary}`);
});

Asset result (200 OK):

{
  "assetId": "a1b2",
  "submissionId": "550e8400-...",
  "filename": "campaign-video.mp4",
  "mimeType": "video/mp4",
  "status": "complete",
  "issueCount": 2,
  "versionNumber": 1,
  "versionGroupId": "g1",
  "startedAt": "2026-06-03T12:00:05Z",
  "completedAt": "2026-06-03T12:04:12Z",
  "issues": [
    {
      "id": "i1",
      "referenceNumber": 1,
      "ruleCode": "CAP_8.4",
      "summary": "Unsubstantiated pricing claim",
      "severity": "MAJOR",
      "status": "OPEN"
    }
  ]
}

What’s next?

Read about Core Concepts to understand the data model
Check out File Upload Guide for handling large files
Learn about Webhooks for real-time updates
See Error Handling for common issues

Getting Started

Core Concepts

Guides

Reference

API Endpoints

Prerequisites

Step 1: Generate an upload URL

Step 2: Upload your file

Step 3: Create a submission

Step 4: Check the status

Step 5: Get the results

What’s next?

​Prerequisites

​Step 1: Generate an upload URL

​Step 2: Upload your file

​Step 3: Create a submission

​Step 4: Check the status

​Step 5: Get the results

​What’s next?

Prerequisites

Step 1: Generate an upload URL

Step 2: Upload your file

Step 3: Create a submission

Step 4: Check the status

Step 5: Get the results

What’s next?