API Reference

Complete endpoint documentation for the MAGIC platform API. All authenticated endpoints require a valid session cookie or Bearer token.

Authentication

MAGIC uses session-based authentication. After signing in, your browser receives a secure HTTP-only cookie that is automatically included in all requests. For programmatic access, include the session token as a Bearer token in the Authorization header.

Example header

Authorization: Bearer your_session_token_here
Content-Type: application/json

Base URL: https://magic.marketinc.agency

Projects

GET/api/projectsAuth required

List all projects for the authenticated user. Returns an array of project summaries with ID, name, status, and creation date.

Response

{
  "projects": [
    {
      "id": "proj_abc123",
      "name": "Q4 Campaign Analysis",
      "status": "active",
      "platforms": ["meta", "google"],
      "created_at": "2025-01-15T10:30:00Z"
    }
  ]
}

POST/api/projectsAuth required

Create a new project. Requires a name and at least one platform source. Returns the created project object.

Request body

{
  "name": "Q1 2025 Analysis",
  "platforms": ["meta", "google"],
  "date_range": {
    "start": "2024-10-01",
    "end": "2025-01-31"
  }
}

Response

{
  "id": "proj_def456",
  "name": "Q1 2025 Analysis",
  "status": "active",
  "created_at": "2025-01-20T14:00:00Z"
}

Data

GET/api/data/dashboard/kpisAuth required

Retrieve aggregated KPIs (spend, impressions, clicks, conversions, ROAS) for the specified project and date range.

Response

{
  "kpis": {
    "total_spend": 45200.50,
    "impressions": 2340000,
    "clicks": 89500,
    "conversions": 3420,
    "roas": 4.8,
    "ctr": 3.82,
    "cpc": 0.51
  },
  "period": {
    "start": "2024-12-01",
    "end": "2025-01-15"
  }
}

GET/api/data/dashboard/timeseriesAuth required

Fetch time-series data for charting. Supports daily, weekly, and monthly granularity. Filterable by platform and metric.

Response

{
  "granularity": "daily",
  "series": [
    {
      "date": "2025-01-01",
      "spend": 1200.00,
      "impressions": 85000,
      "clicks": 3200,
      "conversions": 120
    }
  ]
}

GET/api/data/dashboard/platformsAuth required

Get per-platform performance breakdown. Returns spend, ROAS, and key metrics for each connected platform.

Response

{
  "platforms": [
    {
      "platform": "meta",
      "spend": 22000.00,
      "roas": 5.2,
      "conversions": 1840,
      "trend": "up"
    },
    {
      "platform": "google",
      "spend": 18000.00,
      "roas": 4.1,
      "conversions": 1200,
      "trend": "stable"
    }
  ]
}

POST/api/export/generateAuth required

Generate a PDF or CSV export of project data, MMM results, or dashboard snapshots. Returns an export ID for download.

Request body

{
  "project_id": "proj_abc123",
  "format": "pdf",
  "sections": ["kpis", "attribution", "recommendations"],
  "date_range": {
    "start": "2024-10-01",
    "end": "2025-01-15"
  }
}

Response

{
  "export_id": "exp_abc123",
  "status": "generating",
  "format": "pdf",
  "estimated_seconds": 30
}

AI

POST/api/ai-bi/chatAuth required

Send a natural language question to the AI Copilot. Returns an AI-generated response with optional chart data and source references.

Request body

{
  "message": "Which channel has the best ROAS this quarter?",
  "project_id": "proj_abc123",
  "context": {
    "date_range": "last_90_days"
  }
}

Response

{
  "response": "Google Ads leads with 5.2x ROAS, up 18% from last quarter...",
  "charts": [
    {
      "type": "bar",
      "data": { ... }
    }
  ],
  "sources": ["marketing_facts", "platform_daily"]
}

MMM

POST/api/mmm/runAuth required

Launch a Marketing Mix Model run. Triggers both Robyn (frequentist) and Meridian (Bayesian) engines in parallel. Returns a run ID for polling.

Request body

{
  "project_id": "proj_abc123",
  "config": {
    "engines": ["robyn", "meridian"],
    "date_range": {
      "start": "2024-07-01",
      "end": "2025-01-15"
    },
    "target_metric": "conversions"
  }
}

Response

{
  "run_id": "run_xyz789",
  "status": "queued",
  "estimated_duration_seconds": 600,
  "created_at": "2025-01-20T15:00:00Z"
}

GET/api/mmm/status/{runId}Auth required

Poll the status of an MMM run. Returns current progress percentage, stage, and ETA.

Response

{
  "run_id": "run_xyz789",
  "status": "running",
  "progress": 45,
  "stage": "meridian_fitting",
  "eta_seconds": 320,
  "started_at": "2025-01-20T15:00:30Z"
}

GET/api/mmm/results/{runId}Auth required

Retrieve completed MMM results. Includes attribution by channel, model comparisons, confidence intervals, and budget recommendations.

Response

{
  "run_id": "run_xyz789",
  "status": "completed",
  "robyn": {
    "attribution": {
      "meta": 0.38,
      "google": 0.29,
      "tiktok": 0.21,
      "linkedin": 0.12
    },
    "r_squared": 0.91
  },
  "meridian": {
    "attribution": {
      "meta": 0.35,
      "google": 0.31,
      "tiktok": 0.23,
      "linkedin": 0.11
    },
    "r_squared": 0.89
  },
  "recommendations": [ ... ]
}

System

GET/api/statusPublic

Public health check endpoint. Returns the operational status of all MAGIC services. No authentication required.

Response

{
  "services": [
    {
      "name": "API Backend",
      "status": "operational",
      "latency_ms": 45,
      "checked_at": "2025-01-20T15:30:00Z"
    }
  ],
  "overall": "operational"
}

POST/api/feedbackPublic

Submit user feedback (NPS score and/or freeform comment). Used by the in-app feedback widget.

Request body

{
  "trigger": "first_dashboard_view",
  "nps_score": 9,
  "comment": "Great first impression!",
  "page_url": "/dashboard"
}

Response

{
  "status": "received",
  "id": "fb_001"
}