OverviewPlatformsAPI Reference
Keywords

Update a keyword

Rename it (`term`: the new term is tracked from now on, with no look-back; the mentions the old term found stay), mute or unmute it, reclassify it (`kind`), change the platforms it is tracked on, its classifier `context`, its `matching` rules (each rule field optional; an empty list clears one), or its monthly mention `cap` (null removes it; a cap above this month's count resumes a capped keyword at once). Rules apply to new mentions from the next poll; stored mentions are untouched.

PATCH
/v1/keywords/{id}

Authorization

AuthorizationBearer <token>

API key minted via POST /v1/api-keys (format mk_live_...)

In: header

Path Parameters

idstring

Keyword id (kw_...).

Length1 <= length

Request Body

term?string

Renames the keyword: the new term is tracked from now on, with no look-back, and the keyword keeps its id, its settings and the mentions the old term found. Wrap it in double quotes for the exact phrase only. A 409 when its group already tracks the new term.

Length2 <= length <= 80
kind?string

Reclassify it as brand, competitor or topic.

Value in"brand" | "competitor" | "topic"
muted?boolean

A muted keyword stops polling and matching; its mentions stay.

platforms?|null

Replaces the platform list; null means every platform, [] none (reviews only, when the keyword has reviewSources).

context?string|null

A sentence the classifier reads for this keyword only, on top of the company profile or the group's own description (at most 300 characters): what the term means here, what to ignore. "Arc is our browser; ignore the geometry word." Null clears it.

Lengthlength <= 300
matching?

Omitted fields are untouched; an empty list clears one.

cap?|null

Replaces the mention cap and its period (per, default month); null removes it. A cap above the current period's count resumes a capped keyword at once, one at or under it pauses it.

comments?

Comments under this keyword's mentions; omitted fields are untouched (on create: off, 20 per post).

display?

Which of this keyword's mentions you see, by language and country; each list is replaced when sent, kept when omitted. Hidden mentions are still billed.

groupId?string

Moves the keyword to this group (grp_...). A 409 when that group already tracks the term.

Length1 <= length
reviewSources?

Replaces the list of apps whose reviews this keyword collects; [] disconnects them all (their reviews stay). An app or country added here gets the free 30-day look-back; one already listed keeps its place.

Itemsitems <= 10
feeds?

Replaces the feeds this keyword reads; [] disconnects them all (their mentions stay). A feed added here is checked now and brings its newest 10 matching items of the last 30 days; one already listed keeps its place.

Itemsitems <= 20
readsWorkspaceFeeds?boolean

true: the keyword also reads the workspace's feeds (GET /v1/feeds), live from now on. false: its own feeds alone.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://api.mentio.dev/v1/keywords/kw_abc123" \  -H "Content-Type: application/json" \  -d '{}'
{
  "id": "string",
  "term": "string",
  "kind": "brand",
  "muted": true,
  "pausedForBalance": true,
  "pausedForNoise": true,
  "pausedForCap": true,
  "cap": {
    "mentions": 1,
    "per": "day",
    "used": 0,
    "welcome": true,
    "own": 0,
    "ownPer": "day",
    "resumesAt": "string"
  },
  "comments": {
    "enabled": true,
    "maxPerPost": 1
  },
  "display": {
    "languages": {
      "only": [
        "en"
      ],
      "excluded": [
        "en"
      ]
    },
    "countries": {
      "only": [
        "us"
      ],
      "excluded": [
        "us"
      ]
    }
  },
  "group": {
    "id": "string",
    "name": "string",
    "externalId": "string",
    "isDefault": true
  },
  "platforms": [
    "bluesky"
  ],
  "feeds": [
    {
      "url": "string",
      "title": "string",
      "connectedAt": "string"
    }
  ],
  "readsWorkspaceFeeds": true,
  "reviewSources": [
    {
      "platform": "appstore",
      "id": "string",
      "url": "string",
      "countries": [
        "string"
      ],
      "language": "string",
      "connectedAt": "string"
    }
  ],
  "context": "string",
  "matching": {
    "requiredTerms": [
      "string"
    ],
    "requiredMode": "any",
    "requiredGroups": [
      [
        "string"
      ]
    ],
    "excludedTerms": [
      "string"
    ],
    "excludedAuthors": [
      "string"
    ],
    "caseSensitive": true,
    "exactPhrase": true,
    "subreddits": {
      "only": [
        "string"
      ],
      "excluded": [
        "string"
      ]
    },
    "repositories": {
      "events": [
        "new"
      ],
      "minStars": 1000000,
      "minWeeklyStars": 25
    }
  },
  "stats": {
    "mentions": 0,
    "relevant": 0,
    "last7d": 0,
    "thisMonth": 0,
    "lastMentionAt": "string",
    "feedback": {
      "relevant": 0,
      "notRelevant": 0
    },
    "noise": {
      "scored": 0,
      "relevant": 0,
      "noisy": true
    },
    "health": "healthy",
    "cost": {
      "keywordDays": 0,
      "keywordCents": 0,
      "billableMentions": 0,
      "mentionCents": 0,
      "billableComments": 0,
      "commentCents": 0,
      "totalCents": 0
    }
  },
  "polling": [
    {
      "platform": "bluesky",
      "lastPolledAt": "string",
      "emptyPolls": 0
    }
  ],
  "createdAt": "string"
}
{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "requestId": "string",
    "retryAfterSeconds": 0
  }
}
{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "requestId": "string",
    "retryAfterSeconds": 0
  }
}
{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "requestId": "string",
    "retryAfterSeconds": 0
  }
}
{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "requestId": "string",
    "retryAfterSeconds": 0
  }
}

List keywords GET

The keywords of the workspace with their match stats and poll health. Without parameters: every keyword, newest first. `q` searches the term and the context; `kind`, `status` and `platform` narrow the list; `sort` orders it; `limit` and `offset` page it. `total` counts the keywords that matched before paging.

Export mentions as CSV GET

The same mentions GET /v1/mentions would list for these filters, as CSV, newest matched first (the order they entered your feed, which can differ from the post date): id, published_at, platform, keyword, author, author_url, author_followers, relevance, sentiment, intents (pipe-separated), language, confidence, status, relevant, delivered, url, links (pipe-separated), text (first 1,000 characters), group, group_external_id, rating and app_id (app store reviews only), title and image_url (where the platform has them), duplicate_of (the mention a cross-post copies; the CSV keeps one row per mention, copies included; with includeHidden=true, the mentions a keyword hides by language or country too, it adds up to the bill), kind (post, comment or repository), parent_url (the post a comment answers), comments (comments of it delivered to you), subreddit and flair (Reddit only), country (where the author is, ISO 3166-1 alpha-2, empty when unknown) and organization (true when a company or organization posted). Capped at 10,000 rows; the X-Mentions-Truncated header says when the cap cut the list. At most 6 exports per minute per workspace; a 429 carries Retry-After.