Bloom Radio
API DOCS

API Reference

Authentication

All API requests require authentication using an API key. You can create and manage your API keys in the API Keys Management page.

Authentication Header

Include your API key in the Authorization header of your requests:

Authorization: Bearer YOUR_API_KEY

Permissions

API keys can have the following permissions:

Podcast Endpoints

GET /api/podcast

Retrieve all podcasts for the authenticated user.

Response

            
{
  "podcasts": [
    {
      "id": "ABC123",
      "title": "My Podcast",
      "description": "A podcast about interesting topics",
      "author": "John Doe",
      "email": "john@example.com",
      "image_url": "https://example.com/image.jpg",
      "language": "en",
      "category": "Technology",
      "explicit": false,
      "user_id": "user_123"
    }
  ]
}

GET /api/podcast?id=PODCAST_ID

Retrieve a specific podcast by ID.

Parameters

  • id (required) - The ID of the podcast to retrieve

Response

                    
{
  "podcast": {
    "id": "ABC123",
    "title": "My Podcast",
    "description": "A podcast about interesting topics",
    "author": "John Doe",
    "email": "john@example.com",
    "image_url": "https://example.com/image.jpg",
    "language": "en",
    "category": "Technology",
    "explicit": false,
    "user_id": "user_123"
  }
}

POST /api/podcast

Create a new podcast. Requires write permission.

Request Body

            
{
  "title": "My New Podcast",
  "description": "A podcast about interesting topics",
  "author": "John Doe",
  "email": "john@example.com",
  "image_url": "https://example.com/image.jpg",
  "language": "en",
  "category": "Technology",
  "explicit": false
}

Response

             
{
  "success": true,
  "id": "NEW_PODCAST_ID"
}

PUT /api/podcast

Update an existing podcast. Requires write permission.

Request Body

            
{
  "id": "PODCAST_ID",
  "title": "Updated Podcast Title",
  "description": "Updated description",
  "author": "John Doe",
  "email": "john@example.com",
  "image_url": "https://example.com/new-image.jpg",
  "language": "en",
  "category": "Technology",
  "explicit": false
}

Response

            
{
  "success": true,
  "message": "Podcast actualizado correctamente"
}

DELETE /api/podcast?id=PODCAST_ID

Delete a podcast. Requires delete permission.

Parameters

  • id (required) - The ID of the podcast to delete

Response

            
{
  "success": true,
  "message": "Podcast eliminado correctamente"
}

Episode Endpoints

GET /api/episode

Retrieve all episodes for the authenticated user.

Response

            
{
  "episodes": [
    {
      "id": "XYZ789",
      "title": "Episode 1",
      "description": "The first episode",
      "url": "https://example.com/episode1.mp3",
      "length": 12345678,
      "pubDate": "Wed, 01 Jan 2023 12:00:00 GMT",
      "duration": "30:45",
      "type": "audio/mpeg",
      "user_id": "user_123",
      "cover_image_url": "https://example.com/cover.jpg"
    }
  ]
}

GET /api/episode?id=EPISODE_ID

Retrieve a specific episode by ID.

Parameters

  • id (required) - The ID of the episode to retrieve

Response

            
{
          "episode": {
            "id": "XYZ789",
            "title": "Episode 1",
            "description": "The first episode",
            "url": "https://example.com/episode1.mp3",
            "length": 12345678,
            "pubDate": "Wed, 01 Jan 2023 12:00:00 GMT",
            "duration": "30:45",
            "type": "audio/mpeg",
            "user_id": "user_123",
            "cover_image_url": "https://example.com/cover.jpg"
          }
        }

POST /api/episode

Create a new episode. Requires write permission.

This endpoint accepts multipart/form-data to upload the audio file.

Form Data

  • file (required) - The audio file
  • title (required) - The episode title
  • description - The episode description
  • cover_image_url - URL to the episode cover image

Response

            
{
          "success": true,
          "id": "NEW_EPISODE_ID",
          "url": "https://example.com/episode.mp3"
        }

PUT /api/episode

Update an existing episode. Requires write permission.

This endpoint can accept either JSON data or multipart/form-data if updating the audio file.

JSON Request (without file update)

            
{
          "id": "EPISODE_ID",
          "title": "Updated Episode Title",
          "description": "Updated description",
          "cover_image_url": "https://example.com/new-cover.jpg"
        }

Form Data (with file update)

  • id (required) - The ID of the episode to update
  • file (required) - The new audio file
  • title - The updated episode title
  • description - The updated episode description
  • cover_image_url - URL to the updated episode cover image

Response

            
{
          "success": true,
          "message": "Episodio actualizado correctamente"
        }

DELETE /api/episode?id=EPISODE_ID

Delete an episode. Requires delete permission.

Parameters

  • id (required) - The ID of the episode to delete

Response

            
{
          "success": true,
          "message": "Episodio eliminado correctamente"
        }

API Key Endpoints

GET /api/apikey

Retrieve all API keys for the authenticated user.

Response

            
{
          "apiKeys": [
            {
              "id": "KEY_ID",
              "key": "API_KEY",
              "name": "My API Key",
              "user_id": "user_123",
              "created_at": "2023-01-01T12:00:00Z",
              "last_used_at": "2023-01-02T12:00:00Z",
              "permissions": "read,write",
              "active": true
            }
          ]
        }

GET /api/apikey?id=KEY_ID

Retrieve a specific API key by ID.

Parameters

  • id (required) - The ID of the API key to retrieve

Response

            
{
          "apiKey": {
            "id": "KEY_ID",
            "key": "API_KEY",
            "name": "My API Key",
            "user_id": "user_123",
            "created_at": "2023-01-01T12:00:00Z",
            "last_used_at": "2023-01-02T12:00:00Z",
            "permissions": "read,write",
            "active": true
          }
        }

POST /api/apikey

Create a new API key.

Request Body

            
{
          "name": "My New API Key",
          "permissions": "read,write"
        }

Response

            
{
          "success": true,
          "id": "NEW_KEY_ID",
          "key": "NEW_API_KEY",
          "name": "My New API Key",
          "permissions": "read,write"
        }

PUT /api/apikey

Update an existing API key.

Request Body

            
{
          "id": "KEY_ID",
          "name": "Updated API Key Name",
          "active": true,
          "permissions": "read,write,delete"
        }

Response

            
{
          "success": true,
          "message": "API key updated successfully"
        }

DELETE /api/apikey?id=KEY_ID

Delete an API key.

Parameters

  • id (required) - The ID of the API key to delete

Response

            
{
          "success": true,
          "message": "API key deleted successfully"
        }

Error Responses

All API endpoints return error responses in the following format: 

          
{
        "error": "Error message describing what went wrong"
      }

Common Error Status Codes