Create Comment API: Create a comment or reply
The Create Comment API creates a top-level comment or reply to an existing comment through a single operation. Use POST /v1/comments/ with the platform, accountId and text fields, and choose postId or commentId according to whether you are posting a top-level comment or replying to an existing comment.
Create a comment or reply — operation summary
The Create Comment API posts a top-level comment on an Instagram, Facebook, LinkedIn, or YouTube post or video, or a top-level post on Threads, when you provide postId. It replies to an existing comment on Facebook, Instagram, Threads, LinkedIn, YouTube, or Twitter/X when you provide commentId. The operation is POST /v1/comments/ and the request body is application/json. Before sending, confirm the platform value, the integration ID in accountId, and that text is present, because those three fields are required. Then choose the target field: postId for a top-level comment, or commentId to reply to an existing comment. On success the response returns the created commentId, which you should store if you need to reference, delete, or reconcile the new comment later.
Platform behaviour: top-level comment vs reply
Which target field you supply determines the behaviour. Supplying postId creates a top-level comment on Instagram or Facebook, and on Threads it creates a top-level post. Supplying commentId instead targets a reply, and that reply path is available across Facebook, Instagram, Threads, LinkedIn, YouTube and Twitter/X. Two platforms use identifiers differently. With YouTube, the postId value identifies the video, while commentId identifies the parent comment. With Twitter/X, the operation produces a reply tweet: postId carries the tweet being answered and commentId carries the reply tweet identifier. There is also a separate route for that platform, since a Twitter reply can be published through the posting API by setting platformSpecificData.replyToTweetId. Pick one route for a given call rather than mixing them. The captured specification does not say whether postId and commentId can be sent together, so treat the decision as top-level versus reply and check it before sending.
Authorization
Authorization uses the accessKey sent in the x-access-key header. Send the token as the header value and set Content-Type to application/json for the request body. If authentication fails, do not retry with a different header name, because the captured contract specifies x-access-key in the header. Keep the token out of the JSON body, where it does not belong, and check the header spelling exactly before debugging the request fields.
Request Body
The request body contains five fields. The platform field is required and must be one of facebook, instagram, threads, linkedin, youtube, or twitter. The accountId field is required and is the integration ID. The text field is required and must satisfy 1 <= length. The postId and commentId fields are optional strings whose presence selects the operation: postId for a top-level comment or Threads top-level post, and commentId to reply to an existing comment. Use the request builder and checklist in the code examples to validate required fields and the postId or commentId choice before sending, and to catch an empty text value or a missing target field locally.
Response Body
A 200 response returns success as true and the created commentId as a string. The 400, 402, 403, 404, and 502 responses each return success as true with a message string in the captured shape, so branch on the status code first and then read the documented field for that status. Do not assume a trigger meaning for the error statuses beyond the captured status and shape, because the source does not specify them. For a successful call, persist commentId from the 200 response; for any other status, surface the message and stop rather than treating the comment as created.
Origin-modular HTTP examples
The worked HTTP example uses the origin-modular form {{API_BASE_URL}} before the unchanged path /v1/comments/, preserving the captured POST method, Content-Type header, and JSON body fields platform, accountId, and text. Add the x-access-key header with your token, then adapt the body for a reply by supplying commentId instead of relying on a top-level postId. Check the response status before reading commentId, and keep the trailing slash on /v1/comments/ exactly as captured.
Credit cost note
Credit cost is 1 credit on most platforms. Twitter costs 5 credits, or 50 if the text contains a link, the same as a tweet. Check your available credits before sending a Twitter/X reply, especially when the text contains a link, because the cost changes in that case. The cost note is part of the captured contract for this operation and should be reflected in any budgeting or retry logic you build around the call.
| Field | Type | Required | Description / constraint |
|---|---|---|---|
| platform | string | Required | Platform to post the comment on. Value in "facebook" | "instagram" | "threads" | "linkedin" | "youtube" | "twitter" |
| accountId | string | Required | Integration ID. |
| postId | string | Optional | Platform post/media ID. Provide this to create a top-level comment on Instagram or Facebook, or a top-level post on Threads. |
| commentId | string | Optional | Platform comment ID to reply to. Provide this to reply to an existing comment. |
| text | string | Required | Comment text. Length 1 <= length |
Exact captured request contract.
| Platform | Top-level comment / post | Reply to an existing comment |
|---|---|---|
| Provide postId | Provide commentId | |
| Provide postId | Provide commentId | |
| Threads | Provide postId for a top-level post | Provide commentId |
| Not stated as a top-level postId case in the source summary | Provide commentId | |
| YouTube | postId is the video ID | commentId is the parent comment ID |
| Twitter/X | postId is the tweet ID | commentId is the reply tweet ID; a comment is a reply tweet |
Only source-stated postId/commentId rules; combination of both fields not specified.
| Status | Content type | Response shape |
|---|---|---|
| 200 | application/json | {"success": true, "commentId": "string"} |
| 400 | application/json | {"success": true, "message": "string"} |
| 402 | application/json | {"success": true, "message": "string"} |
| 403 | application/json | {"success": true, "message": "string"} |
| 404 | application/json | {"success": true, "message": "string"} |
| 502 | application/json | {"success": true, "message": "string"} |
Trigger meanings for error statuses are not specified in the source and are not invented here.
| Item | Captured value |
|---|---|
| Method | POST |
| Path | /v1/comments/ |
| Authorization | x-access-key header with <token> |
| Request content type | application/json |
| Cost on most platforms | 1 credit |
| Twitter cost | Twitter costs 5 credits (50 if the text contains a link) |
| Alternative Twitter reply path | platformSpecificData.replyToTweetId via the posting API |
Exact captured operation contract.
curl -X POST "{{API_BASE_URL}}/v1/comments/" \
-H "Content-Type: application/json" \
-H "x-access-key: <token>" \
-d '{
"platform": "facebook",
"accountId": "string",
"text": "string"
}'{
"success": true,
"commentId": "string"
}{
"success": true,
"message": "string"
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| body#1 | body | object | __0 | Yes | ||
| body#1 | body.platform | string | __1 | Yes | Platform to post the comment on. | kind: schemaValueIn; value: "facebook" | "instagram" | "threads" | "linkedin" | "youtube" | "twitter" |
| body#1 | body.accountId | string | __2 | Yes | Integration ID. | |
| body#1 | body.postId | string | __3 | No | Platform post/media ID. Provide this to create a top-level comment on Instagram or Facebook, or a top-level post on Threads. | |
| body#1 | body.commentId | string | __4 | No | Platform comment ID to reply to. Provide this to reply to an existing comment. | |
| body#1 | body.text | string | __5 | Yes | Comment text. | kind: ; value: 1 <= length |
| response#2 | response | object | __0 | |||
| response#2 | response.success | boolean | __1 | Yes | ||
| response#2 | response.commentId | string | __2 | Yes | ID of the created comment or reply. | |
| response#3 | response | object | __0 | |||
| response#3 | response.success | boolean | __1 | Yes | ||
| response#3 | response.message | string | __2 | Yes |