List Comment Automations API
The List Comment Automations API returns existing comment automations so a client can inspect how each automation is scoped, what triggers it, what actions it performs, and how it has performed. Call GET {{API_BASE_URL}}/v1/comment-automations/ with an x-access-key header and, when you want to narrow the result, an accountId query parameter. The response contains an automations array; each entry combines identity fields with trigger, actions, and stats objects that should be read together rather than in isolation.
Request: GET {{API_BASE_URL}}/v1/comment-automations/
Use this endpoint when a dashboard, script, or agent needs an inventory of comment automations before deciding whether to create, update, or delete one. The request is a GET to {{API_BASE_URL}}/v1/comment-automations/ and the only query parameter in the contract is accountId, a string. Supplying accountId narrows the listing to automations belonging to that account; omitting it follows the contract as written, with accountId marked as not required. Before sending the request, confirm the token value is placed in the x-access-key header exactly as shown in the request sample titled List Comment Automations request, and confirm the trailing slash on the path is retained.
Authorization
Authentication is presented in the source under Authorization as a single header: x-access-key with a <token> value. The typed contract nodes do not supply an explicit required flag for this header, so this page shows the header exactly as presented without asserting requiredness beyond that presentation. When a request does not return 200, record the status code first, then read message, and do not assume a specific message string beyond the string type in the contract. The contract supplies only the success and message shape for 400 and 403, so no causal meaning is assigned to either status code here. The input contract table titled Authorization and query parameters summarizes the header and the accountId parameter together so both can be verified in one pass.
Query Parameters
The sole query parameter is accountId, typed as string and marked required=false in the typed contract. That means a client may call the endpoint without it, and when it is included the value should be the account identifier whose automations are wanted. Do not add pagination, sorting, or additional filter parameters, because none are part of this contract. The contract does not state what the endpoint returns when accountId is omitted, so no server-side behavior for omission is described here; each returned entry carries its own accountId field for identification.
Response Body: 200 application/json
A 200 response returns success as a boolean and automations as an array of automation objects. Each automation object carries id, accountId, platform, and name as required strings, plus status as a required string limited to active or paused. The createdAt and updatedAt fields are required date-time strings that show when the automation was created and last changed. As editorial reading guidance only, not as source-stated behavior, status can be read alongside stats: for example, a non-null lastError with a rising failed count is a combination a reader may choose to inspect first. The field map titled Response field map lists every field with its type and requiredness, and the worked example titled 200 response body shows the full shape to compare against a payload field by field.
Response Body: 400 application/json
A 400 response returns success as a boolean and message as a string, with no automations array. The supplied contract provides only this status code and body shape; it does not state what causes a 400, so this page does not assign a cause. Because the exact message strings are not part of the supplied contract, log the message verbatim for debugging and do not branch client logic on a guessed string. The failure matrix titled Status and response shape distinguishes 200, 400, and 403 by status and body shape only, so the three cases are not conflated.
Response Body: 403 application/json
A 403 response also returns success as a boolean and message as a string, with no automations array. The supplied contract provides only this status code and body shape; it does not state what causes a 403, so this page does not assign a cause or a permission meaning. As with 400, the message should be surfaced as-is and not matched against invented text. Keeping 400 and 403 handling separate by status code and shape prevents the two cases from being conflated, without claiming why either occurred.
Field map and worked example
Interpret each automation by reading its trigger, actions, and stats objects as a unit. In trigger, postScope is either any or specific; when it is specific, check platformPostId, postPermalink, and postId, each of which is a required string or null, to see which post identifier is populated. The keywords array holds the phrases that can trigger the automation, matchMode is one of exact, contains, or word, and excludeKeywords lists phrases that should prevent a match. In actions, publicReplies is an array of public reply templates and dmMessage is a single string for the direct message template. In stats, triggered, succeeded, and failed are required numbers, lastRunAt is a required string or null date-time for the most recent run, and lastError is a required string or null describing the most recent failure. The following reading notes are editorial interpretation, not source-stated behavior: a keyword appearing in both keywords and excludeKeywords may merit a closer look, and comparing an empty publicReplies array with a populated dmMessage can help a reader describe the configured actions. The field map titled Response field map lists every field with its type and requiredness, and the worked example titled 200 response body shows the full shape to compare against a real payload field by field.
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
| x-access-key | header | string (<token>) | As presented under Authorization; no explicit required flag supplied | Authorization header identifier |
| accountId | query | string | No | Sole query parameter; filters listing by account |
accountId requiredness follows the typed contract (required=false). The x-access-key header is shown under Authorization in the source; no explicit required flag for the header is supplied in the typed contract nodes, so requiredness is not asserted beyond that presentation.
| Field | Type | Required | Values / notes |
|---|---|---|---|
| success | boolean | Yes | Top-level, all statuses |
| automations | array<object> | Yes | 200 only |
| automations[].id | string | Yes | |
| automations[].accountId | string | Yes | |
| automations[].platform | string | Yes | |
| automations[].name | string | Yes | |
| automations[].status | string | Yes | active | paused |
| automations[].trigger | object | Yes | |
| automations[].trigger.postScope | string | Yes | any | specific |
| automations[].trigger.platformPostId | string | null | Yes | |
| automations[].trigger.postPermalink | string | null | Yes | |
| automations[].trigger.postId | string | null | Yes | |
| automations[].trigger.keywords | array<string> | Yes | |
| automations[].trigger.matchMode | string | Yes | exact | contains | word |
| automations[].trigger.excludeKeywords | array<string> | Yes | |
| automations[].actions | object | Yes | |
| automations[].actions.publicReplies | array<string> | Yes | |
| automations[].actions.dmMessage | string | Yes | |
| automations[].stats | object | Yes | |
| automations[].stats.triggered | number | Yes | |
| automations[].stats.succeeded | number | Yes | |
| automations[].stats.failed | number | Yes | |
| automations[].stats.lastRunAt | string | null (date-time) | Yes | |
| automations[].stats.lastError | string | null | Yes | |
| automations[].createdAt | string (date-time) | Yes | |
| automations[].updatedAt | string (date-time) | Yes | |
| message | string | Yes | 400 and 403 only |
Types, requiredness, nullability, and enums exactly as captured in the typed contract.
| Status | Content type | Body fields | Client check |
|---|---|---|---|
| 200 | application/json | success (boolean), automations (array<object>) | Iterate automations; read trigger, actions, stats together |
| 400 | application/json | success (boolean), message (string) | Record status code; log message verbatim; do not branch on guessed strings |
| 403 | application/json | success (boolean), message (string) | Record status code; log message verbatim; do not branch on guessed strings |
Exact 400/403 message strings and causal semantics for either status are not supplied; only the success/message shape is in the contract. No cause is assigned to 400 or 403.
curl -X GET "{{API_BASE_URL}}/v1/comment-automations/" -H "x-access-key: <token>"curl -X GET "{{API_BASE_URL}}/v1/comment-automations/?accountId=<accountId>" -H "x-access-key: <token>"{
"success": true,
"automations": [
{
"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 |
|---|---|---|---|---|---|---|
| accountId#1 | accountId | string | __0 | No | ||
| response#2 | response | object | __0 | |||
| response#2 | response.success | boolean | __1 | Yes | ||
| response#2 | response.automations | array<object> | __2 | Yes | ||
| response#2 | response.automations[] | object | __3 | |||
| response#2 | response.automations[].id | string | __4 | Yes | ||
| response#2 | response.automations[].accountId | string | __5 | Yes | ||
| response#2 | response.automations[].platform | string | __6 | Yes | ||
| response#2 | response.automations[].name | string | __7 | Yes | ||
| response#2 | response.automations[].status | string | __8 | Yes | ||
| response#2 | response.automations[].status[variant1] | string | __8_extends:__9 | kind: schemaValueIn; value: "active" | ||
| response#2 | response.automations[].status[variant2] | string | __8_extends:__10 | kind: schemaValueIn; value: "paused" | ||
| response#2 | response.automations[].trigger | object | __11 | Yes | ||
| response#2 | response.automations[].trigger.postScope | string | __12 | Yes | ||
| response#2 | response.automations[].trigger.postScope[variant1] | string | __12_extends:__13 | kind: schemaValueIn; value: "any" | ||
| response#2 | response.automations[].trigger.postScope[variant2] | string | __12_extends:__14 | kind: schemaValueIn; value: "specific" | ||
| response#2 | response.automations[].trigger.platformPostId | string | null | __15 | Yes | ||
| response#2 | response.automations[].trigger.platformPostId[variant1] | string | __15_extends:__16 | |||
| response#2 | response.automations[].trigger.platformPostId[variant2] | null | __15_extends:__17 | |||
| response#2 | response.automations[].trigger.postPermalink | string | null | __18 | Yes | ||
| response#2 | response.automations[].trigger.postPermalink[variant1] | string | __18_extends:__19 | |||
| response#2 | response.automations[].trigger.postPermalink[variant2] | null | __18_extends:__20 | |||
| response#2 | response.automations[].trigger.postId | string | null | __21 | Yes | ||
| response#2 | response.automations[].trigger.postId[variant1] | string | __21_extends:__22 | |||
| response#2 | response.automations[].trigger.postId[variant2] | null | __21_extends:__23 | |||
| response#2 | response.automations[].trigger.keywords | array<string> | __24 | Yes | ||
| response#2 | response.automations[].trigger.keywords[] | string | __25 | |||
| response#2 | response.automations[].trigger.matchMode | string | __26 | Yes | ||
| response#2 | response.automations[].trigger.matchMode[variant1] | string | __26_extends:__27 | kind: ; value: "exact" | ||
| response#2 | response.automations[].trigger.matchMode[variant2] | string | __26_extends:__28 | kind: ; value: "contains" | ||
| response#2 | response.automations[].trigger.matchMode[variant3] | string | __26_extends:__29 | kind: ; value: "word" | ||
| response#2 | response.automations[].trigger.excludeKeywords | array<string> | __30 | Yes | ||
| response#2 | response.automations[].trigger.excludeKeywords[] | string | __31 | |||
| response#2 | response.automations[].actions | object | __32 | Yes | ||
| response#2 | response.automations[].actions.publicReplies | array<string> | __33 | Yes | ||
| response#2 | response.automations[].actions.publicReplies[] | string | __34 | |||
| response#2 | response.automations[].actions.dmMessage | string | __35 | Yes | ||
| response#2 | response.automations[].stats | object | __36 | Yes | ||
| response#2 | response.automations[].stats.triggered | number | __37 | Yes | ||
| response#2 | response.automations[].stats.succeeded | number | __38 | Yes | ||
| response#2 | response.automations[].stats.failed | number | __39 | Yes | ||
| response#2 | response.automations[].stats.lastRunAt | string | null | __40 | Yes | ||
| response#2 | response.automations[].stats.lastRunAt[variant1] | string | __40_extends:__41 | kind: ; value: date-time | ||
| response#2 | response.automations[].stats.lastRunAt[variant2] | null | __40_extends:__42 | |||
| response#2 | response.automations[].stats.lastError | string | null | __43 | Yes | ||
| response#2 | response.automations[].stats.lastError[variant1] | string | __43_extends:__44 | |||
| response#2 | response.automations[].stats.lastError[variant2] | null | __43_extends:__45 | |||
| response#2 | response.automations[].createdAt | string | __46 | Yes | kind: ; value: date-time | |
| response#2 | response.automations[].updatedAt | string | __47 | Yes | kind: ; value: date-time | |
| response#3 | response | object | __0 | |||
| response#3 | response.success | boolean | __1 | Yes | ||
| response#3 | response.message | string | __2 | Yes |