CommentKeyword API Reference

Endpoint-level reference for Personal Access Token (PAT) integrations.

OpenAPI specification

Use the OpenAPI 3.1 JSON document with API clients, code generators, testing tools, or AI integrations.

Authentication

All requests require:

Authorization: Bearer YOUR_TOKEN

Tokens are workspace-scoped and do not expire automatically.

Base URL

https://commentkeyword.com/api

Permissions

keywords:read
keywords:write
keywords:delete
agents:read (optional; keywords:read can also read agents)

Public IDs

PAT responses expose public IDs (UUID-like strings) for keywords and agents. Use these IDs in API paths and payloads.

{
  "id": "5f9619c5-daa7-4f2f-ad6f-971f71f8d7f2",
  "aiAgentId": "a6be1900-8f4f-4ae6-8f4e-48f8b28f0f17"
}

Keyword scopes and message limits

global matches comments on any post.
post_specific matches only assigned posts - listed in mediaIds, added later via a PATCH, and/or caught while includeNextPost is enabled.
includeNextPost (post_specific only) turns waiting on or off. It automatically becomes false after the next publication is found; enable it again whenever you want to catch another future post.
Keyword triggers are limited to 100 Unicode characters.
Comment replies may render to at most 500 characters.
Each DM plus an assigned agent's conversation hook may render to at most 1,000 characters.

GET /api/agents

Required permission: agents:read or keywords:read.

Parameters

Field	Type	Required	Accepted Values	Notes
(none)	-	No	-	No path, query, or body parameters.

curl -H "Authorization: Bearer YOUR_TOKEN" https://commentkeyword.com/api/agents

GET /api/keywords

Required permission: keywords:read.

Query Parameters

Field	Type	Required	Accepted Values	Notes
search	string	No	any text	Case-insensitive keyword search.
status	string	No	active \| inactive	Filters by keyword activation state.
limit	integer	No	1..100	Default 50.
offset	integer	No	>= 0	Default 0.

curl -H "Authorization: Bearer YOUR_TOKEN" "https://commentkeyword.com/api/keywords?status=active&limit=20&offset=0"

POST /api/keywords

Required permission: keywords:write.

commentReplies and dmMessages support personalization placeholders:{{handle}}, {{name}}, and {{namefirst}}.

Request Body

Field	Type	Required	Accepted Values	Notes
keyword	string	Yes	non-empty	Maximum 100 Unicode characters. Surrounding whitespace is normalized.
matchMode	string	No	contains \| exact	Default contains.
matchWithoutAccents	boolean	No	true \| false	Available only for keywords with Latin accents. When true, “guía” also matches “guia”. Default false.
scope	string	No	global \| post_specific	Default global. post_specific matches only assigned posts - see mediaIds and includeNextPost.
commentReplies	string[]	No	array of strings	Default []. Empty variants are removed. Rendered limit: 500 characters per variant.
dmMessages	string[]	Yes	array of strings	At least one non-empty variant. Rendered DM plus agent conversation hook limit: 1,000 characters.
trackLinks	boolean	No	true \| false	Default false. Replaces eligible DM links with tracked links.
delaySec	integer	No	1..60	Default 30.
aiAgentId	string \| null	No	agent public ID UUID string or null	If set, must refer to a Live agent in the same workspace.
mediaIds	string[]	Conditional	array of non-empty strings	Required when scope is post_specific, unless includeNextPost is true. Values are trimmed and deduplicated.
mediaUrls	object	No	media ID → Instagram URL	Optional permalink map for selected media IDs.
includeNextPost	boolean	No	true \| false	Default false. post_specific only. Waits for the next publication, adds it to mediaIds, then automatically becomes false.

curl -X POST https://commentkeyword.com/api/keywords \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "pricing",
    "matchMode": "contains",
    "scope": "global",
    "commentReplies": ["Sent it to you, {{namefirst}}!"],
    "dmMessages": ["Hey {{namefirst}}, here are the pricing details."],
    "trackLinks": true,
    "delaySec": 20,
    "aiAgentId": "a6be1900-8f4f-4ae6-8f4e-48f8b28f0f17"
  }'

GET /api/keywords/{id}

Required permission: keywords:read.

Path Parameters

Field	Type	Required	Accepted Values	Notes
id	string	Yes	keyword public ID UUID string	Use keyword public ID.

curl -H "Authorization: Bearer YOUR_TOKEN" https://commentkeyword.com/api/keywords/5f9619c5-daa7-4f2f-ad6f-971f71f8d7f2

PATCH /api/keywords/{id}

Required permission: keywords:write.

Partial update: only provided fields are changed.

Message fields can include {{handle}}, {{name}}, and {{namefirst}}.

Path Parameters

Field	Type	Required	Accepted Values	Notes
id	string	Yes	keyword public ID UUID string	-

Request Body

Field	Type	Required	Accepted Values	Notes
keyword	string	No	non-empty	Maximum 100 Unicode characters.
matchMode	string	No	contains \| exact	-
matchWithoutAccents	boolean	No	true \| false	Available only for keywords with Latin accents.
scope	string	No	global \| post_specific	-
commentReplies	string[]	No	array of strings	Empty variants are removed. Rendered limit: 500 characters.
dmMessages	string[]	No	array of strings	If provided, must contain at least one non-empty variant. Combined DM and agent hook limit: 1,000 characters.
trackLinks	boolean	No	true \| false	Enables or disables tracked links in DM variants.
delaySec	integer	No	1..60	-
isActive	boolean	No	true \| false	-
aiAgentId	string \| null	No	agent public ID UUID string or null	If set, must refer to a Live agent in the same workspace.
mediaIds	string[]	Conditional	array of non-empty strings	Required when changing a global keyword to post_specific unless includeNextPost is true. Existing post-specific keywords may use an empty list to become dormant.
mediaUrls	object	No	media ID → Instagram URL	Optional permalink map for submitted media IDs.
includeNextPost	boolean	No	true \| false	post_specific only. true starts waiting; false stops a pending wait without removing assigned posts; omission preserves the current setting. Automatically false after a post is found.

curl -X PATCH https://commentkeyword.com/api/keywords/5f9619c5-daa7-4f2f-ad6f-971f71f8d7f2 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"isActive": false}'

DELETE /api/keywords/{id}

Required permission: keywords:delete.

If the keyword is linked to an AI agent, the first request returns 409 DELETE_CONFIRMATION_REQUIREDwith an impact summary. Review it, then repeat the request with ?confirm=true.

Path Parameters

Field	Type	Required	Accepted Values	Notes
id	string	Yes	keyword public ID UUID string	-

Query Parameters

Field	Type	Required	Accepted Values	Notes
confirm	boolean	Conditional	true \| false	Set true after receiving DELETE_CONFIRMATION_REQUIRED.

curl -X DELETE -H "Authorization: Bearer YOUR_TOKEN" https://commentkeyword.com/api/keywords/5f9619c5-daa7-4f2f-ad6f-971f71f8d7f2

Error Format

{
  "error": "Bad Request",
  "message": "delaySec must be a number between 1 and 60"
}

Common status codes: 200, 201, 400, 401, 403, 404, 409, 500.