Heatmap API

All endpoints require authentication and heatmap tool permissions.

Get Heatmap Data

GET /api/heatmap

Query parameters:

Parameter	Type	Description
view	string	squad (default) or service
company_ids	string	Comma-separated company IDs to filter
service_ids	string	Comma-separated service IDs to filter
status	string	Filter cells by status
assigned_dm	string	Filter by assigned DM user ID
tier	string	Filter by client tier
blank_only	boolean	Return only companies with unassessed cells

Response:

{
  "companies": [{ "id": "...", "name": "...", "tier": "...", "health_score": 85, "dm_name": "..." }],
  "services": [{ "id": "...", "name": "...", "category": "Development", "position": 1 }],
  "cells": [{ "id": "...", "company_id": "...", "service_id": "...", "status": "active", "source": "manual", "notes": "...", "estimated_value": null }],
  "service_stats": []
}

When view=service, service_stats includes per-service counts (active, opportunity, unassessed, etc.).

Get Heatmap Stats

GET /api/heatmap/stats

Returns summary statistics scoped to the current user’s access level.

{
  "total_cells": 900,
  "assessed_cells": 150,
  "unassessed_cells": 750,
  "by_status": { "active": 50, "past": 30, "opportunity": 40, "proposed": 20, "not_relevant": 10 },
  "total_opportunity_value": 125000
}

Get Single Cell

GET /api/heatmap/cells/:companyId/:serviceId

Returns the cell data and up to 10 history events. Returns { cell: null, blank: true } if no cell exists.

Upsert Cell

PATCH /api/heatmap/cells/:companyId/:serviceId

Creates or updates a cell. Requires heatmap.update permission.

Body:

{
  "status": "opportunity",
  "notes": "Client expressed interest in Q2",
  "estimated_value": 25000
}

Valid statuses: active, past, opportunity, proposed, not_relevant.

Delete Cell (Reset to Blank)

DELETE /api/heatmap/cells/:companyId/:serviceId

Removes the cell, resetting it to unassessed. Only the cell creator or head/executive can delete.

Log Action from Cell

POST /api/heatmap/cells/:companyId/:serviceId/action

Creates a task linked to the heatmap cell.

Body:

{
  "title": "Explore Klaviyo with Acme Corp",
  "assigned_to_user_id": "user-123",
  "due_date": "2026-04-15",
  "description": "Follow up on email marketing opportunity"
}