Skip to content

Key (Services)

Each song arrangement can have multiple keys.

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;

Type to search…

↑↓ navigate↵ selectEsc close