A song
| Property | Value |
|---|---|
| Product | Services (pco.services, API version 2018-11-01) |
| Resource type | Song |
| TypeScript | Services.Song, attributes Services.SongAttributes, schema Services.SongSchema |
| Planning Center path | /services/v2/songs |
| Planning Center docs | Song |
How to reach it
| Client path | Returns | Filters | Create |
|---|---|---|---|
pco.services.songs |
Collection | Yes | |
pco.services.songs.id(songId).last_scheduled_item.id(itemId).song |
Collection | No |
From a collection, .id(songId) addresses one Song: pco.services.songs.id(songId). Collections support where, include, order, and pagination; single resources have get().
Attributes
On Services.SongAttributes. Every resource also has id and type ('Song') next to its attributes.
| Name | Type | Description |
|---|---|---|
admin |
string | null |
|
author |
string | null |
|
ccli_number |
number | null |
|
copyright |
string | null |
|
created_at |
string | null |
|
hidden |
boolean | null |
|
last_scheduled_at |
string | null |
|
last_scheduled_short_dates |
string | null |
|
notes |
string | null |
|
themes |
string | null |
|
title |
string | null |
See details. |
updated_at |
string | null |
Attribute details
title
The name of the song.
When setting this value on a create you can pass a CCLI number and Services will fetch the song metadata for you.
Querying
Where
where(field, value) for equality; where(field, op, value) with the operators listed.
| Field | Value type | Operators |
|---|---|---|
author |
string |
Equality only |
ccli_number |
number |
Equality only |
hidden |
boolean |
Equality only |
themes |
string |
Equality only |
title |
string |
Equality only |
Order
order(...) accepts these fields, ascending, or descending with a - prefix: created_at, last_scheduled_at, title, updated_at.
Edges
Follow these from one Song, ref = pco.services.songs.id(songId):
| Edge | Leads to | Returns | Filters | Create |
|---|---|---|---|---|
ref.arrangements |
Arrangement | Collection | Yes | |
ref.attachments |
Attachment | Collection | Yes | |
ref.last_scheduled_item |
Item | Collection | No | |
ref.song_schedules |
SongSchedule | Collection | after, before, most_recent, most_recent_with_upcoming, three_most_recent |
No |
ref.tags |
Tag | Collection | No | |
ref.unscoped_arrangements |
Arrangement | Collection | No |
Writing
| Property | Value |
|---|---|
| Create | Yes, create() on pco.services.songs |
| Update | Yes, update() on a reference |
| Delete | Yes, delete() on a reference |
Create attributes
Typed as Services.SongSchema['create'].
| Attribute | Type |
|---|---|
admin |
string | null |
author |
string | null |
ccli_number |
number | null |
copyright |
string | null |
hidden |
boolean | null |
import_ccli_chord_chart |
unknown |
import_ccli_chord_pro |
unknown |
import_ccli_lyrics |
unknown |
themes |
string | null |
title |
string | null |
Update attributes
Typed as Services.SongSchema['update'].
| Attribute | Type |
|---|---|
admin |
string | null |
author |
string | null |
ccli_number |
number | null |
copyright |
string | null |
hidden |
boolean | null |
themes |
string | null |
title |
string | null |
See Writing data.
Actions
Run with ref.action(name, body?). Bodies are untyped: see Planning Center’s docs for each action.
| Action | Path | Description |
|---|---|---|
assign_tags |
POST /services/v2/songs/{song_id}/assign_tags |
Used to assign tags to a song. |
Example
import type { Services } from '@mackenly/planningcenterkit';
const page = await pco.services.songs.order('created_at').perPage(25).list();
const items: Services.Song[] = page.data;