Skip to main content
POST
/
api
/
v4
/
posts
create a post
curl --request POST \
  --url https://apix.us.amity.co/api/v4/posts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "data": {
    "title": "<string>",
    "text": "example text",
    "streamId": "81559bcc3a5bb3b6bbd69a83b89d337e",
    "pollId": "53a9fd8b5aaa1af6c5a1bbd245ce4a9b1627373735551"
  },
  "attachments": [
    {
      "fileId": "57b916d38eaf8010caddfb7759a2d06c",
      "type": "image",
      "displayMode": "fill",
      "isMuted": "true"
    }
  ],
  "dataType": "upstra.customtype",
  "targetType": "user",
  "targetId": "public_user_id",
  "metadata": {
    "anything": "you want"
  },
  "postId": "postidiwant",
  "tags": [
    "<string>"
  ],
  "hashtags": [
    "tech_news",
    "startup_life",
    "product_launch",
    "innovation_2025"
  ],
  "mentionees": [
    {
      "type": "user",
      "userIds": [
        "userId1",
        "userId2"
      ]
    }
  ],
  "createdAt": "2022-07-07T04:24:20.444Z",
  "isDiscoverable": true
}'
{
  "posts": [
    {
      "_id": "<string>",
      "path": "<string>",
      "postId": "<string>",
      "parentPostId": "<string>",
      "postedUserId": "<string>",
      "postedUserPublicId": "<string>",
      "postedUserInternalId": "<string>",
      "publisherId": "<string>",
      "publisherPublicId": "<string>",
      "sharedUserId": "<string>",
      "sharedCount": 123,
      "targetId": "<string>",
      "targetPublicId": "<string>",
      "targetInternalId": "<string>",
      "targetType": "user",
      "dataType": "text",
      "data": {
        "title": "<string>",
        "text": "<string>",
        "fileId": "<string>",
        "thumbnailFileId": "<string>",
        "videoFileId": {
          "original": "<string>",
          "low": "<string>",
          "medium": "<string>",
          "high": "<string>"
        },
        "streamId": "<string>"
      },
      "metadata": {},
      "flagCount": 123,
      "hashFlag": {
        "bits": 123,
        "hashes": 123,
        "hash": [
          "<string>"
        ]
      },
      "editedAt": "2023-11-07T05:31:56Z",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "reactions": {
        "like": 1
      },
      "reactionsCount": 1,
      "myReactions": [
        "like"
      ],
      "commentsCount": 1,
      "comments": [
        "<string>"
      ],
      "children": [
        "<string>"
      ],
      "childrenNumber": 123,
      "isDeleted": false,
      "hasFlaggedComment": false,
      "hasFlaggedChildren": false,
      "feedId": "<string>",
      "tags": [
        "<string>"
      ],
      "hashtags": [
        "video_content",
        "clips_feature",
        "multimedia_posts",
        "next_gen_social"
      ],
      "mentionees": [
        {
          "type": "user",
          "userIds": [
            "<string>"
          ],
          "userPublicIds": [
            "<string>"
          ],
          "userInternalIds": [
            "<string>"
          ]
        }
      ],
      "impression": 123,
      "reach": 123
    }
  ],
  "postChildren": [
    {
      "_id": "<string>",
      "path": "<string>",
      "postId": "<string>",
      "parentPostId": "<string>",
      "postedUserId": "<string>",
      "postedUserPublicId": "<string>",
      "postedUserInternalId": "<string>",
      "publisherId": "<string>",
      "publisherPublicId": "<string>",
      "sharedUserId": "<string>",
      "sharedCount": 123,
      "targetId": "<string>",
      "targetPublicId": "<string>",
      "targetInternalId": "<string>",
      "targetType": "user",
      "dataType": "text",
      "data": {
        "title": "<string>",
        "text": "<string>",
        "fileId": "<string>",
        "thumbnailFileId": "<string>",
        "videoFileId": {
          "original": "<string>",
          "low": "<string>",
          "medium": "<string>",
          "high": "<string>"
        },
        "streamId": "<string>"
      },
      "metadata": {},
      "flagCount": 123,
      "hashFlag": {
        "bits": 123,
        "hashes": 123,
        "hash": [
          "<string>"
        ]
      },
      "editedAt": "2023-11-07T05:31:56Z",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "reactions": {
        "like": 1
      },
      "reactionsCount": 1,
      "myReactions": [
        "like"
      ],
      "commentsCount": 1,
      "comments": [
        "<string>"
      ],
      "children": [
        "<string>"
      ],
      "childrenNumber": 123,
      "isDeleted": false,
      "hasFlaggedComment": false,
      "hasFlaggedChildren": false,
      "feedId": "<string>",
      "tags": [
        "<string>"
      ],
      "hashtags": [
        "mobile_app",
        "user_experience",
        "API_v4",
        "social_platform"
      ],
      "mentionees": [
        {
          "type": "user",
          "userIds": [
            "<string>"
          ],
          "userPublicIds": [
            "<string>"
          ],
          "userInternalIds": [
            "<string>"
          ]
        }
      ],
      "impression": 123,
      "reach": 123
    }
  ],
  "comments": [
    {
      "_id": "<string>",
      "path": "<string>",
      "commentId": "<string>",
      "userId": "<string>",
      "userPublicId": "<string>",
      "userInternalId": "<string>",
      "parentId": "<string>",
      "rootId": "<string>",
      "referenceId": "<string>",
      "referenceType": "post",
      "dataType": "<string>",
      "dataTypes": [
        "text"
      ],
      "data": {},
      "metadata": {},
      "childrenNumber": 123,
      "flagCount": 123,
      "hashFlag": {
        "bits": 123,
        "hashes": 123,
        "hash": [
          "<string>"
        ]
      },
      "reactions": {
        "like": 1
      },
      "reactionsCount": 1,
      "myReactions": [
        "like"
      ],
      "isDeleted": false,
      "editedAt": "2023-11-07T05:31:56Z",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "children": [
        "<string>"
      ],
      "segmentNumber": 1,
      "mentionees": [
        {
          "type": "user",
          "userIds": [
            "<string>"
          ],
          "userPublicIds": [
            "<string>"
          ],
          "userInternalIds": [
            "<string>"
          ]
        }
      ],
      "attachments": [
        {
          "type": "image",
          "fileId": "<string>"
        }
      ],
      "targetId": "<string>",
      "targetType": "community"
    }
  ],
  "users": [
    {
      "_id": "<string>",
      "path": "<string>",
      "userId": "<string>",
      "userInternalId": "<string>",
      "userPublicId": "<string>",
      "roles": [
        "<string>"
      ],
      "permissions": [
        "MUTE_CHANNEL"
      ],
      "displayName": "<string>",
      "profileHandle": "<string>",
      "description": "<string>",
      "avatarFileId": "<string>",
      "avatarCustomUrl": "<string>",
      "flagCount": 123,
      "hashFlag": {
        "bits": 123,
        "hashes": 123,
        "hash": [
          "<string>"
        ]
      },
      "metadata": {},
      "isGlobalBan": true,
      "isBrand": true,
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "isDeleted": true
    }
  ],
  "roles": [
    {
      "roleId": "<string>",
      "displayName": "<string>",
      "updatedAt": "2023-11-07T05:31:56Z",
      "createdAt": "2023-11-07T05:31:56Z",
      "permissions": [
        "<string>"
      ],
      "isDeleted": false
    }
  ],
  "files": [
    {
      "fileId": "<string>",
      "fileUrl": "<string>",
      "type": "image",
      "accessType": "public",
      "altText": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "attributes": {
        "name": "<string>",
        "extension": "<string>",
        "size": 123,
        "mimeType": "<string>",
        "metadata": {
          "exif": {},
          "gps": {},
          "height": 123,
          "width": 123,
          "isFull": true
        }
      }
    }
  ],
  "communities": [
    {
      "_id": "<string>",
      "path": "<string>",
      "communityId": "<string>",
      "channelId": "<string>",
      "userId": "<string>",
      "userPublicId": "<string>",
      "userInternalId": "<string>",
      "displayName": "<string>",
      "avatarFileId": "<string>",
      "description": "<string>",
      "isOfficial": true,
      "isPublic": true,
      "onlyAdminCanPost": true,
      "tags": [
        "<string>"
      ],
      "metadata": {},
      "postsCount": 123,
      "membersCount": 123,
      "isJoined": true,
      "categoryIds": [
        "<string>"
      ],
      "isDeleted": false,
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "hasFlaggedComment": false,
      "hasFlaggedPost": false,
      "needApprovalOnPostCreation": false,
      "moderatorMemberCount": 123,
      "allowCommentInStory": true,
      "isDiscoverable": false,
      "requiresJoinApproval": false,
      "notificationMode": "default"
    }
  ],
  "communityUsers": [
    {
      "userId": "<string>",
      "userPublicId": "<string>",
      "userInternalId": "<string>",
      "channelId": "<string>",
      "communityId": "<string>",
      "communityMembership": "none",
      "notMemberReason": "<string>",
      "isBanned": false,
      "lastActivity": "2023-11-07T05:31:56Z",
      "roles": [
        "<string>"
      ],
      "permissions": [
        "MUTE_CHANNEL"
      ],
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "categories": [
    {
      "categoryId": "<string>",
      "name": "<string>",
      "metadata": {},
      "avatarFileId": "<string>",
      "isDeleted": false,
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "feeds": [
    {
      "targetId": "<string>",
      "targetType": "community",
      "postCount": 123,
      "feedType": "published",
      "feedId": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "videoStreamings": [
    {
      "streamId": "<string>",
      "userId": "<string>",
      "userInternalId": "64be1f6cb9b4106b5a6bbf3f",
      "userPublicId": "User123",
      "thumbnailFileId": "<string>",
      "title": "<string>",
      "status": "idle",
      "isLive": true,
      "isDeleted": true,
      "description": "<string>",
      "platform": {
        "name": "<string>",
        "version": "<string>"
      },
      "moderationId": "<string>",
      "startedAt": "2023-11-07T05:31:56Z",
      "endedAt": "2023-11-07T05:31:56Z",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "metadata": {},
      "resolution": "SD",
      "streamerUrl": {
        "url": "<string>",
        "components": {
          "origin": "<string>",
          "appName": "<string>",
          "streamName": "<string>",
          "query": "<string>"
        }
      },
      "recordings": [
        {
          "flv": {
            "url": "<string>",
            "duration": 123,
            "startTime": 123,
            "stopTime": 123
          },
          "mp4": {
            "url": "<string>",
            "duration": 123,
            "startTime": 123,
            "stopTime": 123
          },
          "m3u8": {
            "url": "<string>",
            "duration": 123,
            "startTime": 123,
            "stopTime": 123
          }
        }
      ],
      "watcherUrl": {
        "flv": {
          "url": "<string>",
          "components": {
            "origin": "<string>",
            "appName": "<string>",
            "streamName": "<string>",
            "query": "<string>"
          }
        },
        "hls": {
          "url": "<string>",
          "components": {
            "origin": "<string>",
            "appName": "<string>",
            "streamName": "<string>",
            "query": "<string>"
          }
        },
        "rtmp": {
          "url": "<string>",
          "components": {
            "origin": "<string>",
            "appName": "<string>",
            "streamName": "<string>",
            "query": "<string>"
          }
        }
      },
      "postId": "<string>",
      "channelId": "<string>",
      "channelEnabled": true,
      "isParent": false,
      "parentStreamId": "<string>",
      "childStreamIds": []
    }
  ],
  "videoStreamingChildren": [
    {
      "streamId": "<string>",
      "userId": "<string>",
      "userInternalId": "64be1f6cb9b4106b5a6bbf3f",
      "userPublicId": "User123",
      "thumbnailFileId": "<string>",
      "title": "<string>",
      "status": "idle",
      "isLive": true,
      "isDeleted": true,
      "description": "<string>",
      "platform": {
        "name": "<string>",
        "version": "<string>"
      },
      "moderationId": "<string>",
      "startedAt": "2023-11-07T05:31:56Z",
      "endedAt": "2023-11-07T05:31:56Z",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "metadata": {},
      "resolution": "SD",
      "streamerUrl": {
        "url": "<string>",
        "components": {
          "origin": "<string>",
          "appName": "<string>",
          "streamName": "<string>",
          "query": "<string>"
        }
      },
      "recordings": [
        {
          "flv": {
            "url": "<string>",
            "duration": 123,
            "startTime": 123,
            "stopTime": 123
          },
          "mp4": {
            "url": "<string>",
            "duration": 123,
            "startTime": 123,
            "stopTime": 123
          },
          "m3u8": {
            "url": "<string>",
            "duration": 123,
            "startTime": 123,
            "stopTime": 123
          }
        }
      ],
      "watcherUrl": {
        "flv": {
          "url": "<string>",
          "components": {
            "origin": "<string>",
            "appName": "<string>",
            "streamName": "<string>",
            "query": "<string>"
          }
        },
        "hls": {
          "url": "<string>",
          "components": {
            "origin": "<string>",
            "appName": "<string>",
            "streamName": "<string>",
            "query": "<string>"
          }
        },
        "rtmp": {
          "url": "<string>",
          "components": {
            "origin": "<string>",
            "appName": "<string>",
            "streamName": "<string>",
            "query": "<string>"
          }
        }
      },
      "postId": "<string>",
      "channelId": "<string>",
      "channelEnabled": true,
      "isParent": false,
      "parentStreamId": "<string>",
      "childStreamIds": []
    }
  ],
  "polls": [
    {
      "pollId": "<string>",
      "userId": "<string>",
      "userInternalId": "64be1f6cb9b4106b5a6bbf3f",
      "userPublicId": "User123",
      "title": "<string>",
      "question": "<string>",
      "answers": [
        {
          "dataType": "text",
          "data": "<string>",
          "fileId": "<string>",
          "voteCount": 0,
          "isVotedByUser": false,
          "id": "<string>"
        }
      ],
      "answerType": "<string>",
      "closedAt": "<string>",
      "createdAt": "<string>",
      "isVoted": false,
      "status": "open",
      "closedIn": 123
    }
  ]
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

information of a post to be created.

require text or at least 1 attachments

Custom post

  • When dataType is set as the custom name (dot separated string format, see the dataType field section), data payload can be anything but it will not support normal data capability (ex. text data will not be created) and data payload size will be limit to 100kb
  • attachments will be ignored, users need to keep them in data field and handle the file info by themselves

Image, File, Video post

  • Put type with file id in attachments
  • Image and File data can be picked from fileId in data object in child post
  • Video fileId for each resolution will be in videoFileId in data object in child post

Live streaming post

  • When put dataType as liveStream and streamId in data, post will be created as live streaming post
  • attachments will be ignored
  • Video streaming info will be in videoStreamings object in response

Poll post

  • When put dataType as poll and pollId in data, post will be created as poll post
  • attachments will be ignored
  • Poll info will be in polls object in response

Clip post

  • Put type = clip with fileId (from POST /v4/clips) in attachments
  • Optionally we can add isMuted on the attachment to set the clip to mute for displaying on UI.
  • Optionally we can add displayMode on the attachment to set the clip displayMode for displaying on UI.
  • fileId, isMuted, displayMode will be in data object in child post
​
data
object
required
​
attachments
object[]
​
dataType
string

Must be in dot separated string format or system defined format (ex. "upstra.customtype", "com.eko.birthday", "liveStream")

Example:

"upstra.customtype"

​
targetType
enum<string>
default:user

where to create post to

Available options:
user,
community,
content
​
targetId
string

Resource public id depends on target type (ex. target type is community, target id will be community public id)

Example:

"public_user_id"

​
metadata
object
Example:
{ "anything": "you want" }
​
postId
string

for specify public post id on post creation

Example:

"postidiwant"

​
tags
string[]
Maximum length: 5

tags

​
hashtags
string[]

Hashtags for the post.

Maximum length: 30
Example:
[
  "tech_news",
  "startup_life",
  "product_launch",
  "innovation_2025"
]
​
mentionees
object[]

The object of the mentions type and user who get a notification from the post.

​
createdAt
string<date-time>

The date/time when a post is created.

Example:

"2022-07-07T04:24:20.444Z"

​
isDiscoverable
boolean
default:true

Set whether the post is discoverable in search and hashtag feeds. Default is true.

Response

Post Information

​
posts
object[]
​
postChildren
object[]
​
comments
object[]
​
users
object[]
​
roles
object[]
​
files
object[]
​
communities
object[]
​
communityUsers
object[]
​
categories
object[]
​
feeds
object[]
​
videoStreamings
object[]
​
videoStreamingChildren
object[]
​
polls
object[]