Quickstart

This reads a group’s details and its upcoming events with a group key, which is the quickest way in.

1. Make a group key

A group owner:

1. Opens the group in Grouperly, then Settings → Developers.
2. Under API access, creates a key with a name (“Calendar sync”) and the scopes it needs. For this quickstart, read is enough.
3. Copies the key. It starts gk_, and it’s shown only once.

A key belongs to one group. It acts as the leader who made it: if that person stops being a leader, the key stops working.

Caution

A key is a password for the group’s data. Keep it in a secret store or an environment variable, never in code or a spreadsheet anyone can open. If one leaks, revoke it in Settings → Developers and make another.

2. Find the group’s id

It’s in the group’s address in Grouperly: https://app.grouperly.com/groups/<groupId>.

3. Call the API

export GROUPERLY_KEY=gk_...
export GROUP_ID=...

# The group
curl -s https://app.grouperly.com/api/v2/groups/$GROUP_ID \
  -H "Authorization: Bearer $GROUPERLY_KEY"

# Events from today on, with their RSVP counts
curl -s "https://app.grouperly.com/api/v2/groups/$GROUP_ID/events?from=$(date -u +%Y-%m-%dT00:00:00Z)&include=rsvpCounts" \
  -H "Authorization: Bearer $GROUPERLY_KEY"

A list comes back as { "items": [...], "nextCursor": "..." }. Pass nextCursor back as ?cursor= until it’s null. See Conventions.

With the SDK

import { createGrouperlyClient, unwrap, allItems } from '@grouperly/sdk';

const grouperly = createGrouperlyClient({ token: process.env.GROUPERLY_KEY });

const group = unwrap(
  await grouperly.GET('/groups/{groupId}', { params: { path: { groupId } } })
);

for await (const event of allItems((cursor) =>
  grouperly.GET('/groups/{groupId}/events', {
    params: { path: { groupId }, query: { from: new Date().toISOString(), include: 'rsvpCounts', cursor } },
  })
)) {
  console.log(event.name, event.startsAt);
}

• Every path, parameter and response is typed from the OpenAPI document.
• unwrap returns the data, or throws a GrouperlyError with the API’s code, status and parameter.
• allItems follows nextCursor for you.

Next

• What each scope allows: Authentication.
• Being told when something changes, instead of polling: webhooks are still on v1 for now. A key with the webhooks:manage scope registers them with POST https://app.grouperly.com/api/v1/groups/{groupId}/webhooks, and Settings → Developers lists them.
• Every endpoint: the API reference.