Developer Platform

REST API Reference

Integrate seamlessly with Bloom Radio. Manage podcasts, publish episodes automatically, and extend functionality.

1 Authentication

All API requests to Bloom Radio must be authenticated using a valid API Bearer token.

HTTP Header Example
cURL 
curl -H "x-api-key: YOUR_API_KEY" \
  https://bloom.taptapp.xyz/api/podcast
Permission Scopes

Tokens should be strictly scoped. Keys can have read, write, or delete permissions. An endpoint will return a 403 Forbidden if the key lacks the correct scope.

2 Podcasts Endpoints

APIs to list, detail, create, and manage your podcasts.

GET /api/podcast

Description

Returns a list of all podcasts associated with the authenticated user. Optionally, pass an id parameter to fetch one.

Response Object 
{
  "podcasts": [
    {
      "id": "abc_12345",
      "title": "Design Systems Daily",
      "description": "A podcast about UI components.",
      "author": "Jane Doe",
      "category": "Technology",
      "user_id": "usr_999"
    }
  ]
}
POST /api/podcast Write Scope Required

Payload Request

title Required / String
author Required / String
email Required / String
description Optional / String
category Optional / String

Success Response 

{
  "success": true,
  "id": "nw_pod_98765"
}
PUT /api/podcast Write Scope Required

Payload Request

id Required / String
Other fields optional (title, author, email, etc.)

Success Response 

{
  "success": true
}
DELETE /api/podcast?id=PODCAST_ID Delete Scope Required

Permanently drops a podcast via a query parameter. Proceed with caution. 

{
  "success": true,
  "message": "Podcast deleted"
}

3 Episodes Endpoints

Integrations specifying audio multipart forms and metadata publishing.

GET /api/episode

Description

Returns episodes for the authenticated user. Pass id to get a specific one, or podcast_id to filter by podcast.

Response Object 
{
  "episodes": [
    {
      "id": "ep_123",
      "title": "Welcome",
      "podcast_id": "abc_12345"
    }
  ]
}
POST /api/episode Multipart/Form-Data Required

Episodes require an audio file stream. Because of this, standard JSON payloads are not accepted here. You must transmit the data over multipart/form-data.

Fields

file Required / Audio Blob
title Required / String
podcast_id Required / String
description Optional / String

cURL Example 

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -F "title=My First EP" \
  -F "podcast_id=abc_123" \
  -F "file=@/path/audio.mp3" \
  https://bloom.taptapp.xyz/api/episode
PUT /api/episode Write Scope Required

Update an episode. If updating the audio file, send via multipart/form-data with the id and file. If updating only metadata, a standard JSON payload with id works. 

{
  "success": true,
  "message": "Episode updated successfully"
}
DELETE /api/episode?id=EPISODE_ID Delete Scope Required

Permanently drops an episode via a query parameter. 

{
  "success": true,
  "message": "Episode deleted successfully"
}

Standardized Errors

Always expect identical structures for HTTP errors enabling graceful handling.

400 Bad Request (missing payload)
401 Unauthorized (invalid token)
403 Forbidden (lacking scope)
404 Not Found (invalid database ID) 
{
  "error": "The 'title' field is missing from payload request.",
  "status": 400
}