Skip to main content

Audio Management

Endpoints for managing audio files used in automation flows.

Audio File Listing​

GET /api/audio/files​

Gets all audio files.

Response:

{
  "success": true,
  "files": [
    {
      "name": "test-audio.mp3",
      "size": 1024000,
      "type": ".mp3",
      "createdAt": "2024-01-01T12:00:00.000Z",
      "modifiedAt": "2024-01-01T12:00:00.000Z"
    }
  ],
  "count": 1
}

Response Fields:

  • success: Boolean indicating request success
  • files: Array of audio file objects
    • name: File name
    • size: File size in bytes
    • type: File extension
    • createdAt: ISO timestamp when file was created
    • modifiedAt: ISO timestamp when file was last modified
  • count: Total number of audio files

GET /api/audio/files/:fileName​

Gets specific audio file information.

Parameters:

  • fileName: Audio file name

Response:

{
  "success": true,
  "file": {
    "name": "test-audio.mp3",
    "size": 1024000,
    "type": ".mp3",
    "createdAt": "2024-01-01T12:00:00.000Z",
    "modifiedAt": "2024-01-01T12:00:00.000Z"
  }
}

Error Response (404):

{
  "success": false,
  "error": "Audio file not found"
}

Audio Statistics​

GET /api/audio/stats​

Gets audio service statistics.

Response:

{
  "success": true,
  "stats": {
    "totalFiles": 10,
    "totalSize": 10240000,
    "totalSizeFormatted": "9.77 MB",
    "fileTypes": {
      ".mp3": 8,
      ".wav": 2
    }
  }
}

Response Fields:

  • stats: Statistics object
    • totalFiles: Total number of audio files
    • totalSize: Total size in bytes
    • totalSizeFormatted: Human-readable total size
    • fileTypes: Object mapping file extensions to counts

Audio File Upload​

POST /api/audio/upload​

Uploads an audio file.

Request:

  • Content-Type: multipart/form-data
  • Body: Form data with audioFile field
  • Optional: fileName field for custom filename

Supported Formats:

  • MP3 (.mp3)
  • WAV (.wav)
  • M4A (.m4a)
  • AAC (.aac)
  • OGG (.ogg)
  • FLAC (.flac)

File Size Limit: 50MB

Response:

{
  "success": true,
  "file": {
    "name": "test-audio.mp3",
    "size": 1024000,
    "type": ".mp3"
  },
  "message": "Audio file uploaded successfully"
}

Error Responses:

No file uploaded (400):

{
  "success": false,
  "error": "No file uploaded"
}

Invalid file type (400):

{
  "success": false,
  "error": "Invalid file type. Only audio files (.mp3, .wav, .m4a, .aac, .ogg, .flac) are allowed."
}

File too large (400):

{
  "success": false,
  "error": "File size exceeds limit"
}

Audio File Download​

GET /api/audio/download/:fileName​

Downloads a specific audio file.

Parameters:

  • fileName: Audio file name

Response:

  • Content-Type: Audio MIME type (e.g., audio/mpeg for MP3)
  • Content-Disposition: attachment; filename="fileName"
  • Body: Audio file stream

Error Response (404):

{
  "success": false,
  "error": "Audio file not found or inaccessible"
}

Audio File Management​

DELETE /api/audio/files/:fileName​

Deletes a specific audio file.

Parameters:

  • fileName: Audio file name

Response:

{
  "success": true,
  "message": "Audio file deleted successfully",
  "fileName": "test-audio.mp3"
}

Error Responses:

File not found (404):

{
  "success": false,
  "error": "FILE_NOT_FOUND",
  "message": "Audio file not found"
}

Invalid filename (400):

{
  "success": false,
  "error": "INVALID_FILENAME",
  "message": "Invalid filename"
}

PUT /api/audio/files/:fileName​

Renames an audio file.

Parameters:

  • fileName: Current audio file name

Request Body:

{
  "newFileName": "renamed-audio.mp3"
}

Response:

{
  "success": true,
  "message": "Audio file renamed successfully",
  "oldFileName": "test-audio.mp3",
  "newFileName": "renamed-audio.mp3"
}

Error Responses:

File not found (404):

{
  "success": false,
  "error": "FILE_NOT_FOUND",
  "message": "Audio file not found"
}

Invalid filename (400):

{
  "success": false,
  "error": "INVALID_FILENAME",
  "message": "Invalid filename"
}

Invalid extension (400):

{
  "success": false,
  "error": "INVALID_EXTENSION",
  "message": "Invalid file extension"
}

File already exists (409):

{
  "success": false,
  "error": "FILE_EXISTS",
  "message": "File with new name already exists"
}

Usage Examples​

List All Audio Files​

curl -X GET http://localhost:3000/api/audio/files

Get Audio File Info​

curl -X GET http://localhost:3000/api/audio/files/test-audio.mp3

Get Audio Statistics​

curl -X GET http://localhost:3000/api/audio/stats

Upload Audio File​

curl -X POST \
  -F "audioFile=@/path/to/audio.mp3" \
  -F "fileName=custom-name.mp3" \
  http://localhost:3000/api/audio/upload

Download Audio File​

curl -X GET \
  -o downloaded-audio.mp3 \
  http://localhost:3000/api/audio/download/test-audio.mp3

Delete Audio File​

curl -X DELETE http://localhost:3000/api/audio/files/test-audio.mp3

Rename Audio File​

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{"newFileName": "renamed-audio.mp3"}' \
  http://localhost:3000/api/audio/files/test-audio.mp3

Integration Notes​

  • Audio files are stored in the server's audio directory
  • Temporary upload files are automatically cleaned up after processing
  • File validation checks both MIME type and file extension
  • Supported audio formats are validated on upload
  • File operations are atomic to prevent corruption
  • Temporary files older than 24 hours are automatically cleaned up