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

# Create an upload

> Create an upload. Send the file to upload_url using the returned form fields, then complete the upload.



## OpenAPI

````yaml /openapi.json post /uploads
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:
  /uploads:
    post:
      tags:
        - Library
      summary: Create an upload
      description: >-
        Create an upload. Send the file to upload_url using the returned form
        fields, then complete the upload.
      operationId: createLibraryUpload
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  additionalProperties: false
                  properties:
                    filename:
                      type: string
                      maxLength: 255
                      minLength: 1
                      description: >-
                        Filename only, without directory separators or control
                        characters.
                    content_type:
                      type: string
                    file_size:
                      type: integer
                      minimum: 1
                      maximum: 536870912
                  required:
                    - filename
                    - content_type
                    - file_size
                  title: Library upload
                - type: object
                  properties:
                    filename:
                      type: string
                      minLength: 1
                      maxLength: 255
                    content_type:
                      type: string
                      enum:
                        - video/mp4
                        - video/quicktime
                        - video/x-msvideo
                        - video/webm
                        - video/x-matroska
                        - video/x-m4v
                        - audio/mpeg
                        - audio/mp3
                        - audio/wav
                        - audio/mp4
                        - audio/x-m4a
                        - audio/flac
                        - audio/ogg
                        - audio/aac
                        - audio/opus
                        - audio/webm
                        - image/png
                        - image/jpeg
                        - image/jpg
                        - image/gif
                        - image/webp
                        - image/svg+xml
                  required:
                    - filename
                    - content_type
                  not:
                    required:
                      - file_size
                  additionalProperties: false
                  description: >-
                    Legacy temporary attachment ticket. Omit file_size; this
                    does not create a Library asset and has no completion step.
                    Maximum video 5 GiB, audio 500 MiB or image 50 MiB.
                  title: Legacy temporary attachment
            example:
              filename: brand-guide.pdf
              content_type: application/pdf
              file_size: 123456
      responses:
        '200':
          description: Legacy temporary attachment ticket; no Library asset is created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  upload_id:
                    type: string
                    format: uuid
                  upload_url:
                    type: string
                    format: uri
                  attachment_url:
                    type: string
                    format: uri
                  content_type:
                    type: string
                  filename:
                    type: string
                  upload_method:
                    type: string
                    const: POST
                  upload_fields:
                    type: object
                    additionalProperties:
                      type: string
                  upload_url_expires_in_seconds:
                    type: integer
                    const: 3600
                  attachment_url_expires_in_seconds:
                    type: integer
                    const: 604800
                  max_file_size_bytes:
                    type: integer
                    enum:
                      - 5368709120
                      - 524288000
                      - 52428800
                required:
                  - upload_id
                  - upload_url
                  - attachment_url
                  - content_type
                  - filename
                  - upload_method
                  - upload_fields
                  - upload_url_expires_in_seconds
                  - attachment_url_expires_in_seconds
                  - max_file_size_bytes
                additionalProperties: false
              example:
                upload_id: 4f20dcdd-f63b-4898-97d6-2e05c0d37c78
                upload_url: https://storage.googleapis.com/example-upload
                attachment_url: https://downloads.example.com/launch.mp4
                content_type: video/mp4
                filename: launch.mp4
                upload_method: POST
                upload_fields: {}
                upload_url_expires_in_seconds: 3600
                attachment_url_expires_in_seconds: 604800
                max_file_size_bytes: 5368709120
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MotionCreateLibraryUploadResponse'
              example:
                id: 4f20dcdd-f63b-4898-97d6-2e05c0d37c78
                status: uploading
                upload_url: https://storage.googleapis.com/example-upload
                upload_method: POST
                upload_fields: {}
                expires_at: '2026-11-17T20:00:00Z'
        '400':
          description: Invalid upload input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Missing asset-write permission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Upload ticket limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - MotionApiKey: []
        - MotionOAuth:
            - motion:assets:write
        - MotionOAuth:
            - motion:sessions:write
components:
  schemas:
    MotionCreateLibraryUploadResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: >-
            Identifier of this resource. Use it when reading or updating the
            same resource.
        status:
          type: string
          const: uploading
          description: Current state. The enum lists the values this resource can return.
        upload_url:
          type: string
          format: uri
          description: Signed endpoint to receive the file by multipart form POST.
        upload_method:
          type: string
          const: POST
          description: 'HTTP method required by the upload ticket: POST.'
        upload_fields:
          type: object
          propertyNames:
            type: string
          additionalProperties:
            type: string
          description: >-
            Include every entry as a multipart form field, then append the file
            as the last field named file.
        expires_at:
          type: string
          format: date-time
          description: >-
            ISO 8601 expiration timestamp for this ticket or signed link.
            Request a fresh link after expiry.
      required:
        - id
        - status
        - upload_url
        - upload_method
        - upload_fields
        - expires_at
      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.