create a post

Create a post

POST /api/v4/posts

create a post

cURL

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",
    "fileId": "57b916d38eaf8010caddfb7759a2d06c",
    "pollId": "53a9fd8b5aaa1af6c5a1bbd245ce4a9b1627373735551",
    "streamId": "81559bcc3a5bb3b6bbd69a83b89d337e",
    "roomId": "<string>"
  },
  "attachments": [
    {
      "fileId": "57b916d38eaf8010caddfb7759a2d06c",
      "displayMode": "fit",
      "isMuted": false
    }
  ],
  "dataType": "upstra.customtype",
  "targetType": "user",
  "targetId": "public_user_id",
  "metadata": {
    "anything": "you want"
  },
  "links": [
    {
      "url": "<string>",
      "index": 1,
      "length": 2,
      "renderPreview": false,
      "domain": "<string>",
      "title": "<string>",
      "imageUrl": "<string>"
    }
  ],
  "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,
  "eventId": "507f1f77bcf86cd799439011"
}
'

200

{
  "posts": [
    {
      "postId": "<string>",
      "data": {
        "title": "<string>",
        "text": "<string>",
        "fileId": "<string>",
        "thumbnailFileId": "<string>",
        "videoFileId": {
          "original": "<string>",
          "low": "<string>",
          "medium": "<string>",
          "high": "<string>"
        },
        "streamId": "<string>"
      },
      "_id": "<string>",
      "path": "<string>",
      "parentPostId": "<string>",
      "postedUserId": "<string>",
      "postedUserPublicId": "<string>",
      "postedUserInternalId": "<string>",
      "publisherId": "<string>",
      "publisherPublicId": "<string>",
      "sharedUserId": "<string>",
      "sharedCount": 123,
      "targetId": "<string>",
      "targetPublicId": "<string>",
      "targetInternalId": "<string>",
      "dataType": "text",
      "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": [
        {
          "userIds": [
            "<string>"
          ],
          "userPublicIds": [
            "<string>"
          ],
          "userInternalIds": [
            "<string>"
          ]
        }
      ],
      "impression": 123,
      "reach": 123,
      "structureType": "text"
    }
  ],
  "postChildren": [
    {
      "postId": "<string>",
      "data": {
        "title": "<string>",
        "text": "<string>",
        "fileId": "<string>",
        "thumbnailFileId": "<string>",
        "videoFileId": {
          "original": "<string>",
          "low": "<string>",
          "medium": "<string>",
          "high": "<string>"
        },
        "streamId": "<string>"
      },
      "_id": "<string>",
      "path": "<string>",
      "parentPostId": "<string>",
      "postedUserId": "<string>",
      "postedUserPublicId": "<string>",
      "postedUserInternalId": "<string>",
      "publisherId": "<string>",
      "publisherPublicId": "<string>",
      "sharedUserId": "<string>",
      "sharedCount": 123,
      "targetId": "<string>",
      "targetPublicId": "<string>",
      "targetInternalId": "<string>",
      "dataType": "text",
      "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": [
        {
          "userIds": [
            "<string>"
          ],
          "userPublicIds": [
            "<string>"
          ],
          "userInternalIds": [
            "<string>"
          ]
        }
      ],
      "impression": 123,
      "reach": 123
    }
  ],
  "comments": [
    {
      "commentId": "<string>",
      "_id": "<string>",
      "path": "<string>",
      "userId": "<string>",
      "userPublicId": "<string>",
      "userInternalId": "<string>",
      "parentId": "<string>",
      "rootId": "<string>",
      "referenceId": "<string>",
      "dataType": "<string>",
      "dataTypes": [],
      "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": [
        {
          "userIds": [
            "<string>"
          ],
          "userPublicIds": [
            "<string>"
          ],
          "userInternalIds": [
            "<string>"
          ]
        }
      ],
      "attachments": [
        {
          "fileId": "<string>"
        }
      ],
      "targetId": "<string>"
    }
  ],
  "users": [
    {
      "userId": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "_id": "<string>",
      "path": "<string>",
      "userInternalId": "<string>",
      "userPublicId": "<string>",
      "roles": [
        "<string>"
      ],
      "permissions": [],
      "displayName": "<string>",
      "profileHandle": "<string>",
      "description": "<string>",
      "avatarFileId": "<string>",
      "avatarCustomUrl": "<string>",
      "flagCount": 123,
      "hashFlag": {
        "bits": 123,
        "hashes": 123,
        "hash": [
          "<string>"
        ]
      },
      "metadata": {},
      "isGlobalBan": true,
      "isBrand": true,
      "isDeleted": true
    }
  ],
  "roles": [
    {
      "roleId": "<string>",
      "updatedAt": "2023-11-07T05:31:56Z",
      "permissions": [
        "<string>"
      ],
      "isDeleted": false,
      "displayName": "<string>",
      "createdAt": "2023-11-07T05:31:56Z"
    }
  ],
  "files": [
    {
      "fileId": "<string>",
      "fileUrl": "<string>",
      "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": [
    {
      "communityId": "<string>",
      "channelId": "<string>",
      "displayName": "<string>",
      "_id": "<string>",
      "path": "<string>",
      "userId": "<string>",
      "userPublicId": "<string>",
      "userInternalId": "<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
    }
  ],
  "communityUsers": [
    {
      "userId": "<string>",
      "userPublicId": "<string>",
      "userInternalId": "<string>",
      "channelId": "<string>",
      "communityId": "<string>",
      "notMemberReason": "<string>",
      "isBanned": false,
      "lastActivity": "2023-11-07T05:31:56Z",
      "roles": [
        "<string>"
      ],
      "permissions": [],
      "lastJoin": "2023-11-07T05:31:56Z",
      "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>",
      "postCount": 123,
      "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>",
      "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>",
      "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": []
    }
  ],
  "rooms": [
    {
      "_id": "<string>",
      "targetId": "<string>",
      "referenceId": "<string>",
      "liveChannelId": "<string>",
      "liveChatEnabled": true,
      "title": "<string>",
      "roomId": "<string>",
      "description": "<string>",
      "thumbnailFileId": "<string>",
      "participants": [
        {
          "userId": "<string>",
          "userInternalId": "64be1f6cb9b4106b5a6bbf3f"
        }
      ],
      "livePlaybackUrl": "https://stream.example.com/someid.m3u8?token=token",
      "liveThumbnailUrl": "https://image.example.com/someid/thumbnail.png?token=token",
      "recordedPlaybackInfos": [
        {
          "url": "https://apix.eu.amity.co/api/v1/rooms/roomid/recorded/someid/watch",
          "thumbnailUrl": "https://apix.eu.amity.co/api/v1/rooms/roomid/recorded/someid/thumbnail"
        }
      ],
      "durationSeconds": 123,
      "moderation": {
        "flagLabels": [
          {
            "category": "<string>",
            "threshold": 123,
            "detectedAt": "2023-11-07T05:31:56Z"
          }
        ],
        "terminateLabels": [
          {
            "category": "<string>",
            "threshold": 123,
            "detectedAt": "2023-11-07T05:31:56Z"
          }
        ],
        "updatedAt": "2023-11-07T05:31:56Z"
      },
      "parentRoomId": "<string>",
      "childRoomIds": [],
      "createdAt": "2023-11-07T05:31:56Z",
      "createdBy": "<string>",
      "creatorInternalId": "64be1f6cb9b4106b5a6bbf3f",
      "updatedAt": "2023-11-07T05:31:56Z",
      "liveAt": "2023-11-07T05:31:56Z",
      "endedAt": "2023-11-07T05:31:56Z",
      "recordedAt": "2023-11-07T05:31:56Z",
      "isDeleted": true,
      "deletedAt": "2023-11-07T05:31:56Z",
      "deletedBy": "<string>",
      "path": "<string>",
      "metadata": {}
    }
  ],
  "roomChildrens": [
    {
      "_id": "<string>",
      "targetId": "<string>",
      "referenceId": "<string>",
      "liveChannelId": "<string>",
      "liveChatEnabled": true,
      "title": "<string>",
      "roomId": "<string>",
      "description": "<string>",
      "thumbnailFileId": "<string>",
      "participants": [
        {
          "userId": "<string>",
          "userInternalId": "64be1f6cb9b4106b5a6bbf3f"
        }
      ],
      "livePlaybackUrl": "https://stream.example.com/someid.m3u8?token=token",
      "liveThumbnailUrl": "https://image.example.com/someid/thumbnail.png?token=token",
      "recordedPlaybackInfos": [
        {
          "url": "https://apix.eu.amity.co/api/v1/rooms/roomid/recorded/someid/watch",
          "thumbnailUrl": "https://apix.eu.amity.co/api/v1/rooms/roomid/recorded/someid/thumbnail"
        }
      ],
      "durationSeconds": 123,
      "moderation": {
        "flagLabels": [
          {
            "category": "<string>",
            "threshold": 123,
            "detectedAt": "2023-11-07T05:31:56Z"
          }
        ],
        "terminateLabels": [
          {
            "category": "<string>",
            "threshold": 123,
            "detectedAt": "2023-11-07T05:31:56Z"
          }
        ],
        "updatedAt": "2023-11-07T05:31:56Z"
      },
      "parentRoomId": "<string>",
      "childRoomIds": [],
      "createdAt": "2023-11-07T05:31:56Z",
      "createdBy": "<string>",
      "creatorInternalId": "64be1f6cb9b4106b5a6bbf3f",
      "updatedAt": "2023-11-07T05:31:56Z",
      "liveAt": "2023-11-07T05:31:56Z",
      "endedAt": "2023-11-07T05:31:56Z",
      "recordedAt": "2023-11-07T05:31:56Z",
      "isDeleted": true,
      "deletedAt": "2023-11-07T05:31:56Z",
      "deletedBy": "<string>",
      "path": "<string>",
      "metadata": {}
    }
  ],
  "polls": [
    {
      "pollId": "<string>",
      "userId": "<string>",
      "userInternalId": "64be1f6cb9b4106b5a6bbf3f",
      "userPublicId": "User123",
      "title": "<string>",
      "question": "<string>",
      "answers": [
        {
          "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

Room post

• When dataType is room and roomId is in data, the post will be created as a room post

data · object · required

Body of a post

Show child attributes

attachments · object[]

Array of attachments.

Maximum array length: 10

Show child attributes

dataType · string

Accept "liveStream", "poll", "room" or Custom type. Custom type must be in dot separated string format or system defined format (ex. "some.customtype", "com.foo.bar").

Example:

"upstra.customtype"

targetType · enum<string> · default: user

Where to create post to (default: user).

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).

Maximum string length: 900

Example:

"public_user_id"

metadata · object

Additional properties to support custom fields.

Example:

{ "anything": "you want" }

links · object[]

Array of URL links extracted from content with metadata for link preview rendering

Maximum array length: 100

Show child attributes

postId · string

For specify public post ID on post creation.

Maximum string length: 900

Example:

"postidiwant"

tags · string[]

Tags for the post

Maximum array length: 5

Tag string

Maximum string length: 24

hashtags · string[]

Hashtags for the post

Maximum array length: 30

Maximum string length: 100

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 (optional, max 2 items).

Maximum array length: 2

Show child attributes

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 (optional, default: true).

eventId · string

Event reference for room posts.

Maximum string length: 24

Example:

"507f1f77bcf86cd799439011"

Response

200

application/json

Post Information

posts · object[]

Show child attributes

postChildren · object[]

Show child attributes

comments · object[]

Show child attributes

users · object[]

Show child attributes

roles · object[]

Show child attributes

files · object[]

Show child attributes

communities · object[]

Show child attributes

communityUsers · object[]

Show child attributes

categories · object[]

Show child attributes

feeds · object[]

Show child attributes

videoStreamings · object[]

Show child attributes

videoStreamingChildren · object[]

Show child attributes

rooms · object[]

Show child attributes

roomChildrens · object[]

Show child attributes

polls · object[]

Show child attributes