Keyword

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/rumoro-dev/json-schema/rumoro-dev-keyword-schema.json",
  "title": "Keyword",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/rumoro-dev-openapi.json#/components/schemas/Keyword",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The keyword's id (kw_...)."
    },
    "term": {
      "type": "string"
    },
    "kind": {
      "type": "string",
      "enum": [
        "brand",
        "competitor",
        "topic"
      ]
    },
    "muted": {
      "type": "boolean",
      "description": "True when the keyword is neither polled nor matched. You, the wallet (pausedForBalance) or the noise brake (pausedForNoise) can mute it. Reaching the mention cap does not mute it (pausedForCap)."
    },
    "pausedForBalance": {
      "type": "boolean",
      "description": "Muted because the balance ran out. A top-up resumes it. Unmuting it yourself also needs balance."
    },
    "pausedForNoise": {
      "type": "boolean",
      "description": "Set when the noise brake muted the keyword. That happens on welcome credit once 20 or more matches are scored and under 30% are relevant. Unmuting it, or changing its required or excluded terms, platforms or context, resumes it when the balance covers another day. A top-up alone does not."
    },
    "pausedForCap": {
      "type": "boolean",
      "description": "Hit its monthly mention cap. Matching resumes on the 1st (UTC) or when you raise the cap. The keyword isn't muted and is still charged daily."
    },
    "cap": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "mentions": {
          "type": "integer",
          "minimum": 1,
          "maximum": 1000000,
          "description": "How many matched mentions the keyword may collect per calendar month (UTC). Every match counts, relevant or not, including a new keyword's look-back, since every match is billed."
        },
        "welcome": {
          "type": "boolean",
          "description": "Rumoro sets this while the workspace uses its welcome credit. It limits each keyword to 200 mentions a month until the first top-up."
        },
        "own": {
          "type": [
            "integer",
            "null"
          ],
          "description": "The cap you chose. While welcome is true it is the cap restored at the first top-up (null for none), and sending `mentions: 200` changes nothing. Otherwise it equals mentions."
        }
      },
      "required": [
        "mentions",
        "welcome",
        "own"
      ],
      "description": "Monthly limit on matched mentions. Null means none."
    },
    "comments": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Read the comments under this keyword's relevant mentions, from 30 minutes after each post, while its platform's conversations last. Each comment delivered costs $0.008 on the comments line of the bill (comments of fewer than three words are dropped, never billed). Off by default."
        },
        "maxPerPost": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "description": "How many of a thread's newest comments you receive, 20 by default and 100 at most: the ceiling on what one mention's comments can cost. A comment that names the keyword is a mention too, but only among these."
        }
      },
      "required": [
        "enabled",
        "maxPerPost"
      ],
      "description": "Comments under this keyword's mentions. When enabled, the thread of every new mention scored relevant is read from 30 minutes after the post, several times while its platform's conversations last (a day on Reddit, Hacker News and Bluesky, a week on GitHub, Stack Overflow and DEV, a month on YouTube): new comments only, newest first, at most maxPerPost per mention, and comments of fewer than three words are dropped. List them with GET /v1/mentions/{id}/comments."
    },
    "group": {
      "$ref": "#/$defs/GroupRef"
    },
    "platforms": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string",
        "enum": [
          "bluesky",
          "hackernews",
          "github",
          "stackoverflow",
          "devto",
          "reddit",
          "x",
          "youtube",
          "news",
          "linkedin",
          "tiktok",
          "instagram"
        ]
      },
      "description": "The platforms searched for the term. Null means all of them. An empty list means none, and the keyword only collects reviews."
    },
    "feeds": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/KeywordFeed"
      },
      "description": "The RSS or Atom feeds this keyword reads, in the order given."
    },
    "reviewSources": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ReviewSource"
      },
      "description": "The review pages the keyword reads, such as App Store and Google Play apps, Trustpilot pages and Google Maps places. Empty when there are none."
    },
    "context": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 300,
      "description": "Up to 300 characters the classifier reads for this keyword only, in addition to the company profile or the group's description. Say what the term means for you and what to ignore, for example \"Basil is our deploy tool, not the herb.\" Null clears it."
    },
    "matching": {
      "type": "object",
      "properties": {
        "requiredTerms": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          },
          "maxItems": 50,
          "description": "Terms the post must contain as well. requiredMode says whether one or all of them must appear. An empty list sets no requirement."
        },
        "requiredMode": {
          "type": "string",
          "enum": [
            "any",
            "all"
          ],
          "description": "any needs one of the required terms in the post. all needs every one."
        },
        "excludedTerms": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          },
          "maxItems": 50,
          "description": "Posts that contain one of these terms are dropped. Put `*` at the start or end of a term as a wildcard, so deploy* matches deployment and *bot matches nightlybot."
        },
        "excludedAuthors": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          },
          "maxItems": 100,
          "description": "Authors whose posts this keyword ignores. Each entry is a profile or post link, @handle, u/name, Bluesky DID or display name. Entries are normalized the same way as an alert's muted authors."
        },
        "caseSensitive": {
          "type": "boolean",
          "description": "When true, the term only matches in the exact case you typed, so RAG never matches rag. Defaults to false."
        }
      },
      "required": [
        "requiredTerms",
        "requiredMode",
        "excludedTerms",
        "excludedAuthors",
        "caseSensitive"
      ],
      "description": "Rules a post must pass before it is stored as a mention. A post they reject is never billed."
    },
    "stats": {
      "type": "object",
      "properties": {
        "mentions": {
          "type": "integer",
          "minimum": 0,
          "description": "All matches so far, relevant or not. Billing counts this number."
        },
        "relevant": {
          "type": "integer",
          "minimum": 0,
          "description": "Matches whose relevance score reached the threshold."
        },
        "last7d": {
          "type": "integer",
          "minimum": 0,
          "description": "Matches with a post date in the past 7 days."
        },
        "thisMonth": {
          "type": "integer",
          "minimum": 0,
          "description": "Matches recorded in the current calendar month (UTC). The cap is checked against this count."
        },
        "lastMentionAt": {
          "type": [
            "string",
            "null"
          ],
          "description": "Time of the latest matched post. Null before the first match."
        },
        "feedback": {
          "type": "object",
          "properties": {
            "relevant": {
              "type": "integer",
              "minimum": 0,
              "description": "Marked relevant by your team."
            },
            "notRelevant": {
              "type": "integer",
              "minimum": 0,
              "description": "Mentions someone on your team marked not relevant. This is noise the classifier missed."
            }
          },
          "required": [
            "relevant",
            "notRelevant"
          ],
          "description": "Your team's relevance marks, set with PATCH /v1/mentions/{id}."
        },
        "noise": {
          "type": "object",
          "properties": {
            "scored": {
              "type": "integer",
              "minimum": 0,
              "description": "How many of the last 14 days' matches are scored."
            },
            "relevant": {
              "type": "integer",
              "minimum": 0,
              "description": "How many of them were scored relevant."
            },
            "noisy": {
              "type": "boolean",
              "description": "True when the past 14 days have 20 or more scored matches and fewer than 30% are relevant. Narrow the keyword with required terms, excluded terms or context, because every match is billed, relevant or not."
            }
          },
          "required": [
            "scored",
            "relevant",
            "noisy"
          ],
          "description": "Relevance of the scored matches from the past 14 days. A keyword you narrow today drops the flag within two weeks."
        },
        "health": {
          "type": "string",
          "enum": [
            "healthy",
            "noisy",
            "quiet",
            "capped",
            "paused",
            "new"
          ],
          "description": "Health over the 14 days `noise` covers, by the same rule as GET /v1/keywords/{id}/health. The first that applies wins. paused (muted), capped (at its cap), noisy (20+ scored matches, under 30% relevant), new (under 7 days old, or changed in the last 7 days with under 20 scored since), quiet (7+ days, nothing relevant), otherwise healthy. After a change to matching rules, platforms or context, or an unmute, within the 14 days, only later matches count, while `noise` keeps all 14 days. The endpoint defaults to 30 days, so the two can differ, and it explains why and what to change."
        },
        "cost": {
          "type": "object",
          "properties": {
            "keywordDays": {
              "type": "integer",
              "minimum": 0,
              "description": "Charged days this month. A day is charged when the keyword is unmuted at the daily run, so a new keyword shows 0 until tomorrow."
            },
            "keywordCents": {
              "type": "integer",
              "description": "keywordDays at 500/30 cents each, which is $5 a month. Only the total is rounded."
            },
            "billableMentions": {
              "type": "integer",
              "minimum": 0,
              "description": "Matches billed this month. A match counts when it is scored, which is the time the ledger settles by. So this can lag behind thisMonth while matches are still being scored, and a match that failed to score never counts."
            },
            "mentionCents": {
              "type": "integer",
              "description": "Those matches priced at $0.008 each, with the total rounded once."
            },
            "billableComments": {
              "type": "integer",
              "minimum": 0,
              "description": "Comments billed on the comments line: comments delivered under mentions and matched replies, each once per workspace."
            },
            "commentCents": {
              "type": "integer",
              "description": "Those comments at $0.008 each, rounded once on the total."
            },
            "totalCents": {
              "type": "integer",
              "description": "keywordCents plus mentionCents plus commentCents."
            }
          },
          "required": [
            "keywordDays",
            "keywordCents",
            "billableMentions",
            "mentionCents",
            "billableComments",
            "commentCents",
            "totalCents"
          ],
          "description": "List-price cost this calendar month (UTC), equal to this keyword's row in GET /v1/usage/breakdown?month=<this month>. The ledger settles daily and can differ only by cumulative rounding."
        }
      },
      "required": [
        "mentions",
        "relevant",
        "last7d",
        "thisMonth",
        "lastMentionAt",
        "feedback",
        "noise",
        "health",
        "cost"
      ],
      "description": "Counted from this workspace's matches only."
    },
    "polling": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "platform": {
            "type": "string",
            "enum": [
              "bluesky",
              "hackernews",
              "github",
              "stackoverflow",
              "devto",
              "reddit",
              "x",
              "youtube",
              "news",
              "linkedin",
              "tiktok",
              "instagram",
              "appstore",
              "googleplay",
              "trustpilot",
              "googlemaps",
              "rss"
            ],
            "description": "The platform. Review platforms are appstore, googleplay, trustpilot and googlemaps (a place's Google reviews)."
          },
          "lastPolledAt": {
            "type": [
              "string",
              "null"
            ],
            "description": "When the term was last polled on this platform. Null before the first poll."
          },
          "emptyPolls": {
            "type": "integer",
            "description": "How many polls in a row found nothing new. The higher it gets, the less often the term is polled."
          }
        },
        "required": [
          "platform",
          "lastPolledAt",
          "emptyPolls"
        ]
      },
      "description": "Polling status for each platform that is polled on a schedule. Live feeds such as Bluesky are not listed."
    },
    "createdAt": {
      "type": "string",
      "description": "UTC time in ISO 8601."
    }
  },
  "required": [
    "id",
    "term",
    "kind",
    "muted",
    "pausedForBalance",
    "pausedForNoise",
    "pausedForCap",
    "cap",
    "comments",
    "group",
    "platforms",
    "feeds",
    "reviewSources",
    "context",
    "matching",
    "stats",
    "polling",
    "createdAt"
  ],
  "$defs": {
    "GroupRef": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "The group's id (grp_...)."
        },
        "name": {
          "type": "string",
          "description": "Name of the group."
        },
        "externalId": {
          "type": [
            "string",
            "null"
          ],
          "description": "An id from your own system, or null."
        },
        "isDefault": {
          "type": "boolean",
          "description": "True for the workspace's default group. New keywords go there when you don't name a group."
        }
      },
      "required": [
        "id",
        "name",
        "externalId",
        "isDefault"
      ],
      "description": "The keyword's group."
    },
    "KeywordFeed": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "description": "The feed itself, after redirects: the address that is read."
        },
        "title": {
          "type": [
            "string",
            "null"
          ],
          "description": "The feed's own title, when it has one."
        },
        "connectedAt": {
          "type": "string",
          "description": "When this keyword started reading the feed. Nothing published before it is a live mention."
        }
      },
      "required": [
        "url",
        "title",
        "connectedAt"
      ]
    },
    "ReviewSource": {
      "type": "object",
      "properties": {
        "platform": {
          "type": "string",
          "enum": [
            "appstore",
            "googleplay",
            "trustpilot",
            "googlemaps"
          ],
          "description": "Where the reviews come from. appstore is the Apple App Store, googleplay is Google Play, trustpilot is a company's Trustpilot page and googlemaps is the Google reviews of a place."
        },
        "id": {
          "type": "string",
          "description": "The platform's own id. An App Store app id, a Google Play package name, a Trustpilot domain, or a Google Place ID or cid."
        },
        "url": {
          "type": "string",
          "description": "URL of the review page, such as an app's store listing, a company's Trustpilot page or a place on Google Maps."
        },
        "countries": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Two-letter storefront codes, lowercase. Empty for Trustpilot and Google Maps."
        },
        "language": {
          "type": [
            "string",
            "null"
          ],
          "description": "The review language on Google Play. Null on other platforms."
        },
        "connectedAt": {
          "type": "string",
          "description": "When the keyword began collecting reviews from this page."
        }
      },
      "required": [
        "platform",
        "id",
        "url",
        "countries",
        "language",
        "connectedAt"
      ]
    }
  }
}