---
title: "Key (Services)"
description: "Each song arrangement can have multiple keys."
---

> Documentation Index
> Fetch the complete documentation index at: https://planningcenterkit.mackenly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Key (Services)

Each song arrangement can have multiple keys. A key is the pitch center of the song.

| Property | Value |
| --- | --- |
| Product | [Services](/reference/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](https://api.planningcenteronline.com/docs/apps/services/versions/2018-11-01/vertices/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](/guides/querying/); 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](#alternate-keys). |
| `created_at` | `string \| null` |  |
| `ending_key` | `string \| null` | See [details](#ending-key). |
| `ending_minor` | `boolean \| null` |  |
| `name` | `string \| null` |  |
| `starting_key` | `string \| null` | See [details](#starting-key). |
| `starting_minor` | `boolean \| null` |  |
| `updated_at` | `string \| null` |  |

### Attribute details

#### `alternate_keys` {#alternate-keys}

An array of objects.

`
\{
  "name": "My Alternate Key",
  "key": "B"
\}
`

#### `ending_key` {#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` {#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](/reference/services/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](/reference/services/attachment/) | Collection |  | Yes |

## Writing

| Property | Value |
| --- | --- |
| Create | Yes, `create()` on `keys` on [Arrangement](/reference/services/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](/guides/writing-data/).

## Example

```ts
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;
```

Source: https://planningcenterkit.mackenly.com/reference/services/key/index.mdx
