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

# Send a project message

> Send a prompt to continue or steer the project. Effort stays fixed at creation.



## OpenAPI

````yaml /openapi.json post /projects/{id}/messages
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:
  /projects/{id}/messages:
    post:
      tags:
        - Projects
      summary: Send a project message
      description: >-
        Send a prompt to continue or steer the project. Effort stays fixed at
        creation.
      operationId: SendAProjectMessage
      parameters:
        - in: header
          name: Idempotency-Key
          required: false
          description: >-
            Optional UUID for identical REST retries. Reuse the same key and
            body after a lost response.
          schema:
            type: string
            format: uuid
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContinueMotionProjectRequest'
            example:
              prompt: Shorten the opening and update the thumbnail.
              template_ids: []
              brand_kit_ids: []
      responses:
        '202':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MotionSendProjectMessageResponse'
              example:
                project_id: 4f20dcdd-f63b-4898-97d6-2e05c0d37c78
                chat_url: >-
                  https://motion.so/agent?chat=4f20dcdd-f63b-4898-97d6-2e05c0d37c78
                status: queued
                message_id: e8c3af4c-4f37-46b7-8b0d-53b09a67d6cb
                turn_id: e8c3af4c-4f37-46b7-8b0d-53b09a67d6cb
        '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: Stale revision, active work or conflicting source identity
          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:sessions:write
components:
  schemas:
    ContinueMotionProjectRequest:
      type: object
      properties:
        prompt:
          type: string
          minLength: 1
          maxLength: 12000
          description: >-
            Describe the work to do. Include source links, size, duration,
            layout and style in the prompt.
        attachments:
          description: Uploaded library assets only. Put web links directly in prompt text.
          maxItems: 100
          type: array
          items:
            type: object
            properties:
              asset_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)$
            required:
              - asset_id
            additionalProperties: false
        template_ids:
          description: >-
            Saved template IDs from List templates to attach with this message.
            Earlier references remain in conversation history.
          maxItems: 8
          type: array
          items:
            type: string
            pattern: ^[a-zA-Z0-9_-]{1,160}$
        brand_kit_ids:
          description: >-
            Saved brand-kit UUIDs from List brand kits. Omit to inherit the
            current selection; an array replaces it and [] clears it.
          maxItems: 8
          type: array
          items:
            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)$
        connectors:
          description: >-
            Exact connections the agent may use, at most one per provider. Omit
            to keep the project's selection; an array replaces it for this and
            later turns, including the following tool calls of an active turn;
            [] disables all connectors. Selecting connections needs
            motion:connectors:read for your private connections in this
            organization workspace.
          maxItems: 18
          type: array
          items:
            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: >-
                  Connection id from GET /api/motion/connections or
                  list_connections.
              actions:
                description: >-
                  Narrow this connection to these permission_options ids of its
                  provider. Omit to keep the connection's current allowed
                  actions. Never widens permissions.
                minItems: 1
                maxItems: 16
                type: array
                items:
                  type: string
                  enum:
                    - repositories
                    - code
                    - issues
                    - history
                    - pages
                    - comments
                    - create_pages
                    - edit_pages
                    - add_comments
                    - files
                    - downloads
                    - uploads
                    - folders
                    - search
                    - deletes
                    - posts
                    - prepare
                    - discard
            required:
              - id
            additionalProperties: false
        export_formats:
          description: >-
            Automatically export the finished outputs in these formats. You can
            also request exports later.
          maxItems: 10
          type: array
          items:
            type: string
            enum:
              - mp4
              - png
              - jpeg
              - media
              - premiere
              - after-effects
              - resolve
              - final-cut
              - psd
              - svg
      required:
        - prompt
      additionalProperties: false
    MotionSendProjectMessageResponse:
      type: object
      properties:
        project_id:
          type: string
          format: uuid
          description: >-
            Motion project chat UUID returned by create_project or
            list_projects.
        message_id:
          type: string
          format: uuid
          description: Durable user-message UUID accepted for this request.
        turn_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          description: >-
            Starting user-message UUID shared by all messages and saved
            generations from one turn. Steering retains this ID; historical
            turns may have no recorded ID.
        chat_url:
          type: string
          format: uri
          description: >-
            Motion web chat URL where the user can inspect and continue this
            project.
        status:
          type: string
          enum:
            - queued
            - running
            - completed
            - failed
            - cancelled
            - awaiting_user_input
            - awaiting_credits
          description: >-
            Project work status. Completed means the agent finished; exports may
            still be preparing.
      required:
        - project_id
        - message_id
        - turn_id
        - chat_url
        - status
      additionalProperties: false
    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.