Information
- OpenAPI version:
3.1.0
Overview
Grouperly Platform API 2.26.4
Section titled “Grouperly Platform API 2.26.4”The public interface to Grouperly for apps such as Scoutosia. Guide, conventions and versioning policy: docs/specs/platform-api-v2.md.
v2 only ever adds: new endpoints, new optional parameters, new response fields, new enum values and error codes. Clients must ignore fields they don’t know. A breaking change means a v3, and v2 then stays supported for 12 months, announced with Deprecation and Sunset headers.
Lists take ?limit= (1–200, default 50) and ?cursor=, and return { items, nextCursor }. Money is { amount: “25.00”, currency: “USD” }. Times are ISO 8601 in UTC.
Credentials: a group key (one group, acting as the leader who made it), or an app’s access token for a signed-in person, which may do what its scopes, the group’s install of the app and the person’s own permission in the group all allow (DECISIONS #26). Most writes take only an app’s token: an operation without an x-scope has no group key scope.
Writes take a JSON object of at most 16 KB. An unknown, missing or malformed field is a 400 invalid_body naming it in parameter.
A key may make 120 requests a minute, shared with v1. A partner app may make 120 a minute for each person; first-party apps aren’t counted. An app calling as itself (its app secret) has its own 120 a minute.
Authentication
Section titled “Authentication”apiKey
Section titled “apiKey”Authorization: Bearer gk_… Scopes: read, contacts:write, events:write, messages:announce, webhooks:manage, documents:read, payments:read, rsvps:write. Each operation’s required scope is in its x-scope.
Security scheme type: http
Bearer format: gk_…
appToken
Section titled “appToken”A Cognito access token for the signed-in person, from Sign in with Grouperly with resource=https://api.grouperly.com. Ask for the scopes each operation lists (its x-app-scope); the group must also have the app installed with them.
Security scheme type: oauth2
Flow type: authorizationCode
Authorization URL: https://auth.grouperly.com/oauth2/authorize
Token URL: https://auth.grouperly.com/oauth2/token
Scopes:
- https://api.grouperly.com/me.read - see your name, email address, groups and how many unread messages you have
- https://api.grouperly.com/groups.read - see the group's name, details and subgroups
- https://api.grouperly.com/groups.write - change the group's details and add subgroups
- https://api.grouperly.com/members.read - see who the members are and their roles
- https://api.grouperly.com/roster.read - see the adults on the roster, and how many youth members there are
- https://api.grouperly.com/roster.write - add people to the roster and change their details
- https://api.grouperly.com/roster.youth.read - see youth members on the roster, with their birthdates and contact details
- https://api.grouperly.com/roster.youth.write - add and change youth members' details
- https://api.grouperly.com/guardians.read - see youth members' parents and guardians and how to reach them
- https://api.grouperly.com/events.read - see events
- https://api.grouperly.com/events.write - create and change events
- https://api.grouperly.com/rsvps.write - answer RSVPs for you
- https://api.grouperly.com/positions.read - see positions and who holds them
- https://api.grouperly.com/positions.write - create positions and assign people to them
- https://api.grouperly.com/documents.read - see documents
- https://api.grouperly.com/documents.write - save draft documents for you to check
- https://api.grouperly.com/media.read - see photos and videos
- https://api.grouperly.com/payments.read - see payments
- https://api.grouperly.com/payments.links - ask members for payments
- https://api.grouperly.com/messages.announce - send announcements to members
- https://api.grouperly.com/notifications.send - send notifications to members
- https://api.grouperly.com/cards.write - show its own cards on the group in Grouperly
- https://api.grouperly.com/join_requests.manage - accept and decline requests to join
- https://api.grouperly.com/follows.write - follow and unfollow groups for you
- https://api.grouperly.com/blueprints.apply - set up positions, events and subgroups from a template
- https://api.grouperly.com/app_data.rw - keep its own data for the group
- https://api.grouperly.com/directory.claim - claim a group's directory listing for you
- https://api.grouperly.com/network.use - use the network as you
- https://api.grouperly.com/ai.query - ask the assistant questions for you
appSecret
Section titled “appSecret”Authorization: Bearer gapp_… A registered app’s own secret, issued by Grouperly, for calls the app makes as itself (never a group’s data).
Security scheme type: http
Bearer format: gapp_…