Engage

Queue a team engagement

Queues an explicitly approved teammate like, comment, reshare, or Slack share. LinkedIn reshares use normal post approvals; X reposts and quotes are refused for accounts that require approval. Reposts and quotes require a future scheduledTime; delivery waits for both that time and successful source publication.

POST/api/public/team-engagements

cURLPOST /api/public/team-engagements

curl -X POST https://postiv.ai/api/public/team-engagements \
  -H "Authorization: Bearer pk_postiv_..." \
  -H "Content-Type: application/json" \
  -d '{
    "postId": "...",
    "action": "like",
    "idempotencyKey": "..."
  }'

200Response

{
  "engagement": {
    "id": "22222222-2222-4222-8222-222222222222",
    "status": "waiting"
  }
}

Authorization

Requires an organization API key with the engage:write, posts:schedule scope, sent as Authorization: Bearer or x-api-key.

Body parameters

postIduuidrequired

Source Postiv post UUID.

actionstringrequired

Engagement to queue. quote is only for X posts.

One of:likecommentrepostquoteslack

integrationIdinteger

Acting LinkedIn profile/page, or the teammate's X account for X posts, for like, comment, repost, or quote. It must be on the post's channel. Required unless action is slack.

channelIdstring

Slack channel ID matching ^[CG][A-Z0-9]+$. Required when action is slack.

messagestringdefault: ""

Exact comment, reshare thought, quote text, or Slack text; trimmed and limited to 1250 characters. Required for comment and quote; forbidden for like and for reposts on X.

delayMinutesintegerdefault: 5

0–1440 minute delay for likes, comments, and Slack shares.

scheduledTimeISO 8601 datetime

Required when action is repost or quote. Must be at least two minutes in the future. The reshare, repost or quote waits beyond this time if the source has not published successfully.

idempotencyKeyuuidrequired

Reuse only for the identical request; changed fields return a conflict.

Response

The queued engagement reference.

engagement.iduuid

Public engagement UUID.

engagement.statusstring

Current queue or approval state.

Errors

400	Invalid JSON or schema validation failure
404	Post or acting account not found in this workspace
409	Idempotency key reused for a different request
422	Missing/invalid Slack channel, disconnected profile, missing recorded publication, or invalid engagement text
422	X_ACTION_NOT_AVAILABLE: like or comment on an X post (X supports repost and quote only)
422	x_share_requires_approval: the acting X account has approvers other than you, or is in client approval-link mode, so it cannot send a repost or quote

Good to know

Requires engage:write and posts:schedule. Reshare delayMinutes is ignored; the source post must be recorded as published.
X posts accept only repost, quote and slack. They run from the acting teammate's own X account at scheduledTime (once the post is live) and create no calendar post. A repost takes no message; a quote publishes the message followed by a link to the original post, which X shows as a quote, and must fit X's 280 characters (the link counts 23). like and comment on an X post return 422 X_ACTION_NOT_AVAILABLE; quote on a LinkedIn post returns 422. X reposts and quotes have no approval step: an X account that requires approval is refused with 422 x_share_requires_approval when queued, and a queued one is skipped (not sent) if the account gains an approver before it runs. LinkedIn reshares go through the account's normal approvals.