> ## Documentation Index > Fetch the complete documentation index at: https://docs.tryordinal.com/llms.txt > Use this file to discover all available pages before exploring further. # Create post > Create a new post in the workspace. At least one channel (linkedIn, x, instagram, or tikTok) is required. ## OpenAPI ````yaml /api/openapi.json post /posts openapi: 3.1.0 info: title: Ordinal API version: 1.0.0 description: API to create and manage Ordinal workspaces, posts, profiles, and analytics servers: - url: https://app.tryordinal.com/api/v1 description: Production server security: - bearerAuth: [] tags: - name: Analytics description: Social media analytics data - name: Approvals description: Post approval workflows - name: Comments description: >- Post comments for team collaboration. Supports @mentions using the format @[Display Name](userId). - name: Engagements description: Auto-engagements for posts (likes, comments, reposts) - name: Invites description: Workspace invitations for adding new users - name: Labels description: Labels for organizing posts - name: Instagram description: Instagram utilities for location search and tagging - name: LinkedIn description: LinkedIn utilities for profile lookups, tagging, and mentions - name: Posts description: Create and manage posts - name: Profiles description: List connected social profiles - name: Slack Boosts description: >- List connected Slack channels (webhooks), then create and manage slack boosts so teams get notified in Slack when posts publish. Requires Slack connected with marketing boost channels. - name: Subscribers description: Post subscribers for notifications - name: File Uploads description: >- Upload files from URLs for use in posts. Supports images (JPEG, PNG, GIF, WebP) up to 10 MB and videos (MP4, MOV) up to 350 MB. - name: Ideas description: >- Create and manage content ideas. Ideas are draft posts without scheduled dates that can be converted to calendar posts. - name: Inline Comments description: >- Text-anchored comments on specific post content. Read-only API for retrieving inline comments across channels. - name: Users description: Workspace users - name: Webhooks description: >- Create, list, get, update, and delete webhooks to receive real-time event notifications - name: Workspaces description: Workspace information paths: /posts: post: tags: - Posts summary: Create post description: >- Create a new post in the workspace. At least one channel (linkedIn, x, instagram, or tikTok) is required. operationId: posts-create requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePostInput' example: 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! ๐Ÿš€ Huge thanks to @[John Doe](urn:li:person:ABC123xyz) and the @[Acme Inc](urn:li:organization:123456) team for making this happen. Key highlights: โ€ข Feature A โ€ข Feature B โ€ข Feature C #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! ๐Ÿš€ A thread on what we've been building ๐Ÿงต assets: - assetId: 550e8400-e29b-41d4-a716-446655440011 - copy: |- Key highlights: โ€ข Feature A โ€ข Feature B โ€ข 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' responses: '200': description: Post created successfully content: application/json: schema: $ref: '#/components/schemas/PostCreateResponse' example: 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 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' components: schemas: CreatePostInput: type: object required: - title - publishAt - status properties: title: type: string publishAt: type: string format: date-time status: $ref: '#/components/schemas/PostStatus' labelIds: type: array items: type: string format: uuid campaignId: type: string format: uuid notes: type: string linkedIn: $ref: '#/components/schemas/LinkedInConfig' x: $ref: '#/components/schemas/TwitterConfig' instagram: $ref: '#/components/schemas/InstagramConfig' tikTok: $ref: '#/components/schemas/TikTokConfig' youTubeShorts: $ref: '#/components/schemas/YouTubeShortsConfig' PostCreateResponse: type: object properties: id: type: string format: uuid url: type: string format: uri title: type: string channels: type: array items: type: string status: $ref: '#/components/schemas/PostStatus' createdAt: type: string format: date-time updatedAt: type: string format: date-time linkedIn: type: object nullable: true description: >- LinkedIn content with assets. Present when the post targets the LinkedIn channel. properties: copy: type: string assets: type: array description: Assets attached to the LinkedIn post items: $ref: '#/components/schemas/Asset' x: type: object nullable: true description: >- X (Twitter) content with assets. Present when the post targets the Twitter channel. properties: tweets: type: array items: type: object properties: copy: type: string assets: type: array description: Assets attached to this tweet items: $ref: '#/components/schemas/Asset' instagram: $ref: '#/components/schemas/InstagramContent' PostStatus: type: string enum: - Tentative - ToDo - InProgress - ForReview - Blocked - Finalized - Scheduled - Posted LinkedInConfig: type: object properties: profileId: type: string format: uuid description: LinkedIn profile ID to post from copy: type: string description: >- Post content text. To tag someone, use the format `@[Display Name](urn)`. See [LinkedIn Mentions](/api/linkedin-mentions) for details. assets: type: array description: >- Array of assets to attach to the post. Obtain asset IDs by uploading files via the Uploads API. Maximum 20 attachments for LinkedIn posts. items: $ref: '#/components/schemas/ChannelAssetRef' maxItems: 20 poll: type: object properties: question: type: string duration: type: string enum: - ONE_DAY - THREE_DAYS - ONE_WEEK - TWO_WEEKS options: type: array items: type: object properties: id: type: string text: type: string linkPreview: type: object properties: url: type: string format: uri title: type: string description: type: string thumbnailId: type: string TwitterConfig: type: object description: X (Twitter) channel configuration for creating or updating posts required: - profileId - tweets properties: profileId: type: string format: uuid description: X (Twitter) profile ID to post from tweets: type: array description: Array of tweets. For threads, include multiple tweets in order. minItems: 1 items: type: object required: - copy properties: copy: type: string minLength: 1 description: Tweet text content assets: type: array description: >- Array of assets to attach to this tweet. Obtain asset IDs by uploading files via the Uploads API. Maximum 4 attachments per tweet. items: $ref: '#/components/schemas/ChannelAssetRef' maxItems: 4 InstagramConfig: description: >- Instagram channel configuration for creating or updating posts. The shape of the object depends on the `type` field. oneOf: - $ref: '#/components/schemas/InstagramFeedConfig' - $ref: '#/components/schemas/InstagramReelConfig' - $ref: '#/components/schemas/InstagramStoryConfig' discriminator: propertyName: type mapping: Feed: $ref: '#/components/schemas/InstagramFeedConfig' Reel: $ref: '#/components/schemas/InstagramReelConfig' Story: $ref: '#/components/schemas/InstagramStoryConfig' TikTokConfig: type: object description: >- TikTok channel configuration for creating or updating posts. TikTok posts require exactly one video asset. required: - profileId - copy - assets properties: profileId: type: string format: uuid description: TikTok profile ID to post from copy: type: string maxLength: 2200 description: Caption text. Maximum 2,200 characters. assets: type: array description: Array containing exactly one video asset. minItems: 1 maxItems: 1 items: $ref: '#/components/schemas/ChannelAssetRef' privacyLevel: $ref: '#/components/schemas/TikTokPrivacyLevel' isCommentDisabled: type: boolean description: Disable comments on the video. isDuetDisabled: type: boolean description: Disable Duet on the video. isStitchDisabled: type: boolean description: Disable Stitch on the video. isPromotingBusiness: type: boolean description: >- Mark the video as promoting the creator's own business (branded content disclosure). isPaidPartnership: type: boolean description: >- Mark the video as a paid partnership with a third-party brand (branded content disclosure). videoCoverTimestampMs: type: integer format: int32 minimum: 0 maximum: 2147483647 nullable: true description: >- Timestamp (in milliseconds) of the video frame TikTok should use as the cover thumbnail. Defaults to the first frame when omitted or null. YouTubeShortsConfig: type: object description: >- YouTube Shorts channel configuration for creating or updating posts. YouTube Shorts posts require exactly one video asset (1sโ€“3min). required: - profileId - title - assets properties: profileId: type: string format: uuid description: YouTube channel profile ID to post from title: type: string maxLength: 100 description: Video title. Required by YouTube. Maximum 100 characters. description: type: string maxLength: 5000 description: Video description. Maximum 5,000 characters. assets: type: array description: Array containing exactly one video asset (1sโ€“3min duration). minItems: 1 maxItems: 1 items: $ref: '#/components/schemas/ChannelAssetRef' privacyStatus: $ref: '#/components/schemas/YouTubePrivacyStatus' categoryId: type: string description: YouTube category ID for the video. notifySubscribers: type: boolean description: Whether to notify channel subscribers when the video is published. isEmbeddable: type: boolean description: Whether the video can be embedded on other sites. isSelfDeclaredMadeForKids: type: boolean description: Whether the video is self-declared as made for kids. Asset: type: object description: Asset metadata for files attached to posts properties: id: type: string format: uuid description: Asset ID name: type: string description: Original filename url: type: string format: uri description: URL to access the asset mimetype: type: string description: MIME type of the file (e.g., image/jpeg, video/mp4) size: type: integer description: File size in bytes width: type: integer nullable: true description: Width in pixels for images and videos height: type: integer nullable: true description: Height in pixels for images and videos duration: type: number nullable: true description: Duration in seconds for videos InstagramContent: nullable: true description: >- Instagram content. Present when the post targets the Instagram channel. The shape depends on the `type` field. oneOf: - $ref: '#/components/schemas/InstagramFeedContent' - $ref: '#/components/schemas/InstagramReelContent' - $ref: '#/components/schemas/InstagramStoryContent' discriminator: propertyName: type mapping: Feed: $ref: '#/components/schemas/InstagramFeedContent' Reel: $ref: '#/components/schemas/InstagramReelContent' Story: $ref: '#/components/schemas/InstagramStoryContent' ValidationError: type: object properties: code: type: string message: type: string data: type: object properties: errors: type: object additionalProperties: type: array items: type: string Error: type: object properties: code: type: string message: type: string ChannelAssetRef: type: object description: A reference to an asset to attach to a post. required: - assetId properties: assetId: type: string format: uuid description: Asset ID from the Uploads API InstagramFeedConfig: type: object description: Instagram Feed post configuration required: - type properties: profileId: type: string format: uuid description: Instagram profile ID to post from type: type: string enum: - Feed description: Must be `Feed` copy: type: string maxLength: 2200 description: Caption text. Maximum 2,200 characters. assets: type: array description: Array of assets with optional user tags. Maximum 10. maxItems: 10 items: $ref: '#/components/schemas/InstagramAssetInput' collaborators: type: array description: Instagram usernames to invite as collaborators. Maximum 3. maxItems: 3 items: type: string location: allOf: - $ref: '#/components/schemas/InstagramLocationInput' nullable: true description: >- Location to tag on the post. Use the search locations endpoint to find locations. Set to null to remove. InstagramReelConfig: type: object description: Instagram Reel post configuration required: - type properties: profileId: type: string format: uuid description: Instagram profile ID to post from type: type: string enum: - Reel description: Must be `Reel` copy: type: string maxLength: 2200 description: Caption text. Maximum 2,200 characters. assets: type: array description: Array of video assets. Maximum 1 (video only). maxItems: 1 items: $ref: '#/components/schemas/InstagramAssetInput' coverPhotoId: type: string format: uuid description: Asset ID for a custom Reel cover photo (JPEG or PNG). shareToFeed: type: boolean description: Whether to also share the Reel to the Feed. Defaults to true. collaborators: type: array description: Instagram usernames to invite as collaborators. Maximum 3. maxItems: 3 items: type: string location: allOf: - $ref: '#/components/schemas/InstagramLocationInput' nullable: true description: >- Location to tag on the post. Use the search locations endpoint to find locations. Set to null to remove. InstagramStoryConfig: type: object description: Instagram Story post configuration required: - type properties: profileId: type: string format: uuid description: Instagram profile ID to post from type: type: string enum: - Story description: Must be `Story` assets: type: array description: Array of assets. Maximum 10. maxItems: 10 items: $ref: '#/components/schemas/InstagramAssetInput' TikTokPrivacyLevel: type: string description: Audience visibility for the TikTok video. enum: - PUBLIC_TO_EVERYONE - FOLLOWER_OF_CREATOR - MUTUAL_FOLLOW_FRIENDS - SELF_ONLY YouTubePrivacyStatus: type: string description: Audience visibility for the YouTube Shorts video. enum: - public - private - unlisted InstagramFeedContent: type: object description: Instagram Feed content in responses properties: profile: allOf: - $ref: '#/components/schemas/ChannelProfile' nullable: true type: type: string enum: - Feed description: Instagram content type copy: type: string description: Caption text assets: type: array items: $ref: '#/components/schemas/InstagramAsset' collaborators: type: array items: type: string description: Instagram usernames invited as collaborators location: allOf: - $ref: '#/components/schemas/InstagramLocation' nullable: true description: Tagged location InstagramReelContent: type: object description: Instagram Reel content in responses properties: profile: allOf: - $ref: '#/components/schemas/ChannelProfile' nullable: true type: type: string enum: - Reel description: Instagram content type copy: type: string description: Caption text assets: type: array items: $ref: '#/components/schemas/InstagramAsset' coverPhoto: allOf: - $ref: '#/components/schemas/Asset' nullable: true description: Custom cover photo for the Reel shareToFeed: type: boolean description: Whether the Reel is also shared to the Feed collaborators: type: array items: type: string description: Instagram usernames invited as collaborators location: allOf: - $ref: '#/components/schemas/InstagramLocation' nullable: true description: Tagged location InstagramStoryContent: type: object description: Instagram Story content in responses properties: profile: allOf: - $ref: '#/components/schemas/ChannelProfile' nullable: true type: type: string enum: - Story description: Instagram content type assets: type: array items: $ref: '#/components/schemas/InstagramAsset' InstagramAssetInput: type: object description: An asset to attach to an Instagram post, with optional user tags required: - assetId properties: assetId: type: string format: uuid description: Asset ID from the Uploads API tags: type: array description: Users to tag on this asset items: $ref: '#/components/schemas/InstagramAssetTagInput' InstagramLocationInput: type: object description: Location to tag on an Instagram post required: - pageId - name properties: pageId: type: string description: >- Facebook Page ID for the location. Obtain from the search locations endpoint. name: type: string description: Display name of the location ChannelProfile: type: object description: Profile information for a channel (LinkedIn, X, or Instagram) properties: id: type: string format: uuid description: Profile ID name: type: string nullable: true description: Profile name detail: type: string nullable: true description: Profile detail (vanity name for LinkedIn, @username for X) InstagramAsset: type: object description: An asset attached to an Instagram post with user tags properties: id: type: string format: uuid name: type: string url: type: string format: uri mimetype: type: string size: type: integer width: type: integer nullable: true height: type: integer nullable: true duration: type: number nullable: true tags: type: array items: $ref: '#/components/schemas/InstagramAssetTag' InstagramLocation: type: object description: A location tagged on an Instagram post properties: pageId: type: string description: Facebook Page ID name: type: string description: Display name of the location InstagramAssetTagInput: type: object description: A user tag on an Instagram asset required: - username properties: username: type: string description: Instagram username to tag (with or without @ prefix) x: type: number minimum: 0 maximum: 1 description: >- X coordinate (0-1) for tag position on images. Required for image assets. 'y': type: number minimum: 0 maximum: 1 description: >- Y coordinate (0-1) for tag position on images. Required for image assets. InstagramAssetTag: type: object description: A user tag on an Instagram asset in responses properties: username: type: string description: Instagram username x: type: number nullable: true description: X coordinate (0-1) for images, null for videos 'y': type: number nullable: true description: Y coordinate (0-1) for images, null for videos responses: BadRequest: description: Bad Request - Invalid input parameters content: application/json: schema: $ref: '#/components/schemas/ValidationError' example: code: BAD_REQUEST message: Bad Request data: errors: publishAt: - Invalid date format status: - Invalid enum value Unauthorized: description: Unauthorized - Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' example: code: UNAUTHORIZED message: Invalid or unauthorized API key securitySchemes: bearerAuth: type: http scheme: bearer description: >- API key authentication. Generate an API key from your workspace settings. ````