Backend API Structure

This document provides an overview of the GP3MixMedia TrailMix API architecture for developers and administrators.

API Overview

Framework: Next.js 15.5.9 (App Router)
Pattern: RESTful HTTP endpoints
Base Path: All endpoints versioned under /api/v1
Authentication: NextAuth 4.24.11 with Google Workspace SSO
Total Endpoints: 223

Database Architecture

Technology Stack

Database: MySQL 8+
ORM: Prisma 7.2.0
Total Tables: 129 (82 core + 47 archive)

Key Database Categories

Category	Tables	Description
Campaign Management	15	Campaigns, stations, settings
Buy Lines & Reconciliation	4	Ad buys, assignments, reconciliation
Deduplication	10	Groups, candidates, resolutions
Email & Alerts	4	Sends, events, configurations
Ingestion Feeds	5	Feed configs, runs, watermarks
Archive Tables	47	Soft-delete storage

Main API Endpoint Categories

1. Campaigns

Base Path: /api/v1/campaigns

Method	Endpoint	Purpose
GET	`/api/v1/campaigns`	List all campaigns
POST	`/api/v1/campaigns`	Create new campaign
GET	`/api/v1/campaigns/{id}`	Get campaign details
POST	`/api/v1/campaigns/{id}`	Update campaign
POST	`/api/v1/campaigns/{id}/clone`	Clone campaign

2. Matrix Data

Base Path: /api/v1/matrix

Method	Endpoint	Purpose
GET	`/api/v1/matrix`	Get matrix rows with filters
POST	`/api/v1/matrix/batch-update`	Update multiple rows
GET	`/api/v1/matrix/export`	Export matrix data

3. Deduplication

Base Path: /api/v1/dedupe

Method	Endpoint	Purpose
GET	`/api/v1/dedupe/groups`	List dedupe groups
POST	`/api/v1/dedupe/groups/{id}/resolve`	Resolve group
POST	`/api/v1/dedupe/rows/combine`	Combine rows
POST	`/api/v1/dedupe/rows/combine/undo`	Undo combination

4. Email

Base Path: /api/v1/email

Method	Endpoint	Purpose
POST	`/api/v1/email/send`	Send email
POST	`/api/v1/email/resend`	Resend failed email
GET	`/api/v1/email/logs`	Get send history

5. Ingestion

Base Path: /api/v1/ingestion

Method	Endpoint	Purpose
GET	`/api/v1/ingestion/status`	Get ingestion status
GET	`/api/v1/ingestion/control`	Get control status
POST	`/api/v1/ingestion/control`	Pause/resume/rate-limit

6. Notifications

Base Path: /api/v1/notifications

Method	Endpoint	Purpose
GET	`/api/v1/notifications`	Get user notifications
POST	`/api/v1/notifications/{id}/read`	Mark as read
POST	`/api/v1/notifications/read-all`	Mark all as read

7. Push Notifications

Base Path: /api/v1/push

Method	Endpoint	Purpose
POST	`/api/v1/push/subscribe`	Subscribe to push
DELETE	`/api/v1/push/subscribe`	Unsubscribe
POST	`/api/v1/push/send`	Send push notification

8. Admin

Base Path: /api/v1/admin

Method	Endpoint	Purpose
GET	`/api/v1/admin/users`	List all users
GET	`/api/v1/admin/archives/{table}`	List archived records
POST	`/api/v1/admin/archives/{table}/{id}/restore`	Restore record

Common Patterns

Pagination

Cursor-based:

GET /api/v1/campaigns?cursor=123&limit=20

Offset-based:

GET /api/v1/dedupe/groups?page=1&take=50

Filtering

Common query parameters:

campaignId - Filter by campaign
status - Filter by status
weekMode - Time period filtering (booked, projected, futureOnly)
startDate, endDate - Date ranges

Error Handling

HTTP status codes:

400 - Validation error
401 - Authentication required
403 - Permission denied
404 - Not found
500 - Server error

Response format:

{ "error": "Error message" }

Security Features

Authentication

NextAuth session-based authentication
Google Workspace SSO
JWT tokens for API routes

Rate Limiting

Configurable per tier
Unauthenticated: 100 req/min
Authenticated: 500 req/min
Upstash Redis-based

Idempotency

Request deduplication with idempotency keys
Prevents duplicate processing

Data Types & Enums

Campaign Status

active, paused, completed

Medium Types

tv, radio, digital, ott, ctv, mail, phones, other

Dedupe Status

open, resolved

Notification Types

info, success, warning, error, alert

Health & Monitoring

Endpoint	Purpose
`/api/v1/ping`	Basic health check
`/api/v1/health`	Detailed health check
`/api/v1/observability/metrics`	Application metrics
`/api/v1/circuit-breakers`	Circuit breaker status

Additional Resources

API Types - TypeScript type definitions
Quick Reference - Developer quick start

Last Updated: March 2026

Was this helpful? If you have feedback or questions, please contact your administrator.