Skip to main content

​
Overview

Playlists organize songs for worship services, rehearsals, and special events. Each playlist belongs to a church and optionally to a specific team. Access control ensures members only see playlists relevant to their teams.

​
Authentication

All endpoints require authentication:
  • Read: calendar.read (playlists are part of the calendar/scheduling system)
  • Create: Requires pastor, leader, or coordinator role
Authorization: Bearer YOUR_JWT_TOKEN

​
List Playlists

GET /api/playlists

Retrieve playlists for a church
Required Permission: calendar.read

​
Query Parameters

​
church_id
integer
Filter playlists by church ID. Defaults to authenticated user’s church.
​
churchId
integer
Alternative parameter for church_id
​
group_id
integer
Filter playlists by team/group ID
​
groupId
integer
Alternative parameter for group_id

​
Access Control

  • Pastors, Leaders, Coordinators: See all playlists for their church
  • Regular Members: Only see playlists for teams they belong to
  • Super Admins: See all playlists across all churches

​
Request

# All playlists for a church
curl -X GET "https://your-domain.com/api/playlists?church_id=1" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Playlists for a specific team
curl -X GET "https://your-domain.com/api/playlists?church_id=1&group_id=3" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Response

​
success
boolean
Indicates if the request was successful
​
playlists
array
Array of playlist objects
{
  "success": true,
  "playlists": [
    {
      "id": 1,
      "church_id": 1,
      "group_id": 3,
      "name": "Sunday Service - March 17",
      "description": "Morning worship service playlist",
      "created_by_member_id": 5,
      "created_by_name": "John Smith",
      "song_count": 6,
      "created_at": "2024-03-10 14:30:00"
    },
    {
      "id": 2,
      "church_id": 1,
      "group_id": null,
      "name": "Easter Sunday Set",
      "description": "Special Easter service songs",
      "created_by_member_id": 5,
      "created_by_name": "John Smith",
      "song_count": 8,
      "created_at": "2024-03-01 10:15:00"
    }
  ]
}

​
Get Playlist Details

GET /api/playlists/{id}

Retrieve detailed playlist information including all songs
Required Permission: calendar.read

​
Request Parameters

​
id
integer
required
The unique identifier of the playlist

​
Request

curl -X GET https://your-domain.com/api/playlists/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Response

{
  "success": true,
  "playlist": {
    "id": 1,
    "church_id": 1,
    "group_id": 3,
    "name": "Sunday Service - March 17",
    "description": "Morning worship service playlist",
    "created_by_member_id": 5,
    "created_at": "2024-03-10 14:30:00",
    "items": [
      {
        "id": 15,
        "songKey": "C",
        "song": {
          "id": 15,
          "title": "Great Are You Lord",
          "artist": "All Sons & Daughters",
          "original_key": "C",
          "tempo": "72 BPM",
          "category": "Worship",
          "content": "[Verse 1]..."          
        }
      },
      {
        "id": 22,
        "songKey": "G",
        "song": {
          "id": 22,
          "title": "10,000 Reasons",
          "artist": "Matt Redman",
          "original_key": "G",
          "tempo": "73 BPM",
          "category": "Praise"
        }
      }
    ]
  }
}

​
Error Response

Not Found (404) 
{
  "success": false,
  "error": "Playlist not found"
}

​
Create Playlist

POST /api/playlists

Create a new playlist
Required Permission: calendar.read + role in [pastor, leader, coordinator]

​
Request Body

​
name
string
required
The name of the playlist
​
church_id
integer
required
The church ID this playlist belongs to
​
churchId
integer
Alternative parameter for church_id
​
description
string
Optional description of the playlist
​
group_id
integer
Team/group ID this playlist is associated with
​
groupId
integer
Alternative parameter for group_id
​
songs
array
Array of song IDs to add to the playlist (in order)

​
Request

curl -X POST https://your-domain.com/api/playlists \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sunday Service - March 24",
    "church_id": 1,
    "group_id": 3,
    "description": "Palm Sunday service",
    "songs": [15, 22, 8, 31, 19, 42]
  }'

​
Response

{
  "success": true,
  "id": 5,
  "message": "Playlist created"
}

​
Process Details

  1. Creates the playlist record
  2. Adds songs in the specified order
  3. Logs activity in the system
  4. Returns the new playlist ID

​
Error Responses

Missing Required Fields (400) 
{
  "success": false,
  "error": "Name and Church ID required"
}
Insufficient Permissions (403) 
{
  "success": false,
  "error": "Insufficient permissions"
}

​
Playlist Visibility

​
Team-Specific Playlists

When group_id is set:
  • Only members of that team can see the playlist (unless they’re pastors/leaders)
  • Useful for rehearsals and team-specific services

​
Church-Wide Playlists

When group_id is null:
  • Visible to all authorized members of the church
  • Useful for main services and general planning

​
Song Order

Songs in a playlist maintain their order:
  1. The songs array index determines display order
  2. Songs appear in the items array in the same order
  3. Reordering requires updating the playlist (future endpoint)

​
Activity Logging

Playlist creation automatically logs an activity: 
{
  "church_id": 1,
  "member_id": 5,
  "action": "created",
  "entity_type": "playlist",
  "entity_id": 5,
  "details": {
    "name": "Sunday Service - March 24"
  }
}

​
Role Requirements

To create playlists, users must have one of these roles:
  • pastor - Senior leadership
  • leader - Ministry leaders
  • coordinator - Service coordinators
Regular members (member role) can view playlists but cannot create them.

​
Error Codes

CodeDescription
400Bad Request - Missing church_id or name
401Unauthorized - Invalid or missing token
403Forbidden - Insufficient role permissions
404Not Found - Playlist doesn’t exist
500Internal Server Error

​
Use Cases

​
Sunday Service Planning

{
  "name": "Sunday Morning - March 24",
  "church_id": 1,
  "group_id": 3,
  "description": "Regular Sunday service",
  "songs": [15, 22, 8, 31, 19]
}

​
Special Event

{
  "name": "Christmas Eve Service",
  "church_id": 1,
  "group_id": null,
  "description": "Traditional Christmas carols",
  "songs": [102, 105, 108, 112]
}

​
Team Rehearsal

{
  "name": "Worship Team Practice",
  "church_id": 1,
  "group_id": 3,
  "description": "Wednesday rehearsal set",
  "songs": [22, 31, 42]
}

Songs

Manage the song library

Calendar

Schedule services and assign playlists

Teams

Manage worship teams

Build docs developers (and LLMs) love

Get started for freeTalk to us