---
title: "Create a keyword"
description: "Starts monitoring a word or phrase. Matching, scoring and delivery start with the next poll. A workspace with balance can have up to 500 keywords, each costing $5 a month, taken from the balance day by day. `matching` narrows what counts as a match, with required and excluded terms, excluded authors and case, before anything is stored, so rejected posts are never billed. `context` is a sentence only this keyword's classifier reads. `cap` limits matched mentions per month. At the cap the keyword stops matching until the 1st of next month (UTC) or until you raise the cap, and its daily charge continues."
canonical: https://docs.rumoro.dev/api/keywords/create-keyword
markdown: https://docs.rumoro.dev/api/keywords/create-keyword.mdx
---

# Create a keyword

`POST /v1/keywords`

Starts monitoring a word or phrase. Matching, scoring and delivery start with the next poll. A workspace with balance can have up to 500 keywords, each costing $5 a month, taken from the balance day by day. `matching` narrows what counts as a match, with required and excluded terms, excluded authors and case, before anything is stored, so rejected posts are never billed. `context` is a sentence only this keyword's classifier reads. `cap` limits matched mentions per month. At the cap the keyword stops matching until the 1st of next month (UTC) or until you raise the cap, and its daily charge continues.

## Body

| Field | Required | Description |
| --- | --- | --- |
| `term` | yes | The word or phrase to monitor. It matches as a whole phrase, ignoring case. |
| `kind` |  | brand is for your own names, competitor for a rival's, and topic for your market. Share of voice and segments use it. |
| `platforms` |  | The platforms to search for the term. Leave it out or send null for all platforms. An empty list searches nowhere, for a keyword that only collects reviews and so needs reviewSources. |
| `context` |  | 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 "Driftwood is our deploy tool, not beach wood." Null clears it. |
| `matching` |  | Fields you leave out stay as they are. An empty list clears a field. |
| `cap` |  | Monthly limit on matched mentions. Omit or null means none. |
| `groupId` |  | The group to put it in (grp_...). Without it, the workspace's default group is used. Each group can hold a term only once. |
| `reviewSources` |  | Review pages for this keyword, at most 10 (App Store and Google Play apps, Trustpilot pages, Google Maps places). Every new review on them is a mention, whatever it says. Pages are read daily, per country on the app stores. A newly added page imports its last 30 days, up to 100 newest reviews per country, free and without instant alerts. Later reviews are billed like other mentions. |

## Responses

| Status | Meaning |
| --- | --- |
| 201 | The new keyword |
| 401 | The API key is missing or not valid |
| 402 | The balance cannot cover one more keyword-day (insufficient_balance), or the workspace already has 500 keywords (keyword_limit_reached) |
| 409 | The group already has a keyword with this term after normalizing |

The [OpenAPI document](https://api.rumoro.dev/v1/openapi.json) has every schema. Rules shared by all endpoints are in [Conventions](https://docs.rumoro.dev/conventions.mdx).