Skip to content

Delete Post API Reference

The Delete Post API removes a post by its identifier. Send a DELETE request to {{API_BASE_URL}}/v1/posts/{postId}, where postId is the required post identifier in the path. By default, only the post record is deleted. Set the optional deleteFromPlatforms query parameter to true when you also want supported published platform posts to be deleted, understanding that each successful platform deletion costs 1 credit.

Delete a post by ID — operation summary and exact request line

Use this operation when a post record should be removed by its ID. The request line is DELETE {{API_BASE_URL}}/v1/posts/{postId}. Replace postId with the identifier of the post to delete. The operation has no request body in the captured contract; its inputs are the path parameter, the optional query parameter, and the authorization header described below. Before calling it, confirm you have the correct postId, because the captured contract does not describe a separate confirmation or undo step.

Authorization — x-access-key header

Every request must include the access key in the x-access-key header. Send the header as x-access-key with a <token> value. If the header is missing or invalid, the captured contract does not specify a dedicated authentication failure status, so your client should treat any non-success response by parsing its JSON body and surfacing the message field rather than assuming a particular status meaning.

Path Parameters — postId (required string)

The path contains one required parameter. postId is a required string and is the post identifier. It is placed directly in the path segment after /v1/posts/. URL-encode the value if the identifier contains characters that require encoding, and verify the final URL still matches the pattern {{API_BASE_URL}}/v1/posts/{postId} before sending the request.

Query Parameters — deleteFromPlatforms (optional boolean, default false)

The query string accepts one optional parameter. deleteFromPlatforms is an optional boolean that defaults to false. When it is false or omitted, only the post is deleted. When it is true, supported published platform posts are also deleted, and each successful platform deletion costs 1 credit. Use true only when removing the published copies is intended, and budget credits accordingly; use false or omit the parameter when you want to keep the published platform posts.

Response Body — 200 with creditsCharged and platforms array

A successful deletion returns a 200 response with an application/json body. The body always includes success as a required boolean. It may also include creditsCharged as an optional integer with a value of 0 or greater, reporting the credits charged for the operation, and platforms as an optional array of per-platform results. Parse creditsCharged to reconcile credit usage, and iterate platforms to check each platform outcome individually instead of relying only on the top-level success value.

Per-platform results — platform, integrationId, platformPostId, status, success, message, errorMessage

Each entry in the platforms array describes one platform result. platform, integrationId, platformPostId, status, and success are required fields, with platformPostId typed as string or null. message and errorMessage are optional string fields. Use integrationId to identify which integration the result belongs to, platformPostId to identify the published post on that platform when present, and errorMessage to diagnose a platform entry whose success value is false. A top-level success of true does not by itself prove every platform entry succeeded, so check each entry.

Error responses — 402, 404 and 409 shapes as captured

The endpoint also returns 402, 404, and 409 responses, each with an application/json body containing success and message. In the captured contract, all three error responses share the same shape: success is a required boolean and message is a required string. Your client should branch on the HTTP status code, read the message field for the reason, and avoid assuming additional fields that are not part of the captured shape. The captured source does not label a distinct message or semantic for each of these statuses, so do not hard-code per-status explanations beyond the returned message.

Worked cURL example and response parsing notes

To implement the call, build the URL from {{API_BASE_URL}} plus /v1/posts/{postId}, append ?deleteFromPlatforms=true only when platform deletion is intended, add the x-access-key header, and send the DELETE request. The worked cURL examples below show both the default form and the platform-deletion form. After the call, check the status code first: on 200, parse creditsCharged and the platforms array; on 402, 404, or 409, parse success and message. Log the postId, the deleteFromPlatforms value, the status code, and the parsed fields so a failed deletion can be diagnosed without retrying blindly.

Request parameters
NameLocationTypeRequiredDefaultDescription
postIdPathstringYes—Post identifier
deleteFromPlatformsQuerybooleanNofalseWhen true, also delete supported published platform posts. Costs 1 credit per successful platform deletion.
x-access-keyHeaderstring (<token>)Yes—Authorization header

Exact captured contract; origin modularised as {{API_BASE_URL}}.

Response body by status
StatusContent typesuccesscreditsChargedplatformsmessage
200application/jsonboolean, requiredinteger, optional, 0 <= valuearray<object>, optional—
402application/jsonboolean, required——string, required
404application/jsonboolean, required——string, required
409application/jsonboolean, required——string, required

Error bodies for 402, 404 and 409 are identical in the captured source and are not labelled per status; no per-status semantics invented.

Platforms array entry fields
FieldTypeRequiredDescription
platformstringYesPlatform name for this result
integrationIdstringYesIntegration identifier for this result
platformPostIdstring | nullYesPublished post identifier on the platform, or null
statusstringYesStatus for this platform result
successbooleanYesWhether this platform deletion succeeded
messagestringNoOptional message for this platform result
errorMessagestringNoOptional error message for this platform result

Per-platform entry inside the 200 platforms array.

Delete a post by ID request
curl -X DELETE "{{API_BASE_URL}}/v1/posts/{postId}" \
  -H "x-access-key: <token>"
Delete a post and supported published platform posts
curl -X DELETE "{{API_BASE_URL}}/v1/posts/{postId}?deleteFromPlatforms=true" \
  -H "x-access-key: <token>"
200 success response example
{
  "success": true,
  "creditsCharged": 0,
  "platforms": [
    {
      "platform": "string",
      "integrationId": "string",
      "platformPostId": "string",
      "status": "string",
      "success": true,
      "message": "string",
      "errorMessage": "string"
    }
  ]
}
Error response example for 402, 404 and 409
{
  "success": true,
  "message": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
postId#1postIdstring__0YesPost identifier
deleteFromPlatforms#2deleteFromPlatformsboolean__0NoWhen true, also delete supported published platform posts. Costs 1 credit per successful platform deletion.kind: schemaDefault; value: false
response#3responseobject__0
response#3response.successboolean__1Yes
response#3response.creditsChargedinteger__2Nokind: ; value: 0 <= value
response#3response.platformsarray<object>__3No
response#3response.platforms[]object__4
response#3response.platforms[].platformstring__5Yes
response#3response.platforms[].integrationIdstring__6Yes
response#3response.platforms[].platformPostIdstring | null__7Yes
response#3response.platforms[].platformPostId[variant1]string__7_type:string
response#3response.platforms[].platformPostId[variant2]null__7_type:null
response#3response.platforms[].statusstring__8Yes
response#3response.platforms[].successboolean__9Yes
response#3response.platforms[].messagestring__10No
response#3response.platforms[].errorMessagestring__11No
response#4responseobject__0
response#4response.successboolean__1Yes
response#4response.messagestring__2Yes