Engagement

All write actions need a published destination. Wallet charges follow X list prices (pass-through).

Request shape

POST body: { "destinationId": "…" } (comments also need text, optional parentCommentId)
DELETE query: ?destinationId=
GET list endpoints: ?destinationId= (+ optional cursor, limit)

Retweets

Method	Path
GET	`/v1/posts/:id/retweets`
POST	`/v1/posts/:id/retweets`
DELETE	`/v1/posts/:id/retweets?destinationId=`

Requires tweet.read + tweet.write + users.read.

Notes

Create often succeeds without a separate retweet id — that is success
List who retweeted can be unavailable on some product tracks; prefer insights shares for counts
Missing write scope → RETWEET_PERMISSION / reconnect

Likes

Method	Path
POST	`/v1/posts/:id/likes`
DELETE	`/v1/posts/:id/likes?destinationId=`

Requires like.write (and typically like.read / users.read). Missing scope → ENGAGEMENT_PERMISSION — reconnect X.

Bookmarks

Method	Path
POST	`/v1/posts/:id/bookmarks`
DELETE	`/v1/posts/:id/bookmarks?destinationId=`

Requires bookmark.write. Same reconnect rule as likes.

Comments (replies)

Method	Path
GET	`/v1/posts/:id/comments`
POST	`/v1/posts/:id/comments`
DELETE	`/v1/posts/:id/comments/:commentId?destinationId=`

List

Excludes the root tweet; returns replies in the conversation
Limited to a recent search window (X access-level dependent)
Pagination via nextCursor / next_token

Create

curl -X POST https://api.onepostly.com/v1/posts/POST_ID/comments \
  -H "x-api-key: op_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationId": "DEST_ID",
    "text": "Thanks for reading",
    "parentCommentId": "OPTIONAL_PARENT_REPLY_ID"
  }'

Default parent = root published tweet
Max 280 characters
Billed like an X post create (pricing; URL surcharge when applicable)

Delete

Deletes a reply owned by the connected account (commentId = that reply’s id on X).

Quote (engagement entry)

Quoting an already-published Onepostly destination:

curl -X POST https://api.onepostly.com/v1/posts/POST_ID/quotes \
  -H "x-api-key: op_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"destinationId":"DEST_ID","text":"My take"}'

Creates a new post + destination. Details: Posts → Quote.

Common errors

Code	Meaning
`MISSING_EXTERNAL_ID`	Destination not published / no tweet id
`ENGAGEMENT_PERMISSION` / `*_PERMISSION`	Missing OAuth scope → reconnect
`INSUFFICIENT_WALLET`	Onepostly wallet empty
`RETWEETS_UNSUPPORTED` / `COMMENTS_UNSUPPORTED`	X product track / access level