CommentKeyword API Reference

Endpoint-level reference for Personal Access Token (PAT) 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"
}

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.

Request Body

Field	Type	Required	Accepted Values	Notes
keyword	string	Yes	non-empty	Max 255 chars (database constraint).
matchMode	string	No	exact \| contains	Default exact.
scope	string	No	global \| post_specific	Default global.
commentReplies	string[]	No	array of strings	Default [].
dmMessages	string[]	No	array of strings	Default [].
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.

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": ["I sent details in DM"],
    "dmMessages": ["Here are pricing details"],
    "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.

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	Max 255 chars.
matchMode	string	No	exact \| contains	-
scope	string	No	global \| post_specific	-
commentReplies	string[]	No	array of strings	-
dmMessages	string[]	No	array of strings	-
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 resulting scope is post_specific.

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.

Path Parameters

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

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.