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

# Upload media file

> Uploads a new audio file for use with AI agents. Only audio content types (audio/*) are accepted.
The uploaded file can be used for hold music, background sounds, or other audio features.

## Supported Formats

Only audio files are accepted. Supported formats include:

* MP3 (audio/mpeg)
* WAV (audio/wav)
* OGG (audio/ogg)
* Other audio/\* MIME types

## File Requirements

* File cannot be empty
* Content-Type header must start with `audio/`
* Maximum file size limits apply (contact support for details)

## Use Cases

Uploaded media files can be used for:

* **Hold music** during call transfers
* **Background sounds** for ambient noise
* **Custom audio prompts**


## OpenAPI

````yaml https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/media
openapi: 3.0.4
info:
  title: Dasha BlackBox Agent API
  description: API for managing AI agents and calls
  contact:
    name: DashaAI Team
    email: support@dasha.ai
  version: v1
servers:
  - url: https://blackbox.dasha.ai
    description: Dasha BlackBox Agent API
security:
  - ApiKey: []
  - OAuth: []
tags:
  - name: ActivityLogs
  - name: Agents
  - name: AgentTestCases
  - name: CallResults
  - name: Calls
  - name: Chats
  - name: Copilot
  - name: CustomerData
  - name: Mcp
  - name: Media
  - name: Misc
  - name: PronunciationDictionaries
  - name: Providers
  - name: SipAliases
  - name: SipCredentials
  - name: SipPhoneNumbers
  - name: TextChat
  - name: TwilioProvider
  - name: Voice
  - name: WebhookTest
  - name: WebIntegrations
  - name: WebSocket
    description: WebSocket endpoints for real-time communication
paths:
  /api/v1/media:
    post:
      tags:
        - Media
      summary: Upload media file
      description: >-
        Uploads a new audio file for use with AI agents. Only audio content
        types (audio/*) are accepted.

        The uploaded file can be used for hold music, background sounds, or
        other audio features.
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
                - File
              type: object
              properties:
                File:
                  type: string
                  description: >-
                    Audio file to upload. Supported formats include MP3, WAV,
                    FLAC, and other common audio formats. The file is stored and
                    can be referenced by its ID in agent configurations for
                    transfers and ambient noise features.
                  format: binary
                Description:
                  maxLength: 1000
                  type: string
                  description: >-
                    Description of the media file's purpose or content. Useful
                    for organizing and identifying files when configuring
                    agents, especially when managing multiple media files for
                    different transfer scenarios or ambient sounds.
            encoding:
              File:
                style: form
              Description:
                style: form
      responses:
        '201':
          description: Media file uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaFileResponseDto'
        '400':
          description: Invalid file or non-audio content type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Authentication failed or API key is missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '502':
          description: Upstream service error
        '503':
          description: Service temporarily unavailable
        '504':
          description: Request timeout
components:
  schemas:
    MediaFileResponseDto:
      required:
        - contentType
        - createdTime
        - fileName
        - fileSizeBytes
        - id
        - originalFileName
      type: object
      properties:
        id:
          type: string
          description: >-
            Unique identifier for this media file. Use this ID when configuring
            agents to reference the file for warm transfers, cold transfers, or
            ambient noise features.
          format: uuid
        fileName:
          minLength: 1
          type: string
          description: >-
            Server-assigned filename used for internal storage. This may differ
            from the original filename and is generated to ensure uniqueness and
            avoid conflicts in the storage system.
        originalFileName:
          minLength: 1
          type: string
          description: >-
            Original filename as provided during upload. Preserved for display
            purposes and to help identify the file in the user interface.
        fileSizeBytes:
          type: integer
          description: >-
            File size in bytes. Useful for storage management and estimating
            bandwidth requirements when the file is played during calls.
          format: int64
        contentType:
          minLength: 1
          type: string
          description: >-
            MIME content type detected from the uploaded file. Common values
            include "audio/mpeg" for MP3 files, "audio/wav" for WAV files, and
            "audio/flac" for FLAC files. Used for proper content handling and
            playback.
        createdTime:
          type: string
          description: Timestamp when the media file was originally uploaded to the system.
          format: date-time
        description:
          type: string
          description: >-
            Description of the media file's purpose or content. Helps identify
            and organize files when managing multiple media files for different
            use cases. Null when no description has been provided.
          nullable: true
      additionalProperties: false
      description: >-
        Media file information including metadata, storage details, and usage
        context. Contains all data needed to reference the file in agent
        configurations and track its properties and lifecycle.
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
      additionalProperties: {}
  securitySchemes:
    ApiKey:
      type: http
      description: API Key Authentication (Bearer {key})
      scheme: Bearer
    OAuth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://auth.dasha.ai/connect/authorize
          scopes:
            platform_api: Platform API

````