Skip to content
Ordinal
Esc
↑↓navigate↵open⌘Jpreview

Create post

Create a new post in the workspace. At least one channel (linkedIn, x, instagram, or tikTok) is required.

POST/posts
Authorization
AuthorizationBearer token · headerrequired

API key authentication. Generate an API key from your workspace settings.

Request body
requiredapplication/json
titlestringrequired
publishAtstring<date-time>required
statusPostStatusrequired
Allowed:TentativeToDoInProgressForReviewBlockedFinalizedScheduledPosted
labelIdsstring<uuid>[]
campaignIdstring<uuid>
notesstring
linkedInLinkedInConfig
Show properties
profileIdstring<uuid>

LinkedIn profile ID to post from

copystring

Post content text. To tag someone, use the format @[Display Name](urn). See LinkedIn Mentions for details.

assetsChannelAssetRef[]

Array of assets to attach to the post. Obtain asset IDs by uploading files via the Uploads API. Maximum 20 attachments for LinkedIn posts.

max items 20
Show properties
Array of ChannelAssetRef
assetIdstring<uuid>required

Asset ID from the Uploads API

pollobject
Show properties
questionstring
durationstring
Allowed:ONE_DAYTHREE_DAYSONE_WEEKTWO_WEEKS
optionsobject[]
Show properties
Array of object
idstring
textstring
linkPreviewobject
Show properties
urlstring<uri>
titlestring
descriptionstring
thumbnailIdstring
xTwitterConfig

X (Twitter) channel configuration for creating or updating posts

Show properties
profileIdstring<uuid>required

X (Twitter) profile ID to post from

tweetsobject[]required

Array of tweets. For threads, include multiple tweets in order.

min items 1
Show properties
Array of object
copystringrequired

Tweet text content

min length 1
assetsChannelAssetRef[]

Array of assets to attach to this tweet. Obtain asset IDs by uploading files via the Uploads API. Maximum 4 attachments per tweet.

max items 4
Show properties
Array of ChannelAssetRef
assetIdstring<uuid>required

Asset ID from the Uploads API

instagramInstagramConfig

Instagram channel configuration for creating or updating posts. The shape of the object depends on the type field.

Show properties
One of:
InstagramFeedConfig
profileIdstring<uuid>

Instagram profile ID to post from

typestringrequired

Must be Feed

Allowed:Feed
copystring

Caption text. Maximum 2,200 characters.

max length 2200
assetsInstagramAssetInput[]

Array of assets with optional user tags. Maximum 10.

max items 10
Show properties
Array of InstagramAssetInput
assetIdstring<uuid>required

Asset ID from the Uploads API

tagsInstagramAssetTagInput[]

Users to tag on this asset

Show properties
Array of InstagramAssetTagInput
usernamestringrequired

Instagram username to tag (with or without @ prefix)

xnumber

X coordinate (0-1) for tag position on images. Required for image assets.

min 0 · max 1
ynumber

Y coordinate (0-1) for tag position on images. Required for image assets.

min 0 · max 1
collaboratorsstring[]

Instagram usernames to invite as collaborators. Maximum 3.

max items 3
locationobject | null

Location to tag on the post. Use the search locations endpoint to find locations. Set to null to remove.

Show properties
pageIdstringrequired

Facebook Page ID for the location. Obtain from the search locations endpoint.

namestringrequired

Display name of the location

InstagramReelConfig
profileIdstring<uuid>

Instagram profile ID to post from

typestringrequired

Must be Reel

Allowed:Reel
copystring

Caption text. Maximum 2,200 characters.

max length 2200
assetsInstagramAssetInput[]

Array of video assets. Maximum 1 (video only).

max items 1
coverPhotoIdstring<uuid>

Asset ID for a custom Reel cover photo (JPEG or PNG).

shareToFeedboolean

Whether to also share the Reel to the Feed. Defaults to true.

trialReelGraduationStrategystring | null

Publish as an Instagram trial reel that is shown only to non-followers. MANUAL keeps the reel as a trial until you graduate it from the Instagram app. SS_PERFORMANCE lets Instagram auto-graduate the reel to your followers based on performance in the first 72 hours. Omit or set to null for a normal Reel.

Allowed:MANUALSS_PERFORMANCE
collaboratorsstring[]

Instagram usernames to invite as collaborators. Maximum 3.

max items 3
locationobject | null

Location to tag on the post. Use the search locations endpoint to find locations. Set to null to remove.

Show properties
pageIdstringrequired

Facebook Page ID for the location. Obtain from the search locations endpoint.

namestringrequired

Display name of the location

InstagramStoryConfig
profileIdstring<uuid>

Instagram profile ID to post from

typestringrequired

Must be Story

Allowed:Story
assetsInstagramAssetInput[]

Array of assets. Maximum 10.

max items 10
tikTokTikTokConfig

TikTok channel configuration for creating or updating posts. TikTok posts require exactly one video asset.

Show properties
profileIdstring<uuid>required

TikTok profile ID to post from

copystringrequired

Caption text. Maximum 2,200 characters.

max length 2200
assetsChannelAssetRef[]required

Array containing exactly one video asset.

min items 1 · max items 1
Show properties
Array of ChannelAssetRef
assetIdstring<uuid>required

Asset ID from the Uploads API

privacyLevelTikTokPrivacyLevel

Audience visibility for the TikTok video.

Allowed:PUBLIC_TO_EVERYONEFOLLOWER_OF_CREATORMUTUAL_FOLLOW_FRIENDSSELF_ONLY
isCommentDisabledboolean

Disable comments on the video.

isDuetDisabledboolean

Disable Duet on the video.

isStitchDisabledboolean

Disable Stitch on the video.

isPromotingBusinessboolean

Mark the video as promoting the creator's own business (branded content disclosure).

isPaidPartnershipboolean

Mark the video as a paid partnership with a third-party brand (branded content disclosure).

videoCoverTimestampMsinteger<int32> | null

Timestamp (in milliseconds) of the video frame TikTok should use as the cover thumbnail. Defaults to the first frame when omitted or null.

min 0 · max 2147483647
youTubeShortsYouTubeShortsConfig

YouTube Shorts channel configuration for creating or updating posts. YouTube Shorts posts require exactly one video asset (1s–3min).

Show properties
profileIdstring<uuid>required

YouTube channel profile ID to post from

titlestringrequired

Video title. Required by YouTube. Maximum 100 characters.

max length 100
descriptionstring

Video description. Maximum 5,000 characters.

max length 5000
assetsChannelAssetRef[]required

Array containing exactly one video asset (1s–3min duration).

min items 1 · max items 1
Show properties
Array of ChannelAssetRef
assetIdstring<uuid>required

Asset ID from the Uploads API

privacyStatusYouTubePrivacyStatus

Audience visibility for the YouTube Shorts video.

Allowed:publicprivateunlisted
categoryIdstring

YouTube category ID for the video.

notifySubscribersboolean

Whether to notify channel subscribers when the video is published.

isEmbeddableboolean

Whether the video can be embedded on other sites.

isSelfDeclaredMadeForKidsboolean

Whether the video is self-declared as made for kids.

Responses
200

Post created successfully

idstring<uuid>
urlstring<uri>
titlestring
channelsstring[]
statusPostStatus
Allowed:TentativeToDoInProgressForReviewBlockedFinalizedScheduledPosted
createdAtstring<date-time>
updatedAtstring<date-time>
linkedInobject | null

LinkedIn content with assets. Present when the post targets the LinkedIn channel.

Show properties
copystring
assetsAsset[]

Assets attached to the LinkedIn post

Show properties
Array of Asset
idstring<uuid>

Asset ID

namestring

Original filename

urlstring<uri>

URL to access the asset

mimetypestring

MIME type of the file (e.g., image/jpeg, video/mp4)

sizeinteger

File size in bytes

widthinteger | null

Width in pixels for images and videos

heightinteger | null

Height in pixels for images and videos

durationnumber | null

Duration in seconds for videos

xobject | null

X (Twitter) content with assets. Present when the post targets the Twitter channel.

Show properties
tweetsobject[]
Show properties
Array of object
copystring
assetsAsset[]

Assets attached to this tweet

Show properties
Array of Asset
idstring<uuid>

Asset ID

namestring

Original filename

urlstring<uri>

URL to access the asset

mimetypestring

MIME type of the file (e.g., image/jpeg, video/mp4)

sizeinteger

File size in bytes

widthinteger | null

Width in pixels for images and videos

heightinteger | null

Height in pixels for images and videos

durationnumber | null

Duration in seconds for videos

instagramInstagramContent | null

Instagram content. Present when the post targets the Instagram channel. The shape depends on the type field.

Show properties
One of:
InstagramFeedContent
profileobject | null
Show properties
idstring<uuid>

Profile ID

namestring | null

Profile name

detailstring | null

Profile detail (vanity name for LinkedIn, @username for X)

typestring

Instagram content type

Allowed:Feed
copystring

Caption text

assetsInstagramAsset[]
Show properties
Array of InstagramAsset
idstring<uuid>
namestring
urlstring<uri>
mimetypestring
sizeinteger
widthinteger | null
heightinteger | null
durationnumber | null
tagsInstagramAssetTag[]
Show properties
Array of InstagramAssetTag
usernamestring

Instagram username

xnumber | null

X coordinate (0-1) for images, null for videos

ynumber | null

Y coordinate (0-1) for images, null for videos

collaboratorsstring[]

Instagram usernames invited as collaborators

locationobject | null

Tagged location

Show properties
pageIdstring

Facebook Page ID

namestring

Display name of the location

InstagramReelContent
profileobject | null
Show properties
idstring<uuid>

Profile ID

namestring | null

Profile name

detailstring | null

Profile detail (vanity name for LinkedIn, @username for X)

typestring

Instagram content type

Allowed:Reel
copystring

Caption text

assetsInstagramAsset[]
coverPhotoobject | null

Custom cover photo for the Reel

Show properties
idstring<uuid>

Asset ID

namestring

Original filename

urlstring<uri>

URL to access the asset

mimetypestring

MIME type of the file (e.g., image/jpeg, video/mp4)

sizeinteger

File size in bytes

widthinteger | null

Width in pixels for images and videos

heightinteger | null

Height in pixels for images and videos

durationnumber | null

Duration in seconds for videos

shareToFeedboolean

Whether the Reel is also shared to the Feed

trialReelGraduationStrategystring | null

Trial reel graduation strategy, or null if the Reel is not a trial reel. MANUAL requires you to graduate the reel from the Instagram app; SS_PERFORMANCE lets Instagram auto-graduate based on early performance.

Allowed:MANUALSS_PERFORMANCE
collaboratorsstring[]

Instagram usernames invited as collaborators

locationobject | null

Tagged location

Show properties
pageIdstring

Facebook Page ID

namestring

Display name of the location

InstagramStoryContent
profileobject | null
Show properties
idstring<uuid>

Profile ID

namestring | null

Profile name

detailstring | null

Profile detail (vanity name for LinkedIn, @username for X)

typestring

Instagram content type

Allowed:Story
assetsInstagramAsset[]
400

Bad Request - Invalid input parameters

codestring
messagestring
dataobject
Show properties
errorsobject
401

Unauthorized - Missing or invalid API key

codestring
messagestring
Try it
Server
Authorization
Bodyapplication/json
Request
curl -X POST 'https://app.tryordinal.com/api/v1/posts' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "Q4 Product Launch Announcement",
  "publishAt": "2026-01-15T14:00:00.000Z",
  "status": "Scheduled",
  "linkedIn": {
    "profileId": "550e8400-e29b-41d4-a716-446655440001",
    "copy": "Excited to announce our new product launch! 🚀\n\nHuge thanks to @[John Doe](urn:li:person:ABC123xyz) and the @[Acme Inc](urn:li:organization:123456) team for making this happen.\n\nKey highlights:\n• Feature A\n• Feature B\n• Feature C\n\n#ProductLaunch #Innovation",
    "assets": [
      {
        "assetId": "550e8400-e29b-41d4-a716-446655440010"
      }
    ]
  },
  "x": {
    "profileId": "550e8400-e29b-41d4-a716-446655440003",
    "tweets": [
      {
        "copy": "Excited to announce our new product launch! 🚀\n\nA thread on what we'\''ve been building 🧵",
        "assets": [
          {
            "assetId": "550e8400-e29b-41d4-a716-446655440011"
          }
        ]
      },
      {
        "copy": "Key highlights:\n• Feature A\n• Feature B\n• Feature C"
      }
    ]
  },
  "instagram": {
    "profileId": "550e8400-e29b-41d4-a716-446655440004",
    "type": "Reel",
    "copy": "Check out our new product! 🚀",
    "assets": [
      {
        "assetId": "550e8400-e29b-41d4-a716-446655440012",
        "tags": [
          {
            "username": "tryordinal",
            "x": 0.5,
            "y": 0.5
          }
        ]
      }
    ],
    "shareToFeed": true,
    "coverPhotoId": "550e8400-e29b-41d4-a716-446655440013",
    "collaborators": [
      "tryordinal"
    ]
  },
  "labelIds": [
    "550e8400-e29b-41d4-a716-446655440002"
  ],
  "notes": "Internal note: Coordinate with marketing team"
}'
Response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://app.tryordinal.com/acme/posts/550e8400-e29b-41d4-a716-446655440000",
  "title": "Q4 Product Launch Announcement",
  "channels": [
    "LinkedIn",
    "Twitter",
    "Instagram"
  ],
  "status": "Scheduled",
  "createdAt": "2026-01-05T10:30:00.000Z",
  "updatedAt": "2026-01-05T10:30:00.000Z",
  "linkedIn": {
    "copy": "Excited to announce our new product launch!",
    "assets": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440010",
        "name": "product-photo.jpg",
        "url": "https://cdn.tryordinal.com/assets/product-photo.jpg",
        "mimetype": "image/jpeg",
        "size": 245678,
        "width": 1920,
        "height": 1080,
        "duration": null
      }
    ]
  },
  "x": {
    "tweets": [
      {
        "copy": "Excited to announce our new product launch!",
        "assets": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440011",
            "name": "product-photo.jpg",
            "url": "https://cdn.tryordinal.com/assets/product-photo.jpg",
            "mimetype": "image/jpeg",
            "size": 245678,
            "width": 1920,
            "height": 1080,
            "duration": null
          }
        ]
      },
      {
        "copy": "Key highlights: Feature A, Feature B, Feature C",
        "assets": []
      }
    ]
  },
  "instagram": {
    "type": "Reel",
    "copy": "Check out our new product! 🚀",
    "assets": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440012",
        "name": "product-video.mp4",
        "url": "https://cdn.tryordinal.com/assets/product-video.mp4",
        "mimetype": "video/mp4",
        "size": 5245678,
        "width": 1080,
        "height": 1920,
        "duration": 30,
        "tags": [
          {
            "username": "tryordinal",
            "x": 0.5,
            "y": 0.5
          }
        ]
      }
    ],
    "shareToFeed": true,
    "collaborators": [
      "tryordinal"
    ]
  }
}