Skip to content
GrouperlyGrouperly Docs

The photos and videos in an album the person can see

GET
/groups/{groupId}/albums/{albumId}/items
curl --request GET \
  --url 'https://app.grouperly.com/api/v2/groups/example/albums/example/items?limit=50' \
  --header 'Authorization: Bearer <token>'

By each item’s visibility (leaders only, attendees, members, or public; leaders and the uploader always). An event album reads as the day happened (oldest first); others newest first.

Display copies only: originals, which keep location data, stay in Grouperly. Without roster.youth.read an app gets no captions or tags, since they name the people in a photo, and neither it nor a key gets a photo or video a young person uploaded (2.21.0).

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
groupId
required
string

The credential’s group

albumId
required
string

An album in the group

Query Parameters

Section titled “Query Parameters”
limit
integer
default: 50 >= 1 <= 200

Items per page

cursor
string

From the previous page’s nextCursor; opaque

Responses

Section titled “Responses”

200

Section titled “200”

OK

Media typeapplication/json
object
items
required
Array<object>
object
id
required
string
albumId
required
string
kind
required
string
Allowed values: PHOTO VIDEO
width
required
integer | null
height
required
integer | null
durationSec
required

Videos only

number | null
takenAt
required

From the photo’s or video’s own metadata

string | null format: date-time
caption
required

Null for an app without roster.youth.read: captions name the people in a photo

string | null
tags
required

Empty for an app without roster.youth.read: tags name the people in a photo

Array<string>
visibility
required

Who sees it: its own setting, else its album’s

string
Allowed values: LEADERS ATTENDEES MEMBERS PUBLIC
uploadedBy
required
object
userId
required
string
name
required

Null for a youth’s upload to an app without roster.youth.read

string | null
thumbUrl
required

A small JPEG, until linksExpireAt

string
displayUrl
required

The display copy (a JPEG up to 2048 px, or the video), until linksExpireAt

string
linksExpireAt
required

At least an hour away; the links are the same for every request within the hour, so they cache

string format: date-time
createdAt
required
string format: date-time
nextCursor
required

Pass as ?cursor= for the next page; null on the last page.

string | null
Example
{
  "items": [
    {
      "kind": "PHOTO",
      "visibility": "LEADERS"
    }
  ]
}

Headers

Section titled “Headers”
X-RateLimit-Limit
integer

Requests allowed per minute for this credential

X-RateLimit-Remaining
integer

Requests left in this window

X-RateLimit-Reset
integer

When the window ends (Unix seconds)

400

Section titled “400”

A query parameter is malformed or unknown (invalid_parameter, with parameter)

Media typeapplication/json
object
error
required
object
code
required

Stable and machine-readable: unauthorized, forbidden, insufficient_scope, key_owner_not_leader, app_not_installed, scope_not_allowed, app_suspended, rate_limited, not_found, invalid_parameter, invalid_body, invalid_profile, invalid_descriptor, no_profile, already_exists, not_a_member, position_inactive, position_full, already_assigned, assignment_ended, version_not_current, nothing_to_pay, payments_not_ready, payload_too_large, first_party_only, terms_required, child_account, assistant_off, not_for_assistant, assistant_failed, not_a_draft, storage_full, unavailable, internal_error. New codes may be added.

string
message
required

For people; wording may change.

string
parameter

The query parameter (invalid_parameter) or body field (invalid_body, not_a_member) at fault.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "parameter": "example"
  }
}

Headers

Section titled “Headers”
X-RateLimit-Limit
integer

Requests allowed per minute for this credential

X-RateLimit-Remaining
integer

Requests left in this window

X-RateLimit-Reset
integer

When the window ends (Unix seconds)

401

Section titled “401”

Missing, unknown, revoked or expired credential (unauthorized)

Media typeapplication/json
object
error
required
object
code
required

Stable and machine-readable: unauthorized, forbidden, insufficient_scope, key_owner_not_leader, app_not_installed, scope_not_allowed, app_suspended, rate_limited, not_found, invalid_parameter, invalid_body, invalid_profile, invalid_descriptor, no_profile, already_exists, not_a_member, position_inactive, position_full, already_assigned, assignment_ended, version_not_current, nothing_to_pay, payments_not_ready, payload_too_large, first_party_only, terms_required, child_account, assistant_off, not_for_assistant, assistant_failed, not_a_draft, storage_full, unavailable, internal_error. New codes may be added.

string
message
required

For people; wording may change.

string
parameter

The query parameter (invalid_parameter) or body field (invalid_body, not_a_member) at fault.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "parameter": "example"
  }
}

403

Section titled “403”

A key: wrong group (forbidden), missing scope (insufficient_scope), or its creator no longer leads the group (key_owner_not_leader). An app’s token: missing scope (insufficient_scope), the group hasn’t installed the app (app_not_installed) or allowed the scope (scope_not_allowed, the message has the consent link), the person may not do this in the group (forbidden), Grouperly paused the app (app_suspended), the person hasn’t accepted Grouperly’s current Terms (terms_required: refresh their token, then send them to the hub’s /account/welcome), or it’s a child’s account (child_account)

Media typeapplication/json
object
error
required
object
code
required

Stable and machine-readable: unauthorized, forbidden, insufficient_scope, key_owner_not_leader, app_not_installed, scope_not_allowed, app_suspended, rate_limited, not_found, invalid_parameter, invalid_body, invalid_profile, invalid_descriptor, no_profile, already_exists, not_a_member, position_inactive, position_full, already_assigned, assignment_ended, version_not_current, nothing_to_pay, payments_not_ready, payload_too_large, first_party_only, terms_required, child_account, assistant_off, not_for_assistant, assistant_failed, not_a_draft, storage_full, unavailable, internal_error. New codes may be added.

string
message
required

For people; wording may change.

string
parameter

The query parameter (invalid_parameter) or body field (invalid_body, not_a_member) at fault.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "parameter": "example"
  }
}

Headers

Section titled “Headers”
X-RateLimit-Limit
integer

Requests allowed per minute for this credential

X-RateLimit-Remaining
integer

Requests left in this window

X-RateLimit-Reset
integer

When the window ends (Unix seconds)

404

Section titled “404”

Not found (not_found)

Media typeapplication/json
object
error
required
object
code
required

Stable and machine-readable: unauthorized, forbidden, insufficient_scope, key_owner_not_leader, app_not_installed, scope_not_allowed, app_suspended, rate_limited, not_found, invalid_parameter, invalid_body, invalid_profile, invalid_descriptor, no_profile, already_exists, not_a_member, position_inactive, position_full, already_assigned, assignment_ended, version_not_current, nothing_to_pay, payments_not_ready, payload_too_large, first_party_only, terms_required, child_account, assistant_off, not_for_assistant, assistant_failed, not_a_draft, storage_full, unavailable, internal_error. New codes may be added.

string
message
required

For people; wording may change.

string
parameter

The query parameter (invalid_parameter) or body field (invalid_body, not_a_member) at fault.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "parameter": "example"
  }
}

Headers

Section titled “Headers”
X-RateLimit-Limit
integer

Requests allowed per minute for this credential

X-RateLimit-Remaining
integer

Requests left in this window

X-RateLimit-Reset
integer

When the window ends (Unix seconds)

429

Section titled “429”

Rate limited (rate_limited)

Media typeapplication/json
object
error
required
object
code
required

Stable and machine-readable: unauthorized, forbidden, insufficient_scope, key_owner_not_leader, app_not_installed, scope_not_allowed, app_suspended, rate_limited, not_found, invalid_parameter, invalid_body, invalid_profile, invalid_descriptor, no_profile, already_exists, not_a_member, position_inactive, position_full, already_assigned, assignment_ended, version_not_current, nothing_to_pay, payments_not_ready, payload_too_large, first_party_only, terms_required, child_account, assistant_off, not_for_assistant, assistant_failed, not_a_draft, storage_full, unavailable, internal_error. New codes may be added.

string
message
required

For people; wording may change.

string
parameter

The query parameter (invalid_parameter) or body field (invalid_body, not_a_member) at fault.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "parameter": "example"
  }
}

Headers

Section titled “Headers”
X-RateLimit-Limit
integer

Requests allowed per minute for this credential

X-RateLimit-Remaining
integer

Requests left in this window

X-RateLimit-Reset
integer

When the window ends (Unix seconds)

Retry-After
integer

Seconds to wait

503

Section titled “503”

An app’s token for someone new, while Grouperly’s sign-in can’t be reached (unavailable); try again

Media typeapplication/json
object
error
required
object
code
required

Stable and machine-readable: unauthorized, forbidden, insufficient_scope, key_owner_not_leader, app_not_installed, scope_not_allowed, app_suspended, rate_limited, not_found, invalid_parameter, invalid_body, invalid_profile, invalid_descriptor, no_profile, already_exists, not_a_member, position_inactive, position_full, already_assigned, assignment_ended, version_not_current, nothing_to_pay, payments_not_ready, payload_too_large, first_party_only, terms_required, child_account, assistant_off, not_for_assistant, assistant_failed, not_a_draft, storage_full, unavailable, internal_error. New codes may be added.

string
message
required

For people; wording may change.

string
parameter

The query parameter (invalid_parameter) or body field (invalid_body, not_a_member) at fault.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "parameter": "example"
  }
}