Admin Guide

Step-by-step walkthrough of everything you can do in the MediaKit admin panel.

1. Dashboard Overview

After login, you land on the dashboard showing:

• Stats cards — Total assets, plays today/week/month
• Active jobs — Videos currently being transcoded
• Recent uploads — Last 10 uploaded files with status
• Top videos — Most-played videos this month
• Quick actions — Links to Videos, Images, Webhooks, AI, API Keys, Settings

2. Upload Your First Video

There are two ways to upload:

Option A: Via Admin Panel (System → Files)

1. Click Files in the sidebar (under System)
2. Drag & drop a video file or click to browse
3. The file uploads directly to R2/S3 via presigned URL
4. After upload, a transcode job starts automatically
5. Go to Videos in the sidebar to see progress

Option B: Via API (for testing)

Use curl to test the upload flow programmatically:

curl -X POST https://mediakitapi.gritcms.com/api/mediakit/uploads/presign \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "demo.mp4",
    "content_type": "video/mp4",
    "file_size": 52428800,
    "asset_type": "video",
    "title": "My First Video"
  }'

{
  "data": {
    "upload_url": "https://r2.cloudflarestorage.com/...",
    "asset_id": 1,
    "key": "uploads/abc123/demo.mp4"
  }
}

curl -X PUT "PRESIGNED_URL_FROM_STEP_1" \
  -H "Content-Type: video/mp4" \
  --data-binary @demo.mp4

curl -X POST https://mediakitapi.gritcms.com/api/mediakit/uploads/complete \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_id": 1,
    "key": "uploads/abc123/demo.mp4"
  }'

After completing, the video enters the transcode queue automatically.

3. Video Management

Go to Videos in the sidebar:

• List view — All videos with title, status (pending/processing/ready/failed), duration, resolution
• Click a video → Opens detail view with:
  • Video player preview (plays HLS stream once ready)
  • Transcode progress bar (updates in real-time)
  • Qualities tab — Shows 360p, 480p, 720p, 1080p renditions
  • Chapters tab — View or generate chapters with AI
  • AI tab — Trigger summary, chapters, moderation analysis
  • Embed tab — Copy embed code (script tag, iframe, HLS URL)
• Retranscode — If a video failed, click "Retranscode" to retry

4. Image Management

Go to Images in the sidebar to view all image assets. Images uploaded through the upload pipeline are automatically cataloged.

To serve transformed images, use the image transform API:

https://mediakitapi.gritcms.com/api/img/{asset_id}?w=800&h=600&fit=cover&format=webp&q=80

Parameters: w (width), h (height), fit (cover/contain/fill), format (webp/jpeg/png/avif), q (quality 1-100), blur (blur radius).

5. Analytics

Click Analytics in the sidebar to see:

• Plays today / this week / this month
• Top 10 most-played videos with bar chart
• Date range filtering (7d / 30d / 90d)

Analytics events are automatically tracked when videos are played via the React SDK or embed script. You can also manually ingest events:

# This endpoint is public (no auth required)
curl -X POST https://mediakitapi.gritcms.com/api/analytics/events \
  -H "Content-Type: application/json" \
  -d '{
    "asset_id": 1,
    "event_type": "play",
    "session_id": "test-session-123"
  }'

6. Webhooks

Go to Webhooks in the sidebar:

1. Click Create
2. Enter your webhook URL (e.g., https://your-app.com/webhooks/mediakit)
3. Select events to subscribe to: asset.ready, asset.failed, video.transcoded, etc.
4. Save — MediaKit will deliver events with HMAC-SHA256 signatures

Test with a webhook catcher like webhook.site:

{
  "event": "video.transcoded",
  "timestamp": "2026-03-29T12:00:00Z",
  "data": {
    "asset_id": 1,
    "title": "My Video",
    "status": "ready",
    "hls_url": "https://r2.../videos/1/master.m3u8",
    "qualities": ["360p", "480p", "720p", "1080p"]
  }
}

7. AI Analysis

Go to AI Analysis in the sidebar, or trigger from a video detail page:

• Summary — AI generates a text summary of the video content
• Chapters — Auto-generates timestamped chapters for the video timeline
• Moderation — Checks for NSFW content, violence, etc.
• Q&A — Ask questions about a video (streaming response)

curl -X POST https://mediakitapi.gritcms.com/api/ai/videos/1/analyse \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "summary"}'

8. API Keys

Go to API Keys in the sidebar:

1. Click Create
2. Name your key (e.g., "Production App")
3. Select scopes: read:assets, write:assets, read:analytics
4. The full API key is shown once — copy it immediately
5. Use it in the X-API-Key header for programmatic access

curl https://mediakitapi.gritcms.com/api/assets \
  -H "X-API-Key: mk_live_abc123..."

9. Settings

Click Settings in the sidebar:

• Storage tab — Shows health status of Database, Redis, Storage (R2/S3), and FFmpeg
• API Keys tab — Create and manage API keys
• AI tab — View AI gateway configuration and available features

10. System Pages

Under System in the sidebar:

• Jobs — View background job queues (transcode, sprite, webhook delivery). See active, pending, completed, and failed jobs
• Files — File upload manager with drag-and-drop
• Cron — Scheduled tasks (analytics aggregation, cleanup)
• Mail — Email templates and delivery logs
• Security — WAF dashboard, rate limiting, threat detection

11. Health Check

Verify everything is working:

curl https://mediakitapi.gritcms.com/api/health

{
  "status": "ok",
  "checks": {
    "database": { "status": "ok" },
    "redis": { "status": "ok" },
    "storage": { "status": "ok", "driver": "r2" },
    "ffmpeg": { "status": "ok", "version": "6.x" }
  }
}

Testing Checklist