Create Comment Automation API
The Create Comment Automation API creates a comment automation for a social account by sending a POST request to {{API_BASE_URL}}/v1/comment-automations/. You supply the accountId, a name, the postScope, trigger keywords, publicReplies and a dmMessage, with optional status, platformPostId, postPermalink, matchMode and excludeKeywords to narrow when the automation applies. A successful request returns a 201 response with the created automation, including its trigger, actions and stats.
Create Comment Automation API - POST {{API_BASE_URL}}/v1/comment-automations/
Use POST {{API_BASE_URL}}/v1/comment-automations/ to create a comment automation. The trailing slash is part of the documented path and should be preserved exactly. Send the request as application/json and include the access key in the x-access-key header, using the header name x-access-key and a token value in place of the placeholder shown in the request example. Before sending, check that every required field is present and that each array and string stays within its documented length and item limits, because the request body table lists those constraints field by field.
Authorization: x-access-key header
Authentication uses the accessKey supplied in the x-access-key header. Place the token in that header on the POST request alongside Content-Type: application/json. If the header is missing or invalid, do not assume the request will succeed; treat any non-201 response as a failure and inspect its status code and message field before retrying.
Request body field map
Build the JSON body around the required fields accountId, name, postScope, keywords, publicReplies and dmMessage. The name must be between 1 and 100 characters, keywords is an array of up to 20 strings each between 1 and 60 characters, publicReplies is an array of up to 5 strings each between 1 and 500 characters, and dmMessage is a string between 1 and 1000 characters. The optional status field accepts active or paused, postScope accepts any or specific, and matchMode accepts exact, contains or word. Use platformPostId with at least 1 character and postPermalink as a URI when you need to target a specific post, and use excludeKeywords as an array of up to 20 strings each between 1 and 60 characters to exclude matching comments. The source contract marks platformPostId and postPermalink as optional in the request, so do not treat them as universally required, and do not assume defaults for the optional fields.
Worked example request
The worked request example in the code examples shows the minimal documented body with accountId, name, postScope set to any, keywords, publicReplies and dmMessage. Replace each string placeholder with a real value that satisfies the length and item constraints, keep the JSON types exact, and send the body with the x-access-key header. After sending, verify the response status before reading the body: only a 201 response contains the automation object.
201 application/json response
A 201 application/json response contains success set to true and an automation object. The automation object contains id, accountId, platform, name, status, trigger, actions, stats, createdAt and updatedAt. The trigger object contains postScope, platformPostId, postPermalink, postId, keywords, matchMode and excludeKeywords, where platformPostId, postPermalink and postId are string or null in the response. The actions object contains publicReplies and dmMessage. The stats object contains triggered, succeeded and failed as numbers, plus lastRunAt and lastError as string or null. Store the returned automation id for later list or update operations, and check stats fields to understand whether the automation has run.
Error status responses 400, 403, 404 and 424
The documented error statuses are 400, 403, 404 and 424, and each returns an application/json body with success and message. The contract specifies the status codes and that shape only, so client code should handle each code distinctly, display or log the message, and avoid inventing a specific cause for any of them. A practical failure check is to branch on the exact status code, confirm that success is present in the body, and only treat a 201 response as a successful creation.
Input contract checklist
Before publishing client code against this endpoint, run a final checklist: confirm the method is POST, the path is /v1/comment-automations/ with its trailing slash, the origin is supplied through {{API_BASE_URL}}, the x-access-key header is set, all required fields are present with correct types, enums use only the documented values, and array and string limits are respected. Then confirm that the client handles the 201 automation response and each documented error status without assuming undocumented meanings or defaults.
| Field | Required | Type | Constraints / enum |
|---|---|---|---|
| accountId | Required | string | |
| name | Required | string | 1 <= length <= 100 |
| status | Optional | string | "active" | "paused" |
| postScope | Required | string | "any" | "specific" |
| platformPostId | Optional | string | 1 <= length |
| postPermalink | Optional | string | Format: uri |
| keywords | Required | array<string> | items <= 20; each item 1 <= length <= 60 |
| matchMode | Optional | string | "exact" | "contains" | "word" |
| excludeKeywords | Optional | array<string> | items <= 20; each item 1 <= length <= 60 |
| publicReplies | Required | array<string> | items <= 5; each item 1 <= length <= 500 |
| dmMessage | Required | string | 1 <= length <= 1000 |
Exact request contract for POST /v1/comment-automations/
| Field | Type | Notes |
|---|---|---|
| success | boolean | Required |
| automation.id | string | Required |
| automation.accountId | string | Required |
| automation.platform | string | Required |
| automation.name | string | Required |
| automation.status | string | "active" | "paused" |
| automation.trigger.postScope | string | "any" | "specific" |
| automation.trigger.platformPostId | string | null | Required in response |
| automation.trigger.postPermalink | string | null | Required in response |
| automation.trigger.postId | string | null | Required in response |
| automation.trigger.keywords | array<string> | Required |
| automation.trigger.matchMode | string | "exact" | "contains" | "word" |
| automation.trigger.excludeKeywords | array<string> | Required |
| automation.actions.publicReplies | array<string> | Required |
| automation.actions.dmMessage | string | Required |
| automation.stats.triggered | number | Required |
| automation.stats.succeeded | number | Required |
| automation.stats.failed | number | Required |
| automation.stats.lastRunAt | string | null | date-time or null |
| automation.stats.lastError | string | null | Required |
| automation.createdAt | string | date-time |
| automation.updatedAt | string | date-time |
Exact 201 response contract
| Status | Content type | Body shape | Documented meaning |
|---|---|---|---|
| 201 | application/json | {success, automation} | Automation created |
| 400 | application/json | {success, message} | Not specified in source |
| 403 | application/json | {success, message} | Not specified in source |
| 404 | application/json | {success, message} | Not specified in source |
| 424 | application/json | {success, message} | Not specified in source |
Statuses and shapes only; meanings not specified in source
Frequently asked questions
What is required to create a comment automation?
Send POST to {{API_BASE_URL}}/v1/comment-automations/ with the x-access-key header and a JSON body containing accountId, name, postScope, keywords, publicReplies and dmMessage. Optional fields are status, platformPostId, postPermalink, matchMode and excludeKeywords.
What does a successful 201 response contain?
A 201 response returns success and an automation object containing id, accountId, platform, name, status, trigger, actions, stats, createdAt and updatedAt. The trigger echoes postScope, platformPostId, postPermalink, postId, keywords, matchMode and excludeKeywords, while actions echoes publicReplies and dmMessage.
Which error statuses are documented for this endpoint?
The documented error statuses are 400, 403, 404 and 424, each with a JSON body containing success and message. The source contract does not specify a distinct meaning for each status, so clients should branch on the status code and surface the message without assuming a cause.
curl -X POST "{{API_BASE_URL}}/v1/comment-automations/" \
-H "Content-Type: application/json" \
-H "x-access-key: <token>" \
-d '{
"accountId": "string",
"name": "string",
"postScope": "any",
"keywords": [
"string"
],
"publicReplies": [
"string"
],
"dmMessage": "string"
}'{
"success": true,
"automation": {
"id": "string",
"accountId": "string",
"platform": "string",
"name": "string",
"status": "active",
"trigger": {
"postScope": "any",
"platformPostId": "string",
"postPermalink": "string",
"postId": "string",
"keywords": [
"string"
],
"matchMode": "exact",
"excludeKeywords": [
"string"
]
},
"actions": {
"publicReplies": [
"string"
],
"dmMessage": "string"
},
"stats": {
"triggered": 0,
"succeeded": 0,
"failed": 0,
"lastRunAt": "2019-08-24T14:15:22Z",
"lastError": "string"
},
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
}{
"success": true,
"message": "string"
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| body#1 | body | object | __0 | Yes | ||
| body#1 | body.accountId | string | __1 | Yes | ||
| body#1 | body.name | string | __2 | Yes | kind: ; value: 1 <= length <= 100 | |
| body#1 | body.status | string | __3 | No | ||
| body#1 | body.status[variant1] | string | __3_extends:__4 | kind: ; value: "active" | ||
| body#1 | body.status[variant2] | string | __3_extends:__5 | kind: ; value: "paused" | ||
| body#1 | body.postScope | string | __6 | Yes | ||
| body#1 | body.postScope[variant1] | string | __6_extends:__7 | kind: ; value: "any" | ||
| body#1 | body.postScope[variant2] | string | __6_extends:__8 | kind: ; value: "specific" | ||
| body#1 | body.platformPostId | string | __9 | No | kind: ; value: 1 <= length | |
| body#1 | body.postPermalink | string | __10 | No | kind: ; value: uri | |
| body#1 | body.keywords | array<string> | __11 | Yes | kind: ; value: items <= 20 | |
| body#1 | body.keywords[] | string | __12 | kind: ; value: 1 <= length <= 60 | ||
| body#1 | body.matchMode | string | __13 | No | ||
| body#1 | body.matchMode[variant1] | string | __13_extends:__14 | kind: ; value: "exact" | ||
| body#1 | body.matchMode[variant2] | string | __13_extends:__15 | kind: ; value: "contains" | ||
| body#1 | body.matchMode[variant3] | string | __13_extends:__16 | kind: ; value: "word" | ||
| body#1 | body.excludeKeywords | array<string> | __17 | No | kind: ; value: items <= 20 | |
| body#1 | body.excludeKeywords[] | string | __18 | kind: ; value: 1 <= length <= 60 | ||
| body#1 | body.publicReplies | array<string> | __19 | Yes | kind: ; value: items <= 5 | |
| body#1 | body.publicReplies[] | string | __20 | kind: ; value: 1 <= length <= 500 | ||
| body#1 | body.dmMessage | string | __21 | Yes | kind: ; value: 1 <= length <= 1000 | |
| response#2 | response | object | __0 | |||
| response#2 | response.success | boolean | __1 | Yes | ||
| response#2 | response.automation | object | __2 | Yes | ||
| response#2 | response.automation.id | string | __3 | Yes | ||
| response#2 | response.automation.accountId | string | __4 | Yes | ||
| response#2 | response.automation.platform | string | __5 | Yes | ||
| response#2 | response.automation.name | string | __6 | Yes | ||
| response#2 | response.automation.status | string | __7 | Yes | ||
| response#2 | response.automation.status[variant1] | string | __7_extends:__8 | kind: schemaValueIn; value: "active" | ||
| response#2 | response.automation.status[variant2] | string | __7_extends:__9 | kind: schemaValueIn; value: "paused" | ||
| response#2 | response.automation.trigger | object | __10 | Yes | ||
| response#2 | response.automation.trigger.postScope | string | __11 | Yes | ||
| response#2 | response.automation.trigger.postScope[variant1] | string | __11_extends:__12 | kind: schemaValueIn; value: "any" | ||
| response#2 | response.automation.trigger.postScope[variant2] | string | __11_extends:__13 | kind: ; value: "specific" | ||
| response#2 | response.automation.trigger.platformPostId | string | null | __14 | Yes | ||
| response#2 | response.automation.trigger.platformPostId[variant1] | string | __14_extends:__15 | |||
| response#2 | response.automation.trigger.platformPostId[variant2] | null | __14_extends:__16 | |||
| response#2 | response.automation.trigger.postPermalink | string | null | __17 | Yes | ||
| response#2 | response.automation.trigger.postPermalink[variant1] | string | __17_extends:__18 | |||
| response#2 | response.automation.trigger.postPermalink[variant2] | null | __17_extends:__19 | |||
| response#2 | response.automation.trigger.postId | string | null | __20 | Yes | ||
| response#2 | response.automation.trigger.postId[variant1] | string | __20_extends:__21 | |||
| response#2 | response.automation.trigger.postId[variant2] | null | __20_extends:__22 | |||
| response#2 | response.automation.trigger.keywords | array<string> | __23 | Yes | ||
| response#2 | response.automation.trigger.keywords[] | string | __24 | |||
| response#2 | response.automation.trigger.matchMode | string | __25 | Yes | ||
| response#2 | response.automation.trigger.matchMode[variant1] | string | __25_extends:__26 | kind: ; value: "exact" | ||
| response#2 | response.automation.trigger.matchMode[variant2] | string | __25_extends:__27 | kind: ; value: "contains" | ||
| response#2 | response.automation.trigger.matchMode[variant3] | string | __25_extends:__28 | kind: ; value: "word" | ||
| response#2 | response.automation.trigger.excludeKeywords | array<string> | __29 | Yes | ||
| response#2 | response.automation.trigger.excludeKeywords[] | string | __30 | |||
| response#2 | response.automation.actions | object | __31 | Yes | ||
| response#2 | response.automation.actions.publicReplies | array<string> | __32 | Yes | ||
| response#2 | response.automation.actions.publicReplies[] | string | __33 | |||
| response#2 | response.automation.actions.dmMessage | string | __34 | Yes | ||
| response#2 | response.automation.stats | object | __35 | Yes | ||
| response#2 | response.automation.stats.triggered | number | __36 | Yes | ||
| response#2 | response.automation.stats.succeeded | number | __37 | Yes | ||
| response#2 | response.automation.stats.failed | number | __38 | Yes | ||
| response#2 | response.automation.stats.lastRunAt | string | null | __39 | Yes | ||
| response#2 | response.automation.stats.lastRunAt[variant1] | string | __39_extends:__40 | kind: ; value: date-time | ||
| response#2 | response.automation.stats.lastRunAt[variant2] | null | __39_extends:__41 | |||
| response#2 | response.automation.stats.lastError | string | null | __42 | Yes | ||
| response#2 | response.automation.stats.lastError[variant1] | string | __42_extends:__43 | |||
| response#2 | response.automation.stats.lastError[variant2] | null | __42_extends:__44 | |||
| response#2 | response.automation.createdAt | string | __45 | Yes | kind: ; value: date-time | |
| response#2 | response.automation.updatedAt | string | __46 | Yes | kind: ; value: date-time | |
| response#3 | response | object | __0 | |||
| response#3 | response.success | boolean | __1 | Yes | ||
| response#3 | response.message | string | __2 | Yes |