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

# Create Media Asset

> Create a new media asset and receive an upload URL. Returns a secure upload URL where you can upload your video/audio file (max 5GB). If using YouTube or Vimeo for playback, provide externalPlatform and externalPlatformId, but you must still upload the original file to the returned uploadUrl for AI processing.



## OpenAPI

````yaml POST /media/create
openapi: 3.1.0
info:
  title: Haystack API
  description: Content management and semantic search API for Haystack
  version: 2.0.0
  contact:
    name: Haystack Support
    email: support@thehaystack.ai
    url: https://thehaystack.ai
servers:
  - url: https://api.thehaystack.ai/v2/haystack
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: Items
    description: Content item management
  - name: Collections
    description: Top-level content organization
  - name: Series
    description: Multi-part content grouping
  - name: Speakers
    description: Content presenter management
  - name: Media
    description: Video and audio asset management
  - name: Search
    description: Semantic content search
  - name: Analytics
    description: Usage statistics and metrics
  - name: Resources
    description: Attach supplementary files, links, and videos to items
  - name: Scriptures
    description: Attach Bible references to items
  - name: Chapters
    description: Time-based chapter markers on media assets
  - name: Stats
    description: Analytics and reporting
  - name: Frontend
    description: Public frontend configuration
paths:
  /media/create:
    post:
      tags:
        - Media
      summary: Create media asset
      description: >-
        Create a new media asset and receive an upload URL. Returns a secure
        upload URL where you can upload your video/audio file (max 5GB). If
        using YouTube or Vimeo for playback, provide externalPlatform and
        externalPlatformId, but you must still upload the original file to the
        returned uploadUrl for AI processing.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - itemId
                - contentType
                - variantTypeId
              properties:
                itemId:
                  type: integer
                  description: The item this media belongs to
                contentType:
                  type: string
                  enum:
                    - audio
                    - video
                  description: The type of media content
                variantTypeId:
                  type: integer
                  description: >-
                    The variant type ID for this media asset (e.g., original,
                    sermon audio, full service)
                mimeType:
                  type: string
                  description: MIME type of the file being uploaded
                  example: video/mp4
                originalFilename:
                  type: string
                  description: Original filename of the uploaded file
                externalPlatform:
                  type: string
                  description: Platform for external video playback (video content only)
                  enum:
                    - youtube
                    - vimeo
                externalPlatformId:
                  type: string
                  description: >-
                    Video ID on the external platform (required if
                    externalPlatform is set)
                  example: dQw4w9WgXcQ
      responses:
        '200':
          description: Media asset created with upload URL
          content:
            application/json:
              schema:
                type: object
                properties:
                  mediaAsset:
                    $ref: '#/components/schemas/MediaAsset'
                  uploadUrl:
                    type: string
                    description: Secure URL to upload your video/audio file (PUT request)
                    example: https://storage.example.com/upload/abc123?signature=xyz
components:
  schemas:
    MediaAsset:
      type: object
      properties:
        id:
          type: integer
        itemId:
          type: integer
        item:
          allOf:
            - $ref: '#/components/schemas/Item'
          nullable: true
          description: Included when _expand contains 'item'
        contentType:
          type: string
          enum:
            - audio
            - video
        mimeType:
          type: string
          nullable: true
        variantTypeId:
          type: integer
        variantType:
          allOf:
            - $ref: '#/components/schemas/MediaVariantType'
          nullable: true
          description: Included when _expand contains 'variantType'
        fileSizeBytes:
          type: integer
          nullable: true
        durationSecs:
          type: integer
          nullable: true
        bitrate:
          type: integer
          nullable: true
        videoWidth:
          type: integer
          nullable: true
        videoHeight:
          type: integer
          nullable: true
        filename:
          type: string
          nullable: true
          description: Raw storage key; use `url` to link to the file
        originalFilename:
          type: string
          nullable: true
        externalPlatform:
          type: string
          enum:
            - youtube
            - vimeo
          nullable: true
        externalPlatformId:
          type: string
          nullable: true
        muxAssetId:
          type: string
          nullable: true
        muxPlaybackId:
          type: string
          nullable: true
        status:
          type: string
          enum:
            - created
            - uploaded
            - processing
            - ready
            - error
        url:
          type: string
          nullable: true
          description: Public CDN URL for the asset
        downloadUrl:
          type: string
          nullable: true
          description: Download URL for the original file
        chapters:
          type: array
          items:
            $ref: '#/components/schemas/MediaChapter'
          description: Included when _expand contains 'chapters'
        entryDate:
          type: string
          format: date-time
    Item:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
          example: The Power of Prayer
        subTitle:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        shortDescription:
          type: string
          nullable: true
        date:
          type: string
          format: date
          example: '2025-01-15'
        collectionId:
          type: integer
        seriesId:
          type: integer
          nullable: true
        orderInSeries:
          type: integer
          nullable: true
        urlSlug:
          type: string
          nullable: true
        durationSecs:
          type: integer
          nullable: true
          description: Duration of the item's media in seconds
        status:
          type: string
          enum:
            - draft
            - queued
            - processing
            - ready
            - publishing
            - published
            - unpublishing
            - unpublished
            - actionRequired
            - error
        wizardStep:
          type: string
          enum:
            - basicDetails
            - artwork
            - media
            - processing
            - finalize
          description: Current step in the item creation wizard
        publishedDate:
          type: string
          format: date-time
          nullable: true
        autoPublish:
          type: boolean
          nullable: true
        squareImgUrl:
          type: string
          nullable: true
          description: URL for the square (1:1) artwork image
        wideImgUrl:
          type: string
          nullable: true
          description: URL for the wide (16:9) artwork image
        ultraWideImgUrl:
          type: string
          nullable: true
          description: URL for the ultra-wide (2.77:1) artwork image
        verticalImgUrl:
          type: string
          nullable: true
          description: URL for the vertical (2:3) artwork image
        entryDate:
          type: string
          format: date-time
          description: Date the item was created
        collection:
          $ref: '#/components/schemas/Collection'
          description: Included when _expand contains 'collection'
        series:
          $ref: '#/components/schemas/Series'
          nullable: true
          description: Included when _expand contains 'series'
        speakers:
          type: array
          items:
            $ref: '#/components/schemas/Speaker'
          description: Included when _expand contains 'speakers'
        scriptures:
          type: array
          items:
            $ref: '#/components/schemas/ItemScripture'
          description: Included when _expand contains 'scriptures'
        mediaAssets:
          type: array
          items:
            $ref: '#/components/schemas/MediaAsset'
          description: Included when _expand contains 'mediaAssets'
        resources:
          type: array
          items:
            $ref: '#/components/schemas/ItemResource'
          description: Included when _expand contains 'resources'
        suggestedDescription:
          type: string
          nullable: true
          description: AI-generated description awaiting acceptance
        suggestedShortDescription:
          type: string
          nullable: true
        errorMessage:
          type: string
          nullable: true
          description: Set when status is `error` or `actionRequired`
        indexedMediaAssetId:
          type: integer
          nullable: true
          description: The media asset whose transcript was embedded for search
        autoAcceptScriptures:
          type: boolean
          nullable: true
          description: Auto-accept AI-suggested scriptures without review
        autoAcceptMediaChapters:
          type: boolean
          nullable: true
        transcriptUrl:
          type: string
          nullable: true
          description: CDN URL for the raw transcript JSON
        topics:
          type: array
          items:
            $ref: '#/components/schemas/Topic'
          description: Included when _expand contains 'topics'
        squareImgMetadata:
          type: object
          additionalProperties: true
          nullable: true
        wideImgMetadata:
          type: object
          additionalProperties: true
          nullable: true
        ultraWideImgMetadata:
          type: object
          additionalProperties: true
          nullable: true
        verticalImgMetadata:
          type: object
          additionalProperties: true
          nullable: true
    MediaVariantType:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
          example: Sermon Video
        contentType:
          type: string
          enum:
            - video
            - audio
        indexable:
          type: boolean
          description: Whether this variant can be indexed for search
        displayOrder:
          type: integer
          description: Order shown to users
        collectionId:
          type: integer
    MediaChapter:
      type: object
      properties:
        id:
          type: integer
        itemId:
          type: integer
        mediaAssetId:
          type: integer
        title:
          type: string
          example: Introduction
        startMs:
          type: integer
          description: Chapter start time in milliseconds
        suggested:
          type: boolean
          nullable: true
          description: Whether this chapter was AI-suggested
        accepted:
          type: boolean
          nullable: true
          description: Whether a suggested chapter has been accepted
        hidden:
          type: boolean
          description: True if chapter is suggested but not accepted
    Collection:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: Sunday Sermons
        itemDescriptor:
          type: string
          enum:
            - sermon
            - message
            - teaching
            - episode
        contentFormat:
          type: string
          enum:
            - sermon
            - interview
          description: Shape of content in this collection
        fullService:
          type: boolean
          description: True if items are full services (not just a single sermon)
          default: false
        variantTypes:
          type: array
          items:
            $ref: '#/components/schemas/MediaVariantType'
          description: Included when _expand contains 'variantTypes'
    Series:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
          example: The Gospel of John
        subTitle:
          type: string
          nullable: true
        collectionId:
          type: integer
        description:
          type: string
          nullable: true
        shortDescription:
          type: string
          nullable: true
        sortOrder:
          type: integer
        itemSortDirection:
          type: string
          enum:
            - ASC
            - DESC
          default: DESC
        showItemOrderInSeries:
          type: boolean
          default: true
        urlSlug:
          type: string
          nullable: true
        colorHex:
          type: string
          nullable: true
          example: '#FF5733'
        squareImgUrl:
          type: string
          nullable: true
          description: Full URL to the square artwork (1:1 aspect ratio)
        wideImgUrl:
          type: string
          nullable: true
          description: Full URL to the wide artwork (16:9 aspect ratio)
        ultraWideImgUrl:
          type: string
          nullable: true
          description: Full URL to the ultra-wide artwork (2.77:1 aspect ratio)
        published:
          type: boolean
          nullable: true
        verticalImgUrl:
          type: string
          nullable: true
        squareImgMetadata:
          type: object
          additionalProperties: true
          nullable: true
        wideImgMetadata:
          type: object
          additionalProperties: true
          nullable: true
        ultraWideImgMetadata:
          type: object
          additionalProperties: true
          nullable: true
        verticalImgMetadata:
          type: object
          additionalProperties: true
          nullable: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
          description: Included when _expand contains 'items'
        collection:
          allOf:
            - $ref: '#/components/schemas/Collection'
          nullable: true
          description: Included when _expand contains 'collection'
    Speaker:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
          example: Pastor John Smith
        bio:
          type: string
          nullable: true
        imageUrl:
          type: string
          nullable: true
          description: Full URL to the speaker's image
        imageFilename:
          type: string
          nullable: true
          description: Raw filename; clients should use `imageUrl` instead
        itemCount:
          type: integer
          nullable: true
          description: >-
            Item count for this speaker; populated when sorted by
            `_orderBy=itemCount` or expanded with `_expand=items`
    ItemScripture:
      type: object
      properties:
        id:
          type: integer
        itemId:
          type: integer
        book:
          type: string
          description: Bible book code (e.g., 'GEN', 'MAT', 'REV')
        bookName:
          type: string
          description: Full name of the Bible book
          example: Matthew
        chapter:
          type: integer
        verseStart:
          type: integer
        verseEnd:
          type: integer
        keyVerse:
          type: boolean
          nullable: true
          description: Whether this is a key scripture for the item
        suggested:
          type: boolean
          nullable: true
          description: Whether this scripture was AI-suggested
        accepted:
          type: boolean
          nullable: true
          description: Whether a suggested scripture has been accepted
        displayOrder:
          type: integer
          nullable: true
        citation:
          type: string
          description: Formatted citation string
          example: Matthew 5:1-12
        hidden:
          type: boolean
          description: >-
            True if scripture is suggested but not accepted (and not a key
            verse)
    ItemResource:
      type: object
      properties:
        id:
          type: integer
        itemId:
          type: integer
        title:
          type: string
        subTitle:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        resourceTypeId:
          type: integer
          nullable: true
        displayOrder:
          type: integer
          nullable: true
        contentType:
          type: string
          enum:
            - file
            - link
            - video
        fileMimeType:
          type: string
          nullable: true
        fileSizeBytes:
          type: integer
          nullable: true
        externalPlatform:
          type: string
          enum:
            - youtube
            - vimeo
          nullable: true
        externalPlatformId:
          type: string
          nullable: true
        thumbnailImgUrl:
          type: string
          nullable: true
          description: URL to the resource thumbnail image
        url:
          type: string
          nullable: true
          description: URL to access the resource (file URL or external link)
        resourceType:
          allOf:
            - $ref: '#/components/schemas/ResourceType'
          nullable: true
          description: Included when _expand contains 'resourceType'
        linkTarget:
          type: string
          nullable: true
          description: Target URL for link-type resources
    Topic:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        itemCount:
          type: integer
          nullable: true
          description: Included when _expand contains 'itemCount'
    ResourceType:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
          description: Display name for the resource category
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Enter your API token from the Haystack dashboard

````