Each song arrangement can have multiple keys. A key is the pitch center of the song.
| Property | Value |
|---|---|
| Product | Services (pco.services, API version 2018-11-01) |
| Resource type | Key |
| TypeScript | Services.Key, attributes Services.KeyAttributes, schema Services.KeySchema |
| Planning Center path | /services/v2/songs/{song_id}/arrangements/{arrangement_id}/keys |
| Planning Center docs | Key |
How to reach it
| Client path | Returns | Filters | Create |
|---|---|---|---|
pco.services.songs.id(songId).arrangements.id(arrangementId).keys |
Collection | Yes | |
pco.services.songs.id(songId).last_scheduled_item.id(itemId).key |
Collection | No |
From a collection, .id(keyId) addresses one Key: pco.services.songs.id(songId).arrangements.id(arrangementId).keys.id(keyId). Collections support where, include, order, and pagination; single resources have get().
Attributes
On Services.KeyAttributes. Every resource also has id and type ('Key') next to its attributes.
| Name | Type | Description |
|---|---|---|
alternate_keys |
string | null |
See details. |
created_at |
string | null |
|
ending_key |
string | null |
See details. |
ending_minor |
boolean | null |
|
name |
string | null |
|
starting_key |
string | null |
See details. |
starting_minor |
boolean | null |
|
updated_at |
string | null |
Attribute details
alternate_keys
An array of objects.
\{ "name": "My Alternate Key", "key": "B" \}
ending_key
Possible Values:
Ab, A, A#, Bb, B, C, C#, Db, D, D#, Eb, E, F, F#, Gb, G, G#, Abm, Am, A#m, Bbm, Bm, Cm, C#m, Dbm, Dm, D#m, Ebm, Em, Fm, F#m, Gbm, Gm, G#m
To set the key to minor append m to the key. e.g. Cm
starting_key
Possible Values:
Ab, A, A#, Bb, B, C, C#, Db, D, D#, Eb, E, F, F#, Gb, G, G#, Abm, Am, A#m, Bbm, Bm, Cm, C#m, Dbm, Dm, D#m, Ebm, Em, Fm, F#m, Gbm, Gm, G#m
To set the key to minor append m to the key. e.g. Cm
Relationships and includes
Planning Center documents no includes for this resource.
| Relationship | Type | To | Includable |
|---|---|---|---|
arrangement |
To one | Arrangement | No |
Querying
No documented where fields.
Order
order(...) accepts these fields, ascending, or descending with a - prefix: created_at, updated_at.
Edges
Follow these from one Key, ref = pco.services.songs.id(songId).arrangements.id(arrangementId).keys.id(keyId):
| Edge | Leads to | Returns | Filters | Create |
|---|---|---|---|---|
ref.attachments |
Attachment | Collection | Yes |
Writing
| Property | Value |
|---|---|
| Create | Yes, create() on keys on Arrangement |
| Update | Yes, update() on a reference |
| Delete | Yes, delete() on a reference |
Create attributes
Typed as Services.KeySchema['create'].
| Attribute | Type |
|---|---|
alternate_keys |
string | null |
ending_key |
string | null |
import_ccli_chord_chart |
unknown |
import_ccli_chord_chart_options |
unknown |
import_ccli_lyrics |
unknown |
import_chart_pro |
unknown |
import_rehearsal_mix |
unknown |
import_rehearsal_pack |
unknown |
name |
string | null |
starting_key |
string | null |
Update attributes
Typed as Services.KeySchema['update'].
| Attribute | Type |
|---|---|
alternate_keys |
string | null |
ending_key |
string | null |
import_ccli_chord_chart |
unknown |
import_ccli_chord_chart_options |
unknown |
import_ccli_lyrics |
unknown |
import_chart_pro |
unknown |
import_rehearsal_mix |
unknown |
import_rehearsal_pack |
unknown |
name |
string | null |
starting_key |
string | null |
See Writing data.
Example
import type { Services } from '@mackenly/planningcenterkit';
const songId = '1'; // Song id
const arrangementId = '1'; // Arrangement id
const page = await pco.services.songs.id(songId).arrangements.id(arrangementId).keys.order('created_at').perPage(25).list();
const items: Services.Key[] = page.data;