Creator OSDocs

API resource

Direct messages

List conversations

GET/v1/inbox/conversations

Works on: Instagram, Facebook, X

DM threads across every account, most recently active first. Paginate with cursor.

Query parameters

platformstring

Only this network.

accountIdstring

Only this account.

statusstring

active or archived.

limitinteger

Page size.

cursorstring

pagination.nextCursor from the previous page.

curl "https://creatoros-production-5658.up.railway.app/v1/inbox/conversations?status=active&limit=20" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "data": [
    {
      "id": "conv_9WFW-MsJBK43x7I-Ij21W7ZmevMKhsEYFQ2Bv8Kx5Rt",
      "platform": "instagram",
      "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
      "accountUsername": "kevbuildsapps",
      "participantName": "Maya",
      "lastMessage": "Is the course still open?",
      "updatedTime": "2026-09-25T17:02:10.000Z",
      "status": "active",
      "unreadCount": 1
    }
  ],
  "pagination": {
    "hasMore": false,
    "nextCursor": null
  }
}

List messages

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

Works on: Instagram, Facebook, X

Messages in one thread, oldest first by default.

Path parameters

conversationIdstringrequired

The conv_ id.

Query parameters

accountIdstringrequired

The account (acc_...) the post or conversation belongs to.

limitinteger

Up to 100.

cursorstring

pagination.nextCursor from the previous page.

sortOrderstring

asc (default) or desc.

curl "https://creatoros-production-5658.up.railway.app/v1/inbox/conversations/conv_9WFW-MsJBK43x7I-Ij21W7ZmevMKhsEYFQ2Bv8Kx5Rt/messages?accountId=acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "status": "success",
  "pagination": {
    "hasMore": false,
    "nextCursor": null
  },
  "messages": [
    {
      "id": "msg_Hk2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9X",
      "conversationId": "conv_9WFW-MsJBK43x7I-Ij21W7ZmevMKhsEYFQ2Bv8Kx5Rt",
      "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
      "platform": "instagram",
      "message": "Is the course still open?",
      "senderName": "Maya",
      "direction": "incoming",
      "createdAt": "2026-09-25T17:02:10.000Z",
      "attachments": []
    }
  ]
}

Send a message

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

Works on: Instagram, Facebook, X

Replies in the thread. Attach one file with attachmentUrl, which can be a med_ id from Upload media.

Path parameters

conversationIdstringrequired

The conv_ id.

Body

accountIdstringrequired

The account (acc_...) the post or conversation belongs to.

messagestring

Message text. Required unless attaching.

attachmentUrlstring

A med_ id or public URL.

attachmentTypestring

image, video, audio or file.

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/inbox/conversations/conv_9WFW-MsJBK43x7I-Ij21W7ZmevMKhsEYFQ2Bv8Kx5Rt/messages" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
    "message": "It is! Enrollment closes Friday. Want the link?"
  }'
Response 200
{
  "success": true,
  "data": {
    "messageId": "msg_Hk2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9X",
    "conversationId": "conv_9WFW-MsJBK43x7I-Ij21W7ZmevMKhsEYFQ2Bv8Kx5Rt"
  }
}

Mark as read

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

Works on: Instagram, Facebook, X

Clears the unread count for a conversation.

Path parameters

conversationIdstringrequired

The conv_ id.

Body

accountIdstringrequired

The account (acc_...) the post or conversation belongs to.

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

Archive a conversation

PUT/v1/inbox/conversations/{conversationId}

Works on: Instagram, Facebook, X

Set status to archived to file a thread away, or active to bring it back.

Path parameters

conversationIdstringrequired

The conv_ id.

Body

accountIdstringrequired

The account (acc_...) the post or conversation belongs to.

statusstringrequired

active or archived.

curl -X PUT "https://creatoros-production-5658.up.railway.app/v1/inbox/conversations/conv_9WFW-MsJBK43x7I-Ij21W7ZmevMKhsEYFQ2Bv8Kx5Rt" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
    "status": "archived"
  }'
Response 200
{
  "success": true
}
PreviousCommentsNextValidation