Adds your own keywords to a Niche's Master Keyword List (MKL), the same way the web app does. Every submitted keyword a phrase exclusion does not block is reported in exactly one of these originBreakdown groups:

• alreadyInMkl — already in the MKL; left untouched.
• takenFromOutliers / takenFromResidue — moved into the MKL from the Outliers or Residue list. Free.
• addedManually — new to the Niche. Ranked against the Niche's Competitors; relevancy can be 0.

Two groups report keywords that match one of the Niche's keyword exclusions:

• takenFromExcluded — matched an exact exclusion. The exclusion is removed, so the keyword shows again; it is also listed in the group above it landed in.
• blockedByPhraseExclusion — matched a phrase exclusion. The rule is left in place and the keyword is not added; it appears in no other group, and matchedPhrase names the rule to remove first.

Cost. While the Niche is fresh (dived within the last 24 hours, or a Dive is already running) the add is free and the keywords are readable from GET /v1/niches/{nicheId}/keywords at once. Once it is stale, adding any new keyword re-dives the Niche with its current Competitors and consumes one Dive token per Competitor, like a same_competitors re-dive. The response then carries refresh.diveId; poll GET /v1/niches/dives/{diveId} until success, after which the keywords are in the MKL.

Send dryRun: true first to see tokensUsed without saving or paying anything, then pass that figure as maxTokensUsed on the real call so it can never cost more than the dry run said. A dry run runs every check the real call does except the 422, which only the re-dive itself can discover. Undo an add with POST /v1/niches/{nicheId}/keywords/remove.

Rate limited to 2 requests per minute per Niche, dry runs included.

{
  "keywords": [
    "paint by numbers for adults",
    "diamond painting kits"
  ]
}

{
  "data": {
    "originBreakdown": {
      "alreadyInMkl": [
        "diamond painting kits"
      ],
      "takenFromOutliers": [],
      "takenFromResidue": [],
      "addedManually": [
        "paint by numbers for adults"
      ],
      "takenFromExcluded": [
        "diamond painting kits"
      ],
      "blockedByPhraseExclusion": [
        {
          "keyword": "cheap paint by numbers",
          "matchedPhrase": "cheap"
        }
      ]
    },
    "refresh": {
      "diveId": "b3e1f2c4-7e6a-4d2a-9f1e-123456789abc",
      "estimatedCompletionDate": "2026-08-01T00:00:00Z"
    }
  }
}