OnStage API
The OnStage API lets your own scripts and tools read and change your team's events, setlists, people and songs. Every endpoint is listed below with what it does. Open one for its parameters, request body, responses and code samples.
Before you start
- Base URL:
https://api.on-stage.app/integrations/v1(the token endpoint ishttps://api.on-stage.app/oauth/token). - Credentials: an Owner or Admin creates a client ID and secret in Settings › Connections › API. Get your OnStage API credentials
- Signing in: exchange them for an access token that lasts one hour, and send it as
Authorization: Bearer <token>. Use the OnStage API - Writes preview first: bulk writes and event changes answer a preview. Send
"dryRun": falseto apply them. - OpenAPI file: download it to generate a client in your language.
Endpoints
Authentication
Exchange your client ID and secret for an access token.
| Endpoint | Method and path | What it does |
|---|---|---|
| Get an access token | POST /oauth/token | Exchanges your client ID and secret (grant_type=client_credentials, with HTTP Basic or in the form body) for an access token that lasts one hour. |
Team
Your token and the team's daily limit, the team's people, and their availability.
| Endpoint | Method and path | What it does |
|---|---|---|
| Get the team context | GET /team/context | Gets the team at a glance: its members, groups and positions, event templates, your time zone and your own member record. Read it before planning events. |
| Get team availability | GET /team/availability | Lists the team's blockouts between two dates: who is unavailable, when and why. |
| Get your token details and daily limit | GET /me | Who the token acts for, its team, role and scopes, and the team's daily request limit: how many requests it allows, how many are used today and when the count resets. |
Events
Read, duplicate, change, publish and delete events, set their reminders, and answer invitations.
| Endpoint | Method and path | What it does |
|---|---|---|
| Set an event's reminders | PUT /events/{eventId}/reminders | Replaces an event's reminders: how many days before and at what time the people serving are reminded. Previews by default; send dryRun false to apply. |
| Answer an event invitation | POST /events/{eventId}/response | Accepts or declines the token owner's own invitation to an event. |
| Duplicate an event | POST /events/{eventId}/duplicate | Copies an event, with its setlist, positions and reminders, into a new draft. Optionally give the copy a new name and date. Applies at once. |
| Publish events | POST /events/publish | Publishes draft events so the people serving are invited. Previews by default; send dryRun false to apply. |
| Get an event | GET /events/{eventId} | Gets one event: its details, setlist, reminders and, unless includeParticipants is false, who is serving. |
| Delete an event | DELETE /events/{eventId} | Deletes an event. Previews by default; add ?dryRun=false to delete it. |
| Change an event | PATCH /events/{eventId} | Changes an event's name, date, time or location. Previews by default; send dryRun false to apply. |
| List events | GET /events | Lists the team's events between two dates, with their setlists and, unless includeParticipants is false, who is serving. |
Setlist
Build and change an event's setlist.
| Endpoint | Method and path | What it does |
|---|---|---|
| Replace a setlist | PUT /events/{eventId}/setlist | Replaces an event's whole setlist with the items given. Previews by default; send dryRun false to apply. |
| Reorder the setlist | POST /events/{eventId}/setlist/reorder | Puts an event's setlist items in the order given by their ids. Applies at once and returns the event. |
| Add a setlist item | POST /events/{eventId}/setlist/items | Adds a song or a moment to an event's setlist, at a position or at the end. Applies at once and returns the event. |
| Remove a setlist item | DELETE /events/{eventId}/setlist/items/{itemId} | Removes one item from an event's setlist. Applies at once and returns the event. |
| Change a setlist item | PATCH /events/{eventId}/setlist/items/{itemId} | Changes one setlist item: its key, duration, name, description or position. Applies at once and returns the event. |
People
Who serves in an event, and creating many events with their people at once.
| Endpoint | Method and path | What it does |
|---|---|---|
| Create events in bulk | POST /schedule/batches | Creates many events at once, with their setlists and the people serving, optionally publishing them. Previews by default; send dryRun false to apply. |
| Change who is serving | PATCH /events/{eventId}/participants | Adds, removes or replaces the people serving in an event's positions, and decides what happens when someone has a blockout. Previews by default; send dryRun false to apply. |
Rehearsals
An event's rehearsals.
| Endpoint | Method and path | What it does |
|---|---|---|
| List an event's rehearsals | GET /events/{eventId}/rehearsals | Lists the rehearsals of an event, with their dates and locations. |
| Add a rehearsal | POST /events/{eventId}/rehearsals | Adds a rehearsal to an event. Applies at once. |
| Remove a rehearsal | DELETE /events/{eventId}/rehearsals/{rehearsalId} | Removes a rehearsal from an event. Applies at once. |
| Change a rehearsal | PATCH /events/{eventId}/rehearsals/{rehearsalId} | Changes a rehearsal's name, date or location. Applies at once. |
Blockouts
The token owner's own blockouts.
| Endpoint | Method and path | What it does |
|---|---|---|
| Add a blockout | POST /blockouts | Adds a blockout for the token owner: dates they are not available, with an optional reason. |
| Remove a blockout | DELETE /blockouts/{blockoutId} | Removes one of the token owner's blockouts. |
Songs
The team's song library and its artists.
| Endpoint | Method and path | What it does |
|---|---|---|
| Add songs in bulk | POST /songs/batches | Adds many songs to the team's library at once, with their sections or ChordPro, and decides what happens to duplicates. Previews by default; send dryRun false to apply. |
| Get a song | GET /songs/{songId} | Gets one song: its key, tempo, time signature, themes, CCLI number, sections and files. |
| Change a song | PATCH /songs/{songId} | Changes a song's details or content: title, artist, key, tempo, themes, CCLI, copyright, sections or ChordPro. Previews by default; send dryRun false to apply. |
| Search songs | GET /songs | Searches the team's song library by title or artist, a page at a time. |
| List artists | GET /artists | Lists the artists in the team's song library, optionally filtered by a search text. |
Song files
Attach PDF and audio files to songs.
| Endpoint | Method and path | What it does |
|---|---|---|
| Start a song file upload | POST /songs/{songId}/files | Starts attaching a PDF or audio file to a song: answers a URL to upload the file to. Finish it with Finish a song file upload. |
| Finish a song file upload | POST /songs/{songId}/files/{fileId}/complete | Finishes a file upload started with Start a song file upload, so the file shows on the song. |
Batches
Follow and undo bulk writes.
| Endpoint | Method and path | What it does |
|---|---|---|
| List recent batches | GET /batches | Lists the team's most recent batches (previews and applied writes), newest first. |
| Get a batch | GET /batches/{id} | Gets one batch: its status, what it changed or would change, and any items that failed. Poll it after a write that answered 202. |
| Undo a batch | DELETE /batches/{id} | Undoes an applied batch, within 7 days. Answers 202 and undoes it in the background. |
Reports
Serving, song usage and insights reports.
| Endpoint | Method and path | What it does |
|---|---|---|
| Get a report | GET /reports/{report} | Gets one report for a date range: serving_summary, song_usage, upcoming_events, availability, or one of the insights reports (insights_overview, insights_members, insights_member, insights_events, insights_songs, insights_adoption). Some reports need a role that sees all events. |
Presentation software
Events shaped as services, for presentation software such as Holyrics and FreeShow.
| Endpoint | Method and path | What it does |
|---|---|---|
| List services for presentation software | GET /services | Lists upcoming events shaped as services, the way presentation software such as Holyrics and FreeShow reads them. |
| Get a service for presentation software | GET /services/{eventId} | Gets one event as a service, with each song's lyrics in slide-sized sections. |