{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/instasent/json-schema/instasent-recommendation-response-schema.json",
  "title": "Recommendation report",
  "description": "What is worth doing next, best first. Always recomputed; nothing is\npersisted. Unlike attention, this changes over days rather than\nminutes and is not meant to be polled.\n",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/instasent-attention-api-openapi.yml#/components/schemas/RecommendationResponse",
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "description": "Sorted by priority, then by the order the catalog declares.",
      "items": {
        "$ref": "#/$defs/RecommendationItem"
      }
    },
    "counts": {
      "$ref": "#/$defs/RecommendationCounts"
    },
    "computedAt": {
      "type": "string",
      "format": "date-time"
    },
    "truncated": {
      "type": "boolean"
    }
  },
  "required": [
    "items",
    "counts",
    "computedAt",
    "truncated"
  ],
  "additionalProperties": false,
  "$defs": {
    "AttentionEntity": {
      "type": "object",
      "title": "Attention entity",
      "description": "Something an item is about, so a consumer can navigate to it without\nparsing copy. `name` is the entity's own display name and is therefore\ncustomer-written text; it is never personal data.\n",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "organization",
            "card",
            "invoice",
            "subscription",
            "project",
            "datasource",
            "auth",
            "sender",
            "register",
            "campaign",
            "token"
          ]
        },
        "id": {
          "type": "string",
          "description": "The entity's own id, or its uid where the surfaces address it that way."
        },
        "name": {
          "type": "string",
          "description": "Omitted when there is none. Never personal data."
        }
      },
      "required": [
        "type",
        "id"
      ],
      "additionalProperties": false
    },
    "RecommendationCounts": {
      "type": "object",
      "title": "Recommendation counts",
      "description": "By priority rather than by severity, since every item carries `info`.",
      "properties": {
        "high": {
          "type": "integer"
        },
        "medium": {
          "type": "integer"
        },
        "low": {
          "type": "integer"
        },
        "byKey": {
          "type": "object",
          "additionalProperties": {
            "type": "integer"
          }
        }
      },
      "required": [
        "high",
        "medium",
        "low",
        "byKey"
      ],
      "additionalProperties": false
    },
    "RecommendationItem": {
      "type": "object",
      "title": "Recommendation",
      "description": "One next step worth taking in a project that already works.\n\nSame engine and same shape as an attention item, a separate report:\n`counts` is computed over the whole list, so a single response\nfiltered down would still have counted suggestions as problems.\n\n`key` IS AN OPEN STRING, unlike the attention item's. This catalog is\nmeant to grow, and a new suggestion must not need a spec edit before\nit can ship. The keys that exist today are published in\n`attention-catalog.json` beside the TypeScript definitions.\n",
      "properties": {
        "id": {
          "type": "string",
          "description": "Content fingerprint of this occurrence, stable across polls."
        },
        "key": {
          "type": "string",
          "description": "Open on purpose. See the description above."
        },
        "scope": {
          "type": "string",
          "enum": [
            "org",
            "project",
            "channel"
          ]
        },
        "channel": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "sms",
            "rcs",
            null
          ]
        },
        "type": {
          "type": "string",
          "enum": [
            "recommendation"
          ]
        },
        "severity": {
          "type": "string",
          "enum": [
            "info"
          ],
          "description": "Always `info`. The ranking is `priority`."
        },
        "priority": {
          "type": "string",
          "enum": [
            "high",
            "medium",
            "low"
          ],
          "description": "Worst first. The only axis this list is ordered by, since every\nitem carries `info`. Declared per key and raised per occurrence\nwhen the situation warrants it.\n"
        },
        "summary": {
          "type": "string",
          "maxLength": 64,
          "description": "See `AttentionItem.summary`. English, never rendered by a dashboard."
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "dismiss": {
          "type": "object",
          "description": "How a consumer may let a user silence this item, constant per key.\nEvery recommendation is a plain `dismiss`: a suggestion must not\ncome back on a timer. What brings one back is its fingerprint, and\neach rule chooses that deliberately (a seasonal date carries the\nyear, a rolling measurement carries no date at all).\n",
          "properties": {
            "mode": {
              "type": "string",
              "enum": [
                "none",
                "dismiss",
                "snooze"
              ]
            },
            "days": {
              "type": "integer",
              "description": "Present only when `mode` is `snooze`."
            }
          },
          "required": [
            "mode"
          ],
          "additionalProperties": false
        },
        "entities": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AttentionEntity"
          }
        },
        "data": {
          "type": "object",
          "description": "Per-key payload a surface interpolates. Absent when the rule carries none.",
          "additionalProperties": true
        },
        "startsAt": {
          "type": "string",
          "format": "date-time"
        },
        "endsAt": {
          "type": "string",
          "format": "date-time"
        },
        "dueAt": {
          "type": "string",
          "format": "date-time",
          "description": "The date the suggestion stops being useful, when it has one."
        }
      },
      "required": [
        "id",
        "key",
        "scope",
        "channel",
        "type",
        "severity",
        "priority",
        "summary",
        "tags",
        "dismiss",
        "entities"
      ],
      "additionalProperties": false
    }
  }
}