Create keywords

POST/api/v1/keywords

Adds keywords in one call. Never all-or-nothing: each item lands in created, existing (already tracked, returned with its id) or rejected (with a reason). Matching starts within minutes.

Request

Body parameters

keywordsarray

1 to 500 items. Each: { text, mode?, track_posts?, track_comments? }. A bare array or a single { text } object is accepted too.

keywords[].textstring

2 to 80 characters, at most 6 words.

keywords[].modestring

exact (default), proximity or broad.

keywords[].track_postsboolean

Default true.

keywords[].track_commentsboolean

Default true. At least one of the two must be true.

Response

Returns a JSON object with a data field containing the result.

Response fields

created[]array

Keywords added by this call.

existing[]array

Keywords that were already live, with their ids.

rejected[]array

{ text, reason, message }. reason: invalid, duplicate (twice in the request) or limit_reached.

curl -X POST https://redship.io/api/v1/keywords \
-H "Authorization: Bearer rsp_your_key" \
-H "Content-Type: application/json" \
-d '{"keywords":[{"text":"stripe webhook"},{"text":"notion alternative","mode":"proximity","track_comments":false}]}'

Success response201

{
"created": [
  { "id": "9e0d…", "text": "stripe webhook", "mode": "exact", "active": true, "track_posts": true, "track_comments": true, "created_at": "…", "updated_at": "…" }
],
"existing": [
  { "id": "5b2c…", "text": "notion alternative", "mode": "proximity", "active": true, "track_posts": true, "track_comments": true, "created_at": "…", "updated_at": "…" }
],
"rejected": [
  { "text": "x", "reason": "invalid", "message": "Keyword must be 2 to 80 characters" }
]
}

The status is 201 when at least one keyword was created, 200 otherwise. Text matching is case-insensitive: Notion Alternative and notion alternative are the same keyword.