Skip to content

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.

Request body field map
FieldTypeRequiredDescription / constraint
platformstringRequiredPlatform to post the comment on. Value in "facebook" | "instagram" | "threads" | "linkedin" | "youtube" | "twitter"
accountIdstringRequiredIntegration ID.
postIdstringOptionalPlatform post/media ID. Provide this to create a top-level comment on Instagram or Facebook, or a top-level post on Threads.
commentIdstringOptionalPlatform comment ID to reply to. Provide this to reply to an existing comment.
textstringRequiredComment text. Length 1 <= length

Exact captured request contract.

Platform-by-platform: top-level comment vs reply
PlatformTop-level comment / postReply to an existing comment
InstagramProvide postIdProvide commentId
FacebookProvide postIdProvide commentId
ThreadsProvide postId for a top-level postProvide commentId
LinkedInNot stated as a top-level postId case in the source summaryProvide commentId
YouTubepostId is the video IDcommentId is the parent comment ID
Twitter/XpostId is the tweet IDcommentId is the reply tweet ID; a comment is a reply tweet

Only source-stated postId/commentId rules; combination of both fields not specified.

Response status and shape matrix
StatusContent typeResponse shape
200application/json{"success": true, "commentId": "string"}
400application/json{"success": true, "message": "string"}
402application/json{"success": true, "message": "string"}
403application/json{"success": true, "message": "string"}
404application/json{"success": true, "message": "string"}
502application/json{"success": true, "message": "string"}

Trigger meanings for error statuses are not specified in the source and are not invented here.

Operation contract summary
ItemCaptured value
MethodPOST
Path/v1/comments/
Authorizationx-access-key header with <token>
Request content typeapplication/json
Cost on most platforms1 credit
Twitter costTwitter costs 5 credits (50 if the text contains a link)
Alternative Twitter reply pathplatformSpecificData.replyToTweetId via the posting API

Exact captured operation contract.

Create a comment or reply request
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"
  }'
200 success response
{
  "success": true,
  "commentId": "string"
}
Error response shape for 400, 402, 403, 404 and 502
{
  "success": true,
  "message": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
body#1bodyobject__0Yes
body#1body.platformstring__1YesPlatform to post the comment on.kind: schemaValueIn; value: "facebook" | "instagram" | "threads" | "linkedin" | "youtube" | "twitter"
body#1body.accountIdstring__2YesIntegration ID.
body#1body.postIdstring__3NoPlatform post/media ID. Provide this to create a top-level comment on Instagram or Facebook, or a top-level post on Threads.
body#1body.commentIdstring__4NoPlatform comment ID to reply to. Provide this to reply to an existing comment.
body#1body.textstring__5YesComment text.kind: ; value: 1 <= length
response#2responseobject__0
response#2response.successboolean__1Yes
response#2response.commentIdstring__2YesID of the created comment or reply.
response#3responseobject__0
response#3response.successboolean__1Yes
response#3response.messagestring__2Yes