{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/rumoro-dev/json-schema/rumoro-dev-attention-item-schema.json",
  "title": "AttentionItem",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/rumoro-dev-attention-api-openapi.yml#/components/schemas/AttentionItem",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The attention item's id (att_...)."
    },
    "kind": {
      "type": "string",
      "enum": [
        "mention.spike",
        "sentiment.negative_spike",
        "keyword.noisy",
        "channel.failing"
      ],
      "description": "mention.spike flags an hour with far more mentions than usual, and sentiment.negative_spike a jump in the negative share over 24 hours. keyword.noisy flags a keyword whose scored matches are mostly noise, and channel.failing a channel whose recent sends all failed."
    },
    "status": {
      "type": "string",
      "enum": [
        "open",
        "resolved",
        "dismissed"
      ],
      "description": "open means the condition is still true. resolved means it is not anymore. dismissed means someone dismissed it, and it will not reopen for the same episode."
    },
    "subject": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "keyword",
            "channel"
          ],
          "description": "Either keyword or channel."
        },
        "id": {
          "type": "string",
          "description": "The keyword's id (kw_...) or the channel's id (dest_...)."
        }
      },
      "required": [
        "type",
        "id"
      ],
      "description": "The keyword or channel the item concerns."
    },
    "title": {
      "type": "string",
      "description": "A one-line summary of what happened."
    },
    "openedAt": {
      "type": "string",
      "description": "First time the condition was seen."
    },
    "resolvedAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "When the condition ended. Null while it lasts."
    },
    "dismissedAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "When someone dismissed it. Null if no one did."
    },
    "data": {
      "anyOf": [
        {
          "$ref": "#/$defs/MentionSpikeEventData"
        },
        {
          "$ref": "#/$defs/NegativeSpikeEventData"
        },
        {
          "$ref": "#/$defs/KeywordNoisyEventData"
        },
        {
          "$ref": "#/$defs/ChannelFailingEventData"
        }
      ],
      "description": "The numbers at the time it opened. This is the same object the account event with the same name sends as `data`."
    }
  },
  "required": [
    "id",
    "kind",
    "status",
    "subject",
    "title",
    "openedAt",
    "resolvedAt",
    "dismissedAt",
    "data"
  ],
  "$defs": {
    "ChannelFailingEventData": {
      "type": "object",
      "properties": {
        "attentionId": {
          "type": "string",
          "description": "Related attention item (att_...). See GET /v1/attention, dismiss with POST /v1/attention/{id}/dismiss."
        },
        "url": {
          "type": "string",
          "description": "The dashboard page to open."
        },
        "channel": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "The channel's id (dest_...)."
            },
            "kind": {
              "type": "string",
              "enum": [
                "slack",
                "email",
                "webhook",
                "telegram"
              ],
              "description": "Type of channel."
            },
            "label": {
              "type": "string",
              "description": "The name you gave the channel."
            }
          },
          "required": [
            "id",
            "kind",
            "label"
          ],
          "description": "The channel that keeps failing."
        },
        "failures": {
          "type": "integer",
          "minimum": 0,
          "description": "Consecutive failed sends in the past 24 hours."
        },
        "lastError": {
          "type": [
            "string",
            "null"
          ],
          "description": "The latest error, as Slack, email, the webhook or Telegram returned it."
        },
        "since": {
          "type": "string",
          "description": "Time of the first of those failures."
        }
      },
      "required": [
        "attentionId",
        "url",
        "channel",
        "failures",
        "lastError",
        "since"
      ]
    },
    "KeywordNoisyEventData": {
      "type": "object",
      "properties": {
        "attentionId": {
          "type": "string",
          "description": "Related attention item (att_...). See GET /v1/attention, dismiss with POST /v1/attention/{id}/dismiss."
        },
        "url": {
          "type": "string",
          "description": "The dashboard page to open."
        },
        "keyword": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "The keyword's id (kw_...)."
            },
            "term": {
              "type": "string",
              "description": "The term being tracked."
            },
            "kind": {
              "type": "string",
              "enum": [
                "brand",
                "competitor",
                "topic"
              ],
              "description": "The keyword's kind, brand, competitor or topic."
            },
            "name": {
              "type": "string",
              "description": "The keyword's display name. It is the term, or \"term (Group)\" when the keyword is not in the default group."
            },
            "groupId": {
              "type": "string",
              "description": "The keyword's group id (grp_...)."
            }
          },
          "required": [
            "id",
            "term",
            "kind",
            "name",
            "groupId"
          ],
          "description": "The keyword this item concerns."
        },
        "windowDays": {
          "type": "integer",
          "minimum": 0,
          "description": "How many days the noise is measured over. If the keyword changed within that time, it starts at the change."
        },
        "scored": {
          "type": "integer",
          "minimum": 0,
          "description": "Matches scored by the classifier during that time."
        },
        "relevant": {
          "type": "integer",
          "minimum": 0,
          "description": "How many of them were relevant."
        },
        "noiseShare": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "The part that scored below 40. Every match is billed, relevant or not."
        }
      },
      "required": [
        "attentionId",
        "url",
        "keyword",
        "windowDays",
        "scored",
        "relevant",
        "noiseShare"
      ]
    },
    "MentionSpikeEventData": {
      "type": "object",
      "properties": {
        "attentionId": {
          "type": "string",
          "description": "Related attention item (att_...). See GET /v1/attention, dismiss with POST /v1/attention/{id}/dismiss."
        },
        "url": {
          "type": "string",
          "description": "The dashboard page to open."
        },
        "keyword": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "The keyword's id (kw_...)."
            },
            "term": {
              "type": "string",
              "description": "The term being tracked."
            },
            "kind": {
              "type": "string",
              "enum": [
                "brand",
                "competitor",
                "topic"
              ],
              "description": "The keyword's kind, brand, competitor or topic."
            },
            "name": {
              "type": "string",
              "description": "The keyword's display name. It is the term, or \"term (Group)\" when the keyword is not in the default group."
            },
            "groupId": {
              "type": "string",
              "description": "The keyword's group id (grp_...)."
            }
          },
          "required": [
            "id",
            "term",
            "kind",
            "name",
            "groupId"
          ],
          "description": "The keyword this item concerns."
        },
        "window": {
          "type": "object",
          "properties": {
            "from": {
              "type": "string",
              "description": "Start time, included."
            },
            "to": {
              "type": "string",
              "description": "End time, not included."
            }
          },
          "required": [
            "from",
            "to"
          ],
          "description": "Match-time range of the counts."
        },
        "matches": {
          "type": "integer",
          "minimum": 0,
          "description": "New matches during the hour, meaning posts that matched within 6 hours of being published. Look-backs and free reviews are not counted."
        },
        "relevant": {
          "type": "integer",
          "minimum": 0,
          "description": "How many of them have been scored relevant so far."
        },
        "baseline": {
          "type": "object",
          "properties": {
            "meanPerHour": {
              "type": "number",
              "minimum": 0,
              "description": "Average new matches per hour during the baseline."
            },
            "stddevPerHour": {
              "type": "number",
              "minimum": 0,
              "description": "The standard deviation of that average."
            },
            "hours": {
              "type": "integer",
              "minimum": 0,
              "description": "How many hours the baseline covers. It is the week before the window, or the time since the keyword was created if that is shorter."
            }
          },
          "required": [
            "meanPerHour",
            "stddevPerHour",
            "hours"
          ],
          "description": "The keyword's normal volume."
        }
      },
      "required": [
        "attentionId",
        "url",
        "keyword",
        "window",
        "matches",
        "relevant",
        "baseline"
      ]
    },
    "NegativeSpikeEventData": {
      "type": "object",
      "properties": {
        "attentionId": {
          "type": "string",
          "description": "Related attention item (att_...). See GET /v1/attention, dismiss with POST /v1/attention/{id}/dismiss."
        },
        "url": {
          "type": "string",
          "description": "The dashboard page to open."
        },
        "keyword": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "The keyword's id (kw_...)."
            },
            "term": {
              "type": "string",
              "description": "The term being tracked."
            },
            "kind": {
              "type": "string",
              "enum": [
                "brand",
                "competitor",
                "topic"
              ],
              "description": "The keyword's kind, brand, competitor or topic."
            },
            "name": {
              "type": "string",
              "description": "The keyword's display name. It is the term, or \"term (Group)\" when the keyword is not in the default group."
            },
            "groupId": {
              "type": "string",
              "description": "The keyword's group id (grp_...)."
            }
          },
          "required": [
            "id",
            "term",
            "kind",
            "name",
            "groupId"
          ],
          "description": "The keyword this item concerns."
        },
        "window": {
          "type": "object",
          "properties": {
            "from": {
              "type": "string",
              "description": "Start time, included."
            },
            "to": {
              "type": "string",
              "description": "End time, not included."
            }
          },
          "required": [
            "from",
            "to"
          ],
          "description": "Match-time range of the counts."
        },
        "negative": {
          "type": "integer",
          "minimum": 0,
          "description": "Relevant matches in the window with negative sentiment."
        },
        "relevant": {
          "type": "integer",
          "minimum": 0,
          "description": "Relevant match count for the window."
        },
        "share": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "negative divided by relevant."
        },
        "baseline": {
          "type": "object",
          "properties": {
            "negative": {
              "type": "integer",
              "minimum": 0,
              "description": "How many relevant matches were negative in the prior week."
            },
            "relevant": {
              "type": "integer",
              "minimum": 0,
              "description": "Relevant match count for those 7 days."
            },
            "share": {
              "type": "number",
              "minimum": 0,
              "maximum": 1,
              "description": "The normal share of negative matches, smoothed so that a quiet week still gives a value."
            }
          },
          "required": [
            "negative",
            "relevant",
            "share"
          ],
          "description": "The keyword's normal sentiment."
        }
      },
      "required": [
        "attentionId",
        "url",
        "keyword",
        "window",
        "negative",
        "relevant",
        "share",
        "baseline"
      ]
    }
  }
}