> ## Documentation Index
> Fetch the complete documentation index at: https://docs.motion.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Draft a scheduled social post

> Create a draft with uploaded media and a caption. This does not publish it; submit the draft for review.



## OpenAPI

````yaml /openapi.json post /social/posts
openapi: 3.1.0
info:
  title: Motion
  version: 1.1.0
  description: >-
    Create Motion projects from prompts, read authored generations and outputs,
    and explicitly request renders or editor exports. Use reusable templates and
    brand kits. Credentials remain bound to current workspace access and
    permissions. Legacy single-video endpoints are deprecated.
servers:
  - url: https://api.motion.so/api/motion
security:
  - MotionApiKey: []
tags:
  - name: Projects
  - name: Project results
  - name: Project exports
  - name: Templates
  - name: Brand kits
  - name: Media library
  - name: Automations
  - name: Social posting
  - name: API information
  - name: Deprecated endpoints
    description: >-
      Older single-video routes remain callable for existing clients. Use the
      project API for new integrations; no removal date is scheduled.
  - name: Connectors
    description: Connect services and control the actions a project may use.
paths:
  /social/posts:
    post:
      tags:
        - Social posting
      summary: Draft a scheduled social post
      description: >-
        Create a draft with uploaded media and a caption. This does not publish
        it; submit the draft for review.
      operationId: DraftAScheduledSocialPost
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                connectionId:
                  type: string
                  format: uuid
                caption:
                  type: string
                mediaUrls:
                  type: array
                  maxItems: 10
                  items:
                    type: string
                thumbnailUrl:
                  type:
                    - string
                    - 'null'
                youtubeTitle:
                  type:
                    - string
                    - 'null'
                youtubeDescription:
                  type:
                    - string
                    - 'null'
                scheduledAt:
                  type: string
                  format: date-time
                sourceChatId:
                  type: string
                  format: uuid
                  description: >-
                    Source Motion project chat ID. Required for agent-created
                    posts; current workspace sharing and permissions apply.
              required:
                - connectionId
                - scheduledAt
                - sourceChatId
              additionalProperties: false
            example:
              connectionId: 4f20dcdd-f63b-4898-97d6-2e05c0d37c78
              scheduledAt: '2026-11-17T20:00:00Z'
              sourceChatId: 4f20dcdd-f63b-4898-97d6-2e05c0d37c78
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MotionCreateSocialPostResponse'
              example:
                id: 4f20dcdd-f63b-4898-97d6-2e05c0d37c78
                connectionId: 4f20dcdd-f63b-4898-97d6-2e05c0d37c78
                revision: 3
                status: draft
        '400':
          description: Invalid input or cursor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Credential invalid or revoked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Missing scope, role, resource access or entitlement
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not visible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: >-
            The post changed or cannot perform this action in its current state.
            Read it again before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Required service unavailable; do not blindly retry mutations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - MotionApiKey: []
        - MotionOAuth:
            - motion:social:write
components:
  schemas:
    MotionCreateSocialPostResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          pattern: >-
            ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
          description: >-
            Identifier of this resource. Use it when reading or updating the
            same resource.
        connectionId:
          type: string
          format: uuid
          pattern: >-
            ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
          description: >-
            Enabled social destination UUID from list_social_accounts in the
            connected workspace.
        revision:
          type: integer
          exclusiveMinimum: 0
          maximum: 9007199254740991
          description: >-
            Post edit version. Pass it when editing, submitting, approving or
            cancelling this post; a stale version returns a conflict.
        status:
          type: string
          enum:
            - draft
            - in_review
            - scheduled
            - processing
            - posted
            - failed
            - cancelled
          description: Current state. The enum lists the values this resource can return.
        sourceChatId:
          type:
            - string
            - 'null'
          description: >-
            Accessible source project chat UUID in the selected workspace.
            Required for agent-created social posts.
        caption:
          type:
            - string
            - 'null'
          description: >-
            Post copy within the destination’s platform limits; review before
            scheduling publication.
        scheduledAt:
          anyOf:
            - type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
            - type: 'null'
          description: >-
            Future publication time as an ISO timestamp including its UTC
            offset.
        approvedBy:
          type:
            - string
            - 'null'
          description: Member UUID that approved publication, or null before approval.
        postUrl:
          type:
            - string
            - 'null'
          description: >-
            Provider URL of the published post, or null before verified
            publication.
        error:
          type:
            - string
            - 'null'
          description: >-
            Actionable error text or sanitized failure code, or null when no
            error is present.
        hasMedia:
          type: boolean
          description: Whether this post includes uploaded image or video media.
        hasThumbnail:
          type: boolean
          description: Whether this post includes an uploaded video thumbnail.
        publicationLocked:
          type: boolean
          description: >-
            Whether provider submission has begun, so editing or cancellation
            may be restricted.
      required:
        - id
        - connectionId
        - revision
        - status
      additionalProperties: {}
    ErrorResponse:
      type: object
      description: >-
        Error bodies are JSON. Check the HTTP status first. Permission and
        validation errors use error; service errors may use detail. Optional
        fields explain how to correct the request.
      anyOf:
        - required:
            - error
        - required:
            - detail
      properties:
        error:
          type: string
          description: Error code or readable explanation.
        detail:
          type: string
          description: Readable explanation from the service.
        message:
          type: string
          description: Readable explanation accompanying an error code.
        error_description:
          type: string
          description: Authentication or permission explanation.
        required_scope:
          type: string
          description: Permission required by this operation.
        details:
          type: array
          description: Invalid request fields. Each issue includes a path and message.
          items:
            type: object
            properties:
              code:
                type: string
              path:
                type: array
                items:
                  oneOf:
                    - type: string
                    - type: integer
              message:
                type: string
        issues:
          type: array
          description: Service validation issues.
          items:
            type: object
  securitySchemes:
    MotionApiKey:
      type: http
      scheme: bearer
      description: >-
        A Motion API key. Access is limited to its stored organization,
        workspace, scopes and the creator’s current permissions.
    MotionOAuth:
      type: oauth2
      description: >-
        OAuth REST tokens use the full MCP audience, https://mcp.motion.so/mcp.
        Reauthorize existing connections to add scopes. Current workspace roles
        and resource permissions still apply.
      flows:
        authorizationCode:
          authorizationUrl: https://mcp.motion.so/oauth/authorize
          tokenUrl: https://mcp.motion.so/oauth/token
          scopes:
            motion:automations:read: Read automation definitions, capabilities, runs, and analytics.
            motion:automations:write: Create, edit, delete, invoke, and retry automations.
            motion:connectors:read: >-
              Read available services, your private organization connections and
              allowed actions without secrets.
            motion:connectors:write: >-
              Connect and disconnect your private accounts inside the credential
              organization workspace.
            motion:templates:read: Read and preview accessible templates.
            motion:templates:write: Create, edit, share, and archive prompt templates.
            motion:sessions:read: Read permitted chats, job status and saved exports.
            motion:sessions:write: >-
              Create and steer Motion projects using organization workspace
              credits.
            motion:assets:read: Find and read permitted media library assets.
            motion:brand-kits:read: Read permitted brand kits.
            motion:brand-kits:write: Create and edit brand kits within current app permissions.
            motion:social:read: Read authorized social accounts and posts.
            motion:social:write: >-
              Draft, submit, approve and cancel posts within current app
              permissions.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.