API resource

Mentions, reviews and labels

The rest of the inbox: mentions of your accounts in the last 7 days (LinkedIn organization mentions, Instagram comment and caption tags) and replies to them, Facebook Page reviews and replies, Messenger conversation labels, message requests (accept by replying), handover between apps, editing a comment, liking a post, deleting a conversation and a fresh URL for a message attachment (Meta expires DM media links).

List the Page's conversation labels

GET/v1/inbox/labels

Works on: Instagram, Facebook, LinkedIn

Facebook Messenger only. Lists the custom labels defined on the Page (Graph /{page-id}/custom_labels). Other platforms answer 400 platform_not_supported.

Query parameters

accountIdstringrequired

Facebook social account ID

curl "https://creatoros-production-5658.up.railway.app/v1/inbox/labels?accountId=acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "labels": [
    {
      "id": "string",
      "name": "string"
    }
  ]
}

Create a conversation label

POST/v1/inbox/labels

Works on: Instagram, Facebook, LinkedIn

Facebook Messenger only. Creates a custom label on the Page (Graph POST /{page-id}/custom_labels). Other platforms answer 400 platform_not_supported.

Body

accountIdstringrequired

Facebook social account ID

namestringrequired

Label name

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/inbox/labels" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
    "name": "string"
  }'
Response 200
{
  "label": {
    "id": "string",
    "name": "string"
  }
}

Delete a conversation label

DELETE/v1/inbox/labels/{labelId}

Works on: Instagram, Facebook, LinkedIn

Facebook Messenger only. Deletes a custom label from the Page (Graph DELETE /{label-id}), which also removes it from every conversation. The id must be one of the Page's custom labels, otherwise 404 resource_not_found. Other platforms answer 400 platform_not_supported.

Path parameters

labelIdstringrequired

Meta label id

Query parameters

accountIdstringrequired

Facebook social account ID

curl -X DELETE "https://creatoros-production-5658.up.railway.app/v1/inbox/labels/987654321098765?accountId=acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "success": true
}

List mentions

GET/v1/inbox/mentions

Works on: Instagram, Facebook, LinkedIn

Returns mentions of your connected accounts from the last 7 days. Requires Inbox addon. ### LinkedIn Organization mentions, delivered by webhooks and a background pull. ### Instagram Comment mentions (someone tags the account in a comment on their own media) and caption mentions (someone tags it in their media caption), delivered by the Meta mentions webhook. - Only accounts connected through Facebook Login receive them. - Comments on the account's own posts are never listed, even when they contain its @handle.

Query parameters

accountIdstring

Filter by account ID

sortOrderstring

Sort order by publishedAt One of: asc, desc.

limitinteger

cursorstring

Cursor for pagination (ID of the last item from the previous page)

curl "https://creatoros-production-5658.up.railway.app/v1/inbox/mentions" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "data": [
    {
      "id": "string",
      "platform": "social",
      "type": "caption",
      "mediaId": "18045678901234567",
      "postId": "post_V9cK2mQ7xL4pR8tN1wZ6bH3jF5dS0aG7eU2iO4kY9",
      "commentId": "17958467203124567",
      "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
      "accountUsername": "string",
      "content": "string",
      "contentNotRetained": true,
      "permalink": "string",
      "authorUrn": "string",
      "authorName": "string",
      "authorUsername": "string",
      "authorPicture": "string",
      "organizationalEntity": "string",
      "publishedAt": "2026-10-10T00:00:00.000Z",
      "createdAt": "2026-10-10T00:00:00.000Z"
    }
  ],
  "pagination": {
    "hasMore": true,
    "cursor": "string"
  },
  "meta": {
    "total": 0,
    "sortOrder": "asc"
  }
}

Reply to a mention

POST/v1/inbox/mentions/reply

Works on: Instagram, Facebook, LinkedIn

Reply to a mention of the connected account. Supported on Instagram only. Two shapes, selected by whether commentId is present: - Comment mention (someone @mentioned the account inside a comment): pass both mediaId and commentId. Instagram posts a reply under that comment. - Caption mention (someone @mentioned the account in their media caption, so no comment exists): pass mediaId only. Instagram posts a comment on their media. Story mentions are not supported by Instagram's API. GET /v1/inbox/mentions returns Instagram mentions with the mediaId and commentId to pass here.

Body

accountIdstringrequired

The Instagram account ID

mediaIdstringrequired

The ID of the media the account was mentioned in

commentIdstring

The mentioning comment's ID. Omit for a caption mention.

messagestringrequired

The reply text

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/inbox/mentions/reply" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
    "mediaId": "18045678901234567",
    "message": "string"
  }'
Response 200
{
  "success": true,
  "id": "string"
}

List reviews

GET/v1/inbox/reviews

Works on: Instagram, Facebook, LinkedIn

Fetch reviews from all connected Facebook Pages and Google Business Profile accounts. Aggregates data with filtering and sorting options. Supported platforms: Facebook, Google Business Profile. Each account's reviews are read from the platform page by page within a 20-second budget per request, so very large accounts can come back truncated. Each account's listing is cached for up to 60 seconds.

Query parameters

platformstring

One of: facebook, googlebusiness.

minRatinginteger

maxRatinginteger

hasReplyboolean

Filter by reply status

sortBystring

One of: date, rating.

sortOrderstring

One of: asc, desc.

limitinteger

cursorstring

accountIdstring

Filter by specific account ID

curl "https://creatoros-production-5658.up.railway.app/v1/inbox/reviews" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "status": "string",
  "data": [
    {
      "id": "string",
      "platform": "social",
      "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
      "accountUsername": "string",
      "locationId": "string",
      "locationName": "string",
      "reviewer": {
        "id": "string",
        "name": "string",
        "profileImage": "string"
      },
      "rating": 0,
      "recommendationType": "positive",
      "text": "string",
      "created": "2026-10-10T00:00:00.000Z",
      "hasReply": true,
      "hasPhotos": true,
      "photoCount": 0,
      "photos": [
        {}
      ],
      "reply": {
        "id": "string",
        "text": "string",
        "created": "2026-10-10T00:00:00.000Z"
      },
      "reviewUrl": "string"
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "string"
  },
  "meta": {
    "accountsQueried": 0,
    "accountsFailed": 0,
    "failedAccounts": [
      {
        "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
        "accountUsername": "string",
        "platform": "social",
        "error": "string",
        "code": "string",
        "retryAfter": 0
      }
    ],
    "lastUpdated": "2026-10-10T00:00:00.000Z",
    "accountsSkipped": [
      {
        "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
        "platform": "social"
      }
    ]
  },
  "summary": {
    "totalReviews": 0,
    "averageRating": 0
  }
}

Reply to review

POST/v1/inbox/reviews/{reviewId}/reply

Works on: Instagram, Facebook, LinkedIn

Post a reply to a review. Requires accountId in request body. ### Idempotency Send an Idempotency-Key header to make retries safe (e.g. after a client-side timeout where delivery is unknown). - Same key + same body: replays the original response (with Idempotent-Replayed: true) instead of sending the reply to the platform again. - Same key + different body: returns 422. - A key still in flight: returns 409. Keys are retained for 24 hours and are scoped to the credential and to this exact path.

Path parameters

reviewIdstringrequired

Review ID (URL-encoded for Google Business Profile)

Body

accountIdstringrequired

messagestringrequired

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/inbox/reviews/123456789012345/reply" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
    "message": "string"
  }'
Response 200
{
  "status": "string",
  "reply": {
    "id": "string",
    "text": "string",
    "contentNotRetained": true,
    "created": "2026-10-10T00:00:00.000Z"
  },
  "platform": "social"
}

Delete review reply

DELETE/v1/inbox/reviews/{reviewId}/reply

Works on: Instagram, Facebook, LinkedIn

Delete a reply to a review (Google Business Profile only). Requires accountId in request body.

Path parameters

reviewIdstringrequired

Body

accountIdstringrequired

curl -X DELETE "https://creatoros-production-5658.up.railway.app/v1/inbox/reviews/123456789012345/reply" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r"
  }'
Response 200
{
  "status": "string",
  "message": "string",
  "platform": "social"
}

Like post

POST/v1/inbox/posts/{postId}/like

Works on: Instagram, Facebook, LinkedIn

Like (or react to) a post as a connected account. ### Platform support - Supported: LinkedIn, X, Facebook, YouTube, Bluesky, and Instagram in limited release (see below). - Threads, TikTok and Pinterest expose no like endpoint in their APIs and return 400. - Reddit returns 400 too, pointing at POST /v1/accounts/{accountId}/reddit-vote, which covers upvote, downvote and clear on both posts and comments.

Path parameters

postIdstringrequired

Creator OS post ID or the platform's native post ID

Body

accountIdstringrequired

The account acting as the liker

reactionTypestring

(LinkedIn only) Reaction to create. Defaults to LIKE; ignored on other platforms.

cidstring

(Bluesky only) Content identifier of the post

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/inbox/posts/post_V9cK2mQ7xL4pR8tN1wZ6bH3jF5dS0aG7eU2iO4kY9/like" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r"
  }'
Response 200
{
  "status": "string",
  "postId": "post_V9cK2mQ7xL4pR8tN1wZ6bH3jF5dS0aG7eU2iO4kY9",
  "platform": "social",
  "liked": true,
  "likeUri": "string",
  "alreadyReacted": true,
  "reactionType": "string"
}

Unlike post

DELETE/v1/inbox/posts/{postId}/like

Works on: Instagram, Facebook, LinkedIn

Remove this account's like from a post. Supported platforms: LinkedIn, X, Facebook, YouTube, Bluesky, and Instagram in limited release. - YouTube: this clears the rating. - Instagram: has the same limited release, Facebook Login, instagram_manage_engagement and burst-limit constraints as liking. - Bluesky: likeUri (returned when the post was liked) is required. - Reddit: uses POST /v1/accounts/{accountId}/reddit-vote with direction: 0.

Path parameters

postIdstringrequired

Creator OS post ID or the platform's native post ID

Query parameters

accountIdstringrequired

likeUristring

(Bluesky only) The like URI returned when liking

curl -X DELETE "https://creatoros-production-5658.up.railway.app/v1/inbox/posts/post_V9cK2mQ7xL4pR8tN1wZ6bH3jF5dS0aG7eU2iO4kY9/like?accountId=acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "status": "string",
  "postId": "post_V9cK2mQ7xL4pR8tN1wZ6bH3jF5dS0aG7eU2iO4kY9",
  "platform": "social",
  "liked": true
}

Edit comment

PATCH/v1/inbox/comments/{postId}/{commentId}

Works on: Instagram, Facebook, LinkedIn

Edit the body of a comment the connected account posted. Supported on Reddit only. Reddit keeps the same comment id after an edit. Reddit exposes no API to edit a post title, and a link post has no editable body. To edit a published post's body, use POST /v1/posts/{postId}/edit.

Path parameters

postIdstringrequired

commentIdstringrequired

Body

accountIdstringrequired

The account ID

platformstringrequired

Only Reddit supports editing a comment

contentstringrequired

The new comment body

curl -X PATCH "https://creatoros-production-5658.up.railway.app/v1/inbox/comments/post_V9cK2mQ7xL4pR8tN1wZ6bH3jF5dS0aG7eU2iO4kY9/17958467203124567" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
    "platform": "social",
    "content": "string"
  }'
Response 200
{
  "status": "string",
  "commentId": "17958467203124567",
  "platform": "social"
}

Delete conversation

DELETE/v1/inbox/conversations/{conversationId}

Works on: Instagram, Facebook, LinkedIn

Permanently deletes Creator OS's stored copy of one conversation and every message in it, in one transaction, and unlinks the contact channel that pointed at it. ### What is kept - Nothing is deleted on the platform (the thread stays in WhatsApp, Messenger or Instagram). - The contact record is kept: call DELETE /v1/contacts/{contactId} to erase the person's name and number as well. Inbound media copies Creator OS stored are removed on a best-effort basis.

Path parameters

conversationIdstringrequired

Opaque conversation identifier, accepted verbatim from the list endpoint or from the conversationId on inbox webhooks. Format not to be assumed.

Query parameters

accountIdstringrequired

Account ID

curl -X DELETE "https://creatoros-production-5658.up.railway.app/v1/inbox/conversations/conv_M4nB7vC1xZ9lK3jH6gF2dS8aP5oI0uY7tR4eW1qQ6?accountId=acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "success": true,
  "data": {
    "id": "string",
    "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
    "platform": "social",
    "deletedMessages": 0
  }
}

Change who answers a conversation (handover)

POST/v1/inbox/conversations/{conversationId}/thread-control

Works on: Instagram, Facebook, LinkedIn

Changes who answers a conversation: Meta Business Agent handover on WhatsApp, Meta's conversation routing on Facebook and Instagram. On Instagram, Conversation Routing replaced the Handover Protocol in October 2025 and kept the thread-control calls below. WhatsApp, on numbers with Meta Business Agent enabled: - release: hand the conversation back to the agent so it resumes answering. You must currently hold control (sending any message takes it implicitly). - take: take control before sending anything, so the agent stops replying while an operator reads the thread.

Path parameters

conversationIdstringrequired

The conversation ID

Body

accountIdstringrequired

Social account ID

actionstringrequired

request is Facebook and Instagram only. take and request are refused with platform_not_supported on Instagram accounts connected with Instagram Login.

targetstring

WhatsApp only. With action pass: send control to Meta Business Agent instead of the escalation partner.

targetAppIdstring

Facebook and Instagram only, required with action pass: the Meta app id receiving the thread.

metadatastring

Free-form note forwarded verbatim to the app receiving control (its messaging_handovers webhook).

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/inbox/conversations/conv_M4nB7vC1xZ9lK3jH6gF2dS8aP5oI0uY7tR4eW1qQ6/thread-control" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
    "action": "release"
  }'
Response 200
{
  "success": true,
  "control": {
    "owner": "app",
    "ownerAppId": "string"
  }
}

Accept a message request

POST/v1/inbox/conversations/{conversationId}/accept

Works on: Instagram, Facebook, LinkedIn

Accept a Facebook or Instagram Message Request by replying to it. Facebook Page requests are listed with GET /v1/inbox/conversations?folder=requests; Instagram answers PLATFORM_LIMITATION there. Meta has no separate accept call: the first reply is what moves the thread into the inbox. So this sends message through the same path, checks and webhooks as POST /v1/inbox/conversations/{conversationId}/messages, and answers the same way. Supports the Idempotency-Key header.

Path parameters

conversationIdstringrequired

The id of the request item from the requests folder.

Body

accountIdstringrequired

Facebook or Instagram social account ID

messagestringrequired

The reply that accepts the request

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/inbox/conversations/conv_M4nB7vC1xZ9lK3jH6gF2dS8aP5oI0uY7tR4eW1qQ6/accept" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
    "message": "string"
  }'
Response 200
{
  "success": true,
  "data": {
    "messageId": "msg_Q8wE3rT6yU1iO4pA7sD2fG9hJ5kL0zX3cV6bN8mM1"
  }
}

List the labels on a conversation

GET/v1/inbox/conversations/{conversationId}/labels

Works on: Instagram, Facebook, LinkedIn

Facebook Messenger only. Lists the Page's custom labels applied to the person in this conversation (Graph /{psid}/custom_labels). Other platforms answer 400 platform_not_supported.

Path parameters

conversationIdstringrequired

Conversation ID (Creator OS id or Meta platform conversation id)

Query parameters

accountIdstringrequired

Facebook social account ID

curl "https://creatoros-production-5658.up.railway.app/v1/inbox/conversations/conv_M4nB7vC1xZ9lK3jH6gF2dS8aP5oI0uY7tR4eW1qQ6/labels?accountId=acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "labels": [
    {
      "id": "string",
      "name": "string"
    }
  ]
}

Add a label to a conversation

POST/v1/inbox/conversations/{conversationId}/labels

Works on: Instagram, Facebook, LinkedIn

Facebook Messenger only. Applies one of the Page's custom labels to the person in this conversation (Graph POST /{label-id}/label?user={psid}). The id must be one of the Page's custom labels, otherwise 404 resource_not_found. Other platforms answer 400 platform_not_supported.

Path parameters

conversationIdstringrequired

Conversation ID (Creator OS id or Meta platform conversation id)

Body

accountIdstringrequired

Facebook social account ID

labelIdstringrequired

Meta label id from listInboxLabels

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/inbox/conversations/conv_M4nB7vC1xZ9lK3jH6gF2dS8aP5oI0uY7tR4eW1qQ6/labels" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
    "labelId": "987654321098765"
  }'
Response 200
{
  "success": true
}

Remove a label from a conversation

DELETE/v1/inbox/conversations/{conversationId}/labels/{labelId}

Works on: Instagram, Facebook, LinkedIn

Facebook Messenger only. Removes one of the Page's custom labels from the person in this conversation (Graph DELETE /{label-id}/label?user={psid}). The label itself stays on the Page. The id must be one of the Page's custom labels, otherwise 404 resource_not_found. Other platforms answer 400 platform_not_supported.

Path parameters

conversationIdstringrequired

Conversation ID (Creator OS id or Meta platform conversation id)

labelIdstringrequired

Meta label id

Query parameters

accountIdstringrequired

Facebook social account ID

curl -X DELETE "https://creatoros-production-5658.up.railway.app/v1/inbox/conversations/conv_M4nB7vC1xZ9lK3jH6gF2dS8aP5oI0uY7tR4eW1qQ6/labels/987654321098765?accountId=acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "success": true
}

Resolve message attachment

GET/v1/inbox/conversations/{conversationId}/messages/{messageId}/attachments/{index}

Works on: Instagram, Facebook, LinkedIn

Resolve one attachment on a message to a media url that works right now. ### Why it exists Instagram and Facebook sign DM media urls per request and expire them. So the url on a message is a snapshot: it works when you read the message and stops working later. This endpoint checks the stored url and, when it has gone stale, re-mints the message's media from Meta and persists it before answering. The message id never expires, so this URL is the one to store. It is returned ready-made on each attachment as refreshUrl when you read a message over REST.

Path parameters

conversationIdstringrequired

The conversation ID (Creator OS id or platform conversation id)

messageIdstringrequired

The message id as returned by the list-messages endpoint (the platform message id)

indexintegerrequired

Zero-based position of the attachment in the message's attachments array

Query parameters

accountIdstringrequired

Account ID. Required: without it the request returns 400 missing_required_field.

formatstring

redirect (default) answers 302 to the media; json returns the url in the body One of: redirect, json.

curl "https://creatoros-production-5658.up.railway.app/v1/inbox/conversations/conv_M4nB7vC1xZ9lK3jH6gF2dS8aP5oI0uY7tR4eW1qQ6/messages/msg_Q8wE3rT6yU1iO4pA7sD2fG9hJ5kL0zX3cV6bN8mM1/attachments/0?accountId=acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "status": "success",
  "url": "string",
  "refreshed": true
}