Unofficial OpenAPI 3.0 specification for the BSA Scoutbook / Scouting.org API. This spec documents the REST endpoints that power Scoutbook and Scouting.org — the same APIs used by the official web interface.
This specification is the foundation for:
- scoutbook-ai-mcp — MCP server exposing Scoutbook data as AI-callable tools
- trailcache — Offline-capable Scoutbook data viewer for desktop and terminal
All API requests (except the login endpoint) require a JWT bearer token obtained by authenticating against the auth server.
POST https://auth.scouting.org/api/users/{username}/authenticate
The returned JWT is passed as a standard Authorization: Bearer <token> header on all subsequent requests. Tokens expire after approximately 7 hours.
| Server | URL | Purpose |
|---|---|---|
| Main API | https://api.scouting.org |
All data endpoints |
| Auth | https://auth.scouting.org |
Authentication and token issuance |
The API uses two primary identifier types:
- Person GUID (
personGuid, UUID format) — used for most person-related endpoints (profile, roles, memberships, training, relationships) - User ID (
userId, numeric integer) — used for youth advancement endpoints (ranks, merit badges, awards, adventures, activities, calendars) - Organization GUID (
organizationGuid, UUID format) — used for all unit/org endpoints (rosters, dashboards, events, commissioner tools)
GUIDs and user IDs for the authenticated user can be discovered via the profile and toolkit endpoints after login.
Many endpoints exist in both v1 (no version prefix) and v2 (/v2/ in path):
- v2 endpoints are generally preferred — they offer enhanced data and better structure
- v1 endpoints remain useful for reference data (complete rank/badge catalogs) or where v2 doesn't exist
- Some v1 endpoints split into multiple v2 endpoints (e.g.,
/persons/{id}/trainings→ separate/ypt+/positionTrainingRequirements)
| Method | Path | Description |
|---|---|---|
| POST | /api/users/{username}/authenticate |
Authenticate and obtain JWT bearer token |
Person profiles, roles, toolkits, subscriptions, and relationships.
| Method | Path | Description |
|---|---|---|
| GET | /persons/{personGuid}/profile |
Get person profile |
| GET | /persons/{personGuid}/roleTypes |
Get person role types |
| GET | /persons/{personGuid}/subscriptions |
Get person subscriptions |
| GET | /persons/{personGuid}/renewalRelationships |
Get renewal relationships |
| GET | /persons/{userId}/myScout |
Get "my scout" relationships |
| GET | /persons/v2/{personGuid}/personprofile |
Get person profile (v2) |
| GET | /persons/v2/{userId}/personprofile |
Get person profile by user ID (v2) |
| GET | /persons/v2/{personGuid}/parentGuardianInvitation |
Get parent/guardian invitations |
| GET | /persons/v2/{personGuid}/relationships |
Get person relationships (v2) |
| GET | /persons/v2/{personGuid}/toolkits |
Get accessible organizations/toolkits |
| GET | /persons/v2/{personGuid}/{organizationGuid}/tools |
Get tools for a specific organization |
Youth, adult, and parent rosters, subunits, key3, and org profile.
| Method | Path | Description |
|---|---|---|
| GET | /organizations/v2/{organizationGuid}/profile |
Organization profile |
| GET | /organizations/v2/{organizationGuid}/key3 |
Key 3 leadership |
| GET | /organizations/v2/{organizationGuid}/orgAdults |
Adult roster |
| GET | /organizations/v2/{organizationGuid}/orgYouths |
Youth roster |
| GET | /organizations/v2/units/{organizationGuid}/adults |
Unit adults (alternate) |
| GET | /organizations/v2/units/{organizationGuid}/parents |
Parent roster |
| GET | /organizations/v2/units/{organizationGuid}/subUnits |
Subunits (patrols/dens) |
| GET | /organizations/v2/units/{organizationGuid}/youths |
Unit youths (alternate) |
YPT status, training records, and position training requirements.
| Method | Path | Description |
|---|---|---|
| GET | /persons/{personGuid}/trainings |
All training records (v1) |
| GET | /persons/v2/{personGuid}/trainings/ypt |
Youth Protection Training status |
| GET | /persons/v2/{personGuid}/trainings/positionTrainingRequirements |
Position-specific training requirements |
| GET | /organizations/{organizationGuid}/orgTrainingSummary |
Org-wide training summary |
Memberships, positions, registrations, renewals, recharter, and OLR dashboards.
| Method | Path | Description |
|---|---|---|
| GET | /persons/{personGuid}/memberships |
Person memberships |
| GET | /persons/{personGuid}/positions |
Person positions |
| GET | /persons/v2/{personGuid}/membershipRegistrations |
Membership registrations (v2) |
| GET | /organizations/{organizationGuid}/leads |
Organization leads |
| GET | /organizations/{organizationGuid}/membershipSummary |
Membership summary |
| GET | /organizations/{organizationGuid}/olrSettings |
OLR settings |
| GET | /organizations/{organizationGuid}/pin |
Organization PIN |
| GET | /organizations/v2/{organizationGuid}/OLRDashboard |
OLR dashboard |
| GET | /organizations/v2/{organizationGuid}/OLRLeadsDashboard |
OLR leads dashboard |
| GET | /organizations/v2/{organizationGuid}/leadDashboard |
Lead dashboard |
| GET | /organizations/v2/{organizationGuid}/registrations |
Registrations |
| GET | /organizations/v2/{organizationGuid}/renewalDashboard |
Renewal dashboard |
| GET | /organizations/v2/{organizationGuid}/youthMembershipDashboard |
Youth membership dashboard |
| POST | /registrations/v2/{organizationGuid}/validateForRecharter |
Validate recharter readiness |
Rank, merit badge, award, and adventure definitions and their requirements.
| Method | Path | Description |
|---|---|---|
| GET | /advancements/ranks |
All rank definitions |
| GET | /advancements/meritBadges |
All merit badge definitions (v1) |
| GET | /advancements/awards |
All award definitions |
| GET | /advancements/awards/{awardId} |
Single award detail |
| GET | /advancements/adventures |
All adventure definitions |
| GET | /advancements/ssElectives |
Shooting Sports electives |
| GET | /advancements/v2/meritBadges |
All merit badge definitions (v2) |
| GET | /advancements/v2/meritBadges/{meritBadgeId} |
Single merit badge detail (v2) |
| GET | /advancements/v2/ranks/{rankId} |
Single rank detail (v2) |
| GET | /advancements/ranks/{rankId}/requirements |
Rank requirements (v1) |
| GET | /advancements/meritBadges/{meritBadgeId}/requirements |
Merit badge requirements (v1) |
| GET | /advancements/awards/{awardId}/requirements |
Award requirements |
| GET | /advancements/adventures/{adventureId}/requirements |
Adventure requirements |
| GET | /advancements/v2/ranks/{rankId}/requirements |
Rank requirements (v2) |
| GET | /advancements/meritBadges/counselors/{userId}/profile |
Merit badge counselor profile |
Per-youth ranks, merit badges, awards, adventures, requirements, and leadership history.
| Method | Path | Description |
|---|---|---|
| GET | /advancements/v2/youth/{userId}/ranks |
Youth rank progress |
| GET | /advancements/v2/youth/{userId}/meritBadges |
Youth merit badge progress |
| GET | /advancements/v2/youth/{userId}/meritBadges/{meritBadgeId} |
Youth single merit badge detail |
| GET | /advancements/v2/youth/{userId}/awards |
Youth award progress |
| GET | /advancements/v2/youth/{userId}/adventures |
Youth adventure progress |
| GET | /advancements/v2/youth/{userId}/ranks/{rankId}/requirements |
Youth rank requirement status |
| GET | /advancements/v2/youth/{userId}/meritBadges/{meritBadgeId}/requirements |
Youth merit badge requirement status |
| GET | /advancements/v2/youth/{userId}/awards/{awardId}/requirements |
Youth award requirement status |
| GET | /advancements/youth/{userId}/leadershipPositionHistory |
Youth leadership position history |
Organization-wide advancement history and ready-to-award reports.
| Method | Path | Description |
|---|---|---|
| GET | /advancements/advancementHistory |
Advancement history (filterable by org, date range, type) |
| GET | /organizations/{organizationGuid}/advancementsReadyToBeAwarded |
Advancements ready to be awarded |
Calendar entries, events, guests, and event communications.
| Method | Path | Description |
|---|---|---|
| GET | /advancements/events |
List events (filterable) |
| GET | /advancements/events/{eventId} |
Event detail |
| GET | /advancements/v2/events/{eventId}/guests |
Event guest list |
| GET | /advancements/v2/users/{userId}/calendars |
User calendar entries |
| GET | /events/communications/organizations |
Event communications |
Activity logging for camping, hiking, and service hours.
| Method | Path | Description |
|---|---|---|
| GET | /advancements/v2/activities |
List activities (filterable) |
| GET | /advancements/activities/{activityId} |
Activity detail |
| GET | /advancements/v2/{userId}/userActivitySummary |
User activity summary |
Advancement, renewal, activities, and roundtable dashboards plus supply orders.
| Method | Path | Description |
|---|---|---|
| GET | /organizations/councils |
List councils |
| GET | /organizations/positions/{guid} |
Organization positions |
| GET | /organizations/v2/{organizationGuid}/advancementDashboard |
Advancement dashboard |
| GET | /organizations/v2/{organizationGuid}/unitAdvancementDashboard |
Unit advancement dashboard |
| GET | /organizations/v2/{organizationGuid}/unitActivitiesDashboard |
Unit activities dashboard |
| GET | /organizations/v2/{organizationGuid}/unitRenewalStatusDashboard |
Unit renewal status dashboard |
| GET | /organizations/v2/{organizationGuid}/unitRoundtableAttendance |
Roundtable attendance |
| GET | /organizations/v2/{organizationGuid}/orders |
Supply orders |
Commissioner assignments, roundtable, and unit health.
| Method | Path | Description |
|---|---|---|
| GET | /commissioners/v2/organizations/{organizationGuid}/units/assignedCommissioners |
Assigned commissioners |
| GET | /commissioners/v2/organizations/{organizationGuid}/roundtable |
Roundtable data |
| GET | /commissioners/v2/organizations/{organizationGuid}/unitsHealth/details |
Unit health details |
| GET | /commissioners/v2/organizations/{organizationGuid}/unitsHealth/manualEntry |
Unit health manual entries |
Reference data for forms, validation, and display.
| Method | Path | Description |
|---|---|---|
| GET | /lookups/address/countries |
Countries |
| GET | /lookups/address/states |
States |
| GET | /lookups/advancements/activityCategories |
Activity categories |
| GET | /lookups/advancements/activityCollaborativeOrganizations |
Collaborative organizations |
| GET | /lookups/advancements/activityTypes |
Activity types |
| GET | /lookups/advancements/meritBadgeCategories |
Merit badge categories |
| GET | /lookups/advancements/positions |
Advancement positions |
| GET | /lookups/advancements/ranks |
Rank lookup |
| GET | /lookups/advancements/swimmingClassification |
Swimming classifications |
| GET | /lookups/advancements/unitTimezone |
Unit timezones |
| GET | /lookups/advancements/youthLeadershipPositions |
Youth leadership positions |
| GET | /lookups/communications/communicationTypes |
Communication types |
| GET | /lookups/communications/mobilePhoneCarrier |
Mobile phone carriers |
| GET | /lookups/communications/phoneCountryCodes |
Phone country codes |
| GET | /lookups/organizations/unitTypes |
Unit types |
| GET | /lookups/organizations/units/specialInterestTypes |
Special interest types |
| GET | /lookups/person/ethnicities |
Ethnicities |
| GET | /lookups/person/genders |
Genders |
| GET | /lookups/person/grades |
Grades |
| GET | /lookups/person/nameSuffixes |
Name suffixes |
| GET | /lookups/person/positions |
Person positions |
| GET | /lookups/person/titlePrefixes |
Title prefixes |
| GET | /lookups/registrations/applicationStatus |
Application statuses |
| GET | /lookups/trainings/courses |
Training courses |
The openapi.yaml file can be loaded into any OpenAPI-compatible tool:
- Swagger Editor — paste or import for interactive browsing
- Code generation — use openapi-generator to generate client libraries in any language
- API testing — import into Postman, Insomnia, or Bruno
- Documentation — render with Redoc, Swagger UI, or Stoplight
This is an unofficial, community-maintained specification. It is not affiliated with, endorsed by, or supported by the Boy Scouts of America. The API may change without notice. Use responsibly and in accordance with BSA's terms of service.
MIT