OSM API Docs

Unofficial, community-driven OpenAPI documentation for the Online Scout Manager (OSM) API — reverse-engineered from real traffic by the City of Newcastle Scouts Digital Team.

OSM doesn't publish a public API specification. This project exists to fill that gap for developers building tools on top of OSM's platform, whether you're writing a custom badge tracker, a patrol planner, or anything else that helps leaders run their sections.

Warning

This documentation is provided as-is with no guarantees. OSM's API is undocumented and can change without notice. Endpoints, parameters, and response shapes described here were observed at the time of writing and may drift over time. Always test against the live API before relying on anything here. We are not affiliated with OSM — use at your own risk.

What's covered

The spec documents 80 endpoints (88 operations) across 14 categories, with request/response examples and schemas:

Category	Endpoints	What you can do
Startup	/ext/generic/startup/	Bootstrap a session — get roles, terms, permissions
Members	/ext/members/contact/, /ext/members/contact/actions/, /ext/members/patrols/, /ext/members/census/, /ext/members/flexirecords/, /ext/audittrail/, /ext/settings/parents/loginhistory/, /v3/members/contact/.../removalWarnings, /v3/members/review/...	List members, update fields (name, DOB, patrol, rank), create/remove/restore members, patrol points, flexi-records, transfers, portal logins
Badges	/ext/badges/records/, /ext/badges/badgesbyperson/, /ext/programme/clouds/	Available badges, requirement columns, per-member progress, completion records
Attendance	/ext/members/attendance/, /v3/members/attendance/visitors/...	Register data and layout, mark attendance, visitors, meeting badge requirements
Custom Data	/ext/customdata/	Read and update custom fields (contacts, consents, gender, etc.)
Email	/ext/members/email/, /ext/members/email/campaigns/, /ext/settings/emails/, /ext/members/sms/, /v3/members/email/...	Resolve recipients, compose/draft/send, campaign templates, delivery reports
Programme	/ext/programme/, /ext/programme/activities/, /ext/recipes/, /v3/programme/.../bookings, /v3/todo/...	Meeting summaries and details, activity library, recipes, parent bookings, meeting to-dos and projects
Events	/ext/events/summary/, /v3/events/event/..., /v3/kit/...	Event lists, details, attendance, payments, Parent Portal settings, timetable, kit lists
Finance	/v3/finances/accounting/..., /v3/comments/accounting/..., /ext/finances/onlinepayments/..., /ext/finances/invoices/summary/	Cashbook, categories, bank accounts and imports, budgets, annual report, expense cards, tracked items, Online Payments, comments
Files	.../uploads/, .../leader_resources/, .../attachments/files/ (action=manifest)	Shared file-attachment manifest pattern
Dashboard	/ext/dashboard/	Dashboard summaries (now loadable in parts)
Risk Assessments	/v3/risk_assessments/..., /ext/risk_assessments/	Risk assessment categories, review schedule and meeting hazards
Generic / User	/ext/generic/locks/, /ext/generic/featureusage/, /ext/users/..., /ext/settings/accountpreferences/, /v3/menu-preferences/..., /v3/favourites/...	Edit locks, keep-alive ping, default section, menu preferences, notifications

Contents

File	Description
openapi.yaml	OpenAPI 3.0.3 specification. The source of truth, edited by hand
index.html	Interactive docs UI (Redoc), served over HTTP
llms.txt	Index for AI agents (llmstxt.org). Generated
llms/<category>.md	One Markdown reference per category. Generated
llms-full.txt	The whole reference in one Markdown file. Generated
scripts/build-llms.mjs	Builds the three generated outputs from openapi.yaml
AGENTS.md	How AI agents (and people) should work on this repo

Viewing the docs

Browse them at https://opensource.newcastlescouts.org.uk. Locally, serve the folder over HTTP (for example npx http-server .) rather than opening index.html from disk, because browsers block the spec fetch on file://.

With an AI assistant

Point your coding agent at https://opensource.newcastlescouts.org.uk/llms.txt. It summarises the rules that matter (form-encoded POSTs, rate limits, the action parameter) and links to one Markdown file per category, so the agent only loads what it needs. llms-full.txt has everything in one file if your tool prefers that.

You can also import openapi.yaml into tools like Swagger Editor, Postman, or Insomnia.

Key things to know

• Authentication — OSM uses OAuth 2.0. You'll need a client_id and client_secret from OSM. The bearer token goes in the Authorization header. Tokens expire and must be refreshed via the /oauth/token endpoint.

• Response format quirks — Some endpoints return JavaScript (var data_holder = {...}) rather than clean JSON. You'll need to strip the prefix before parsing. The startup endpoint is the main offender.

• Money units — the accounting API (/v3/finances/accounting/) uses integer pence; event endpoints use pounds. Don't mix them up.

• POST bodies — OSM expects application/x-www-form-urlencoded for all POST requests, not JSON. Sending JSON will get you blocked.

• Rate limits — OSM enforces rate limits. Responses may include X-RateLimit-* or RateLimit-* headers. If you hit a 429, back off immediately. Excessive requests will get your OAuth client banned.

• Privacy and GDPR — These endpoints return personal data about young people and their families. Handle it responsibly. Don't store what you don't need, don't log PII, and follow your organisation's data protection policies.

Contributing

PRs are welcome — especially for endpoints not yet documented. If you've observed a new endpoint or spotted a mistake:

1. Add or update the relevant path in openapi.yaml
2. Include realistic but fictional example data (no real names, IDs, or section data). Never commit HAR files
3. Note any quirks in the description (unusual response formats, required-but-undocumented params, etc.)
4. Run npm install once, then npm run check to lint and regenerate the llms* files, and commit them too

See AGENTS.md for the full conventions, including how to mine HAR captures safely.

Validating the OpenAPI spec

This repo uses Redocly CLI to lint openapi.yaml (config in redocly.yaml):

npm install
npm run check   # lint + regenerate llms.txt, llms-full.txt and llms/

GitHub Actions (.github/workflows/validate-openapi.yml) lints and bundles the spec on every pull request and push to main, and fails if the generated llms* files weren't regenerated after a spec change.

Licence

This documentation is open source. The OSM API itself is owned by Online Scout Manager. This project is not endorsed by or affiliated with OSM.