The weekly brief

Every Monday our lead detective C. T. Lucky files one week of competitor movement. The brief endpoints hand you that filing a week at a time: which weeks are on file and how much moved in each, then one week in full. Who moved, how much, in which category and at what priority, and who did not move at all. The app's Brief page reads these two endpoints and nothing else. One week, one file.

What a week is

A week runs Monday to Sunday and is named by its Monday as YYYY-MM-DD. Days are counted in UTC, so a change detected at 23:59 on Sunday in London belongs to that week and one detected a minute later belongs to the next.

Only completed weeks are served. The week in progress is not on file until it has finished, because the pack reads every competitor once a week and an unfinished week would read as empty most days. The most recently completed week is the latest one and the one the app opens on.

A change is in a week when it finished landing there. On merged entries that is lastDetectedAt, the same field the changes feed windows on, so a week here holds exactly what GET /v1/changes?since=<Monday>&until=<next Monday> lists.

Every week on file

GET /v1/brief/weeks

Every week from the latest completed one back to the first week with a detected change, newest first. Quiet weeks are present with zero counts. A reader must be able to see that a week was quiet, so no week is skipped.

curl "$CT_API/brief/weeks" \
  -H "Authorization: Bearer $CT_TOKEN"

{
  "latestWeekStart": "2026-08-31",
  "weeks": [
    {
      "weekStart": "2026-08-31",
      "high": 12,
      "medium": 21,
      "low": 14,
      "total": 47,
      "filing": false
    },
    { "weekStart": "2026-08-24", "high": 0, "medium": 9, "low": 0, "total": 9, "filing": false },
    { "weekStart": "2026-08-17", "high": 0, "medium": 0, "low": 0, "total": 0, "filing": false }
  ]
}

Counts are merged entries, one per update however many pages it touched. See Merged entries for what that means.

One week in full

GET /v1/brief/weeks/{weekStart}

The week's summary. weekStart is a Monday from the list above.

curl "$CT_API/brief/weeks/2026-08-31" \
  -H "Authorization: Bearer $CT_TOKEN"

{
  "weekStart": "2026-08-31",
  "weekEnd": "2026-09-06",
  "isLatest": true,
  "filing": false,
  "tracked": 30,
  "totals": { "high": 12, "medium": 21, "low": 14, "total": 47 },
  "byCategory": { "pricing_changes": 6, "product_changes": 19, "messaging_changes": 22 },
  "movers": [
    {
      "competitorId": "01HF...",
      "name": "TeamSense",
      "displayName": null,
      "normalizedUrl": "https://teamsense.com",
      "faviconUrl": "https://assets.competitortracker.io/favicons/01HF....png",
      "competitorKind": "company",
      "paused": false,
      "high": 5,
      "medium": 4,
      "low": 3,
      "total": 12,
      "cells": [
        { "category": "product_changes", "priority": "high", "count": 3 },
        { "category": "messaging_changes", "priority": "high", "count": 2 }
      ]
    }
  ],
  "quiet": [
    {
      "competitorId": "01HG...",
      "name": "Calamari",
      "displayName": null,
      "normalizedUrl": "https://calamari.io",
      "faviconUrl": null,
      "competitorKind": "company",
      "paused": false
    }
  ]
}

• totals and byCategory — the week's counts by priority and by category.
• movers — one row per competitor with at least one entry, most high-priority first, then by total, then by name. Each carries its own high, medium, low and total, plus cells: the same counts split by category and priority. Narrow the week to one category by summing the matching cells; there is no request for that, the numbers are already in hand.
• quiet — every competitor on file with nothing in the week, in name order. Paused competitors appear here too. Pausing stops the reading, not the file.
• tracked — movers plus quiet.
• isLatest — true for the most recently completed week.

The movers example is trimmed to one competitor.

A week's detail for one competitor is the per-competitor feed with since and until set to the week's bounds. The app loads it when a row is opened, not before.

Still filing

filing is true on both endpoints while at least one competitor's changes for the week have been detected but not yet merged into entries. We merge one competitor at a time once its reading has settled, so a week can spend a while in this state after the Sunday reading. While it does, that competitor's counts are per-page changes rather than merged entries and will come down once its entries are filed. Competitors already filed keep their merged counts. A competitor is never called quiet while its changes are still filing. Notes on the desk, not yet in the folder.

Only the two most recent weeks can be filing. Older weeks whose changes were never filed as entries, typically the weeks from before we started filing for that competitor, are still counted and listed from their per-page changes, without the flag.

Filters

Both endpoints take labelId, repeated or comma-separated, to cover only competitors carrying any of the given labels. Totals, movers, the quiet list and tracked all follow the filter, so a labelled view agrees with itself.

Errors

• 400 ValidationError — weekStart is not a Monday as YYYY-MM-DD, or a labelId is malformed.
• 404 BriefWeekNotAvailable — the week has not finished yet. Ask for the Monday of the current week or any earlier one.