A file, whether it’s stored on Planning Center or linked from another location.
| Property | Value |
|---|---|
| Product | Services (pco.services, API version 2018-11-01) |
| Resource type | Attachment |
| TypeScript | Services.Attachment, attributes Services.AttachmentAttributes, schema Services.AttachmentSchema |
| Planning Center path | /services/v2/media/{media_id}/attachments |
| Planning Center docs | Attachment |
How to reach it
| Client path | Returns | Filters | Create |
|---|---|---|---|
pco.services.songs.id(songId).arrangements.id(arrangementId).attachments |
Collection | Yes | |
pco.services.songs.id(songId).last_scheduled_item.id(itemId).attachments |
Collection | Yes | |
pco.services.songs.id(songId).last_scheduled_item.id(itemId).selected_attachment |
Collection | No | |
pco.services.songs.id(songId).last_scheduled_item.id(itemId).selected_background |
Collection | No | |
pco.services.songs.id(songId).arrangements.id(arrangementId).keys.id(keyId).attachments |
Collection | Yes | |
pco.services.media.id(mediaId).attachments |
Collection | Yes | |
pco.services.series.id(seriesId).plans.id(planId).all_attachments |
Collection | attachable_type, extensions |
No |
pco.services.series.id(seriesId).plans.id(planId).attachments |
Collection | Yes | |
pco.services.service_types.id(serviceTypeId).attachments |
Collection | Yes | |
pco.services.songs.id(songId).attachments |
Collection | Yes |
From a collection, .id(attachmentId) addresses one Attachment: pco.services.media.id(mediaId).attachments.id(attachmentId). Collections support where, include, order, and pagination; single resources have get().
Attributes
On Services.AttachmentAttributes. Every resource also has id and type ('Attachment') next to its attributes.
| Name | Type | Description |
|---|---|---|
allow_mp3_download |
boolean | null |
|
attachable_type |
string | null |
|
content |
string | null |
|
content_type |
string | null |
|
created_at |
string | null |
|
deleted_at |
string | null |
|
display_name |
string | null |
|
downloadable |
boolean | null |
|
file_size |
number | null |
|
file_upload_identifier |
string | null |
See details. |
filename |
string | null |
|
filetype |
string | null |
|
has_preview |
boolean | null |
|
import_to_item_details |
boolean | null |
|
licenses_purchased |
number | null |
|
licenses_remaining |
number | null |
|
licenses_used |
number | null |
|
linked_url |
string | null |
|
page_order |
string | null |
The shared order of pages to display for this file in Music Stand. Page numbers start at 1 and 0 inserts a blank page. Blank pages are left out of responses unless the request includes blank_pages=true. A person can override this for themselves with a PageOrder. |
pco_type |
string | null |
|
remote_link |
string | null |
|
streamable |
boolean | null |
|
thumbnail_url |
string | null |
|
transposable |
boolean | null |
|
updated_at |
string | null |
|
url |
string | null |
|
web_streamable |
boolean | null |
Attribute details
file_upload_identifier
Planning Center File UUID. Required only when creating a file attachment. See the “File Uploads” section of the API documentation for more information.
Only available when requested with the ?fields param
Relationships and includes
Side-load with include() (or get({ include })) and read with related(resource, name): zooms.
| Relationship | Type | To | Includable |
|---|---|---|---|
administrator |
To one | Person | No |
attachable |
To one | Plan | No |
attachment_types |
To many | AttachmentType | No |
created_by |
To one | Person | No |
updated_by |
To one | Person | No |
Querying
Where
where(field, value) for equality; where(field, op, value) with the operators listed.
| Field | Value type | Operators |
|---|---|---|
administrator_id |
string | number |
Equality only |
attachable_type |
string |
Equality only |
licenses_purchased |
number |
Equality only |
Order
order(...) accepts these fields, ascending, or descending with a - prefix: attachable_type, created_at, deleted_at, filename, filetype, size.
Filters
filter(...) names depend on the edge you query through:
| Edge | Filters |
|---|---|
all_attachments on Plan |
attachable_type, extensions |
Edges
Follow these from one Attachment, ref = pco.services.media.id(mediaId).attachments.id(attachmentId):
| Edge | Leads to | Returns | Filters | Create |
|---|---|---|---|---|
ref.zooms |
Zoom | Collection | Yes |
Writing
| Property | Value |
|---|---|
| Create | Yes, create() on attachments on Arrangement, attachments on Item, attachments on Key, attachments on Media, attachments on Plan, attachments on ServiceType, attachments on Song |
| Update | Yes, update() on a reference |
| Delete | Yes, delete() on a reference |
Create attributes
Typed as Services.AttachmentSchema['create'].
| Attribute | Type |
|---|---|
attachment_type_ids |
string[] |
content |
string | null |
file_upload_identifier |
string | null |
filename |
string | null |
import_to_item_details |
boolean | null |
page_order |
string | null |
remote_link |
string | null |
song_part |
unknown |
Update attributes
Typed as Services.AttachmentSchema['update'].
| Attribute | Type |
|---|---|
attachment_type_ids |
string[] |
content |
string | null |
file_upload_identifier |
string | null |
filename |
string | null |
import_to_item_details |
boolean | null |
page_order |
string | null |
remote_link |
string | null |
song_part |
unknown |
See Writing data.
Actions
Run with ref.action(name, body?). Bodies are untyped: see Planning Center’s docs for each action.
| Action | Path | Description |
|---|---|---|
open |
POST /services/v2/media/{media_id}/attachments/{attachment_id}/open |
This action is used to get the attachment file URL. |
preview |
POST /services/v2/media/{media_id}/attachments/{attachment_id}/preview |
This action is used to get a reduced resolution (preview) version of the attachment. |
Example
import type { Services } from '@mackenly/planningcenterkit';
const mediaId = '1'; // Media id
const page = await pco.services.media.id(mediaId).attachments.order('attachable_type').perPage(25).list();
const items: Services.Attachment[] = page.data;