Pular para o conteúdo principal

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 is https://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": false to 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.

EndpointMethod and pathWhat it does
Get an access tokenPOST /oauth/tokenExchanges 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.

EndpointMethod and pathWhat it does
Get the team contextGET /team/contextGets 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 availabilityGET /team/availabilityLists the team's blockouts between two dates: who is unavailable, when and why.
Get your token details and daily limitGET /meWho 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.

EndpointMethod and pathWhat it does
Set an event's remindersPUT /events/{eventId}/remindersReplaces 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 invitationPOST /events/{eventId}/responseAccepts or declines the token owner's own invitation to an event.
Duplicate an eventPOST /events/{eventId}/duplicateCopies 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 eventsPOST /events/publishPublishes draft events so the people serving are invited. Previews by default; send dryRun false to apply.
Get an eventGET /events/{eventId}Gets one event: its details, setlist, reminders and, unless includeParticipants is false, who is serving.
Delete an eventDELETE /events/{eventId}Deletes an event. Previews by default; add ?dryRun=false to delete it.
Change an eventPATCH /events/{eventId}Changes an event's name, date, time or location. Previews by default; send dryRun false to apply.
List eventsGET /eventsLists 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.

EndpointMethod and pathWhat it does
Replace a setlistPUT /events/{eventId}/setlistReplaces an event's whole setlist with the items given. Previews by default; send dryRun false to apply.
Reorder the setlistPOST /events/{eventId}/setlist/reorderPuts an event's setlist items in the order given by their ids. Applies at once and returns the event.
Add a setlist itemPOST /events/{eventId}/setlist/itemsAdds 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 itemDELETE /events/{eventId}/setlist/items/{itemId}Removes one item from an event's setlist. Applies at once and returns the event.
Change a setlist itemPATCH /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.

EndpointMethod and pathWhat it does
Create events in bulkPOST /schedule/batchesCreates 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 servingPATCH /events/{eventId}/participantsAdds, 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.

EndpointMethod and pathWhat it does
List an event's rehearsalsGET /events/{eventId}/rehearsalsLists the rehearsals of an event, with their dates and locations.
Add a rehearsalPOST /events/{eventId}/rehearsalsAdds a rehearsal to an event. Applies at once.
Remove a rehearsalDELETE /events/{eventId}/rehearsals/{rehearsalId}Removes a rehearsal from an event. Applies at once.
Change a rehearsalPATCH /events/{eventId}/rehearsals/{rehearsalId}Changes a rehearsal's name, date or location. Applies at once.

Blockouts​

The token owner's own blockouts.

EndpointMethod and pathWhat it does
Add a blockoutPOST /blockoutsAdds a blockout for the token owner: dates they are not available, with an optional reason.
Remove a blockoutDELETE /blockouts/{blockoutId}Removes one of the token owner's blockouts.

Songs​

The team's song library and its artists.

EndpointMethod and pathWhat it does
Add songs in bulkPOST /songs/batchesAdds 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 songGET /songs/{songId}Gets one song: its key, tempo, time signature, themes, CCLI number, sections and files.
Change a songPATCH /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 songsGET /songsSearches the team's song library by title or artist, a page at a time.
List artistsGET /artistsLists the artists in the team's song library, optionally filtered by a search text.

Song files​

Attach PDF and audio files to songs.

EndpointMethod and pathWhat it does
Start a song file uploadPOST /songs/{songId}/filesStarts 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 uploadPOST /songs/{songId}/files/{fileId}/completeFinishes a file upload started with Start a song file upload, so the file shows on the song.

Batches​

Follow and undo bulk writes.

EndpointMethod and pathWhat it does
List recent batchesGET /batchesLists the team's most recent batches (previews and applied writes), newest first.
Get a batchGET /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 batchDELETE /batches/{id}Undoes an applied batch, within 7 days. Answers 202 and undoes it in the background.

Reports​

Serving, song usage and insights reports.

EndpointMethod and pathWhat it does
Get a reportGET /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.

EndpointMethod and pathWhat it does
List services for presentation softwareGET /servicesLists upcoming events shaped as services, the way presentation software such as Holyrics and FreeShow reads them.
Get a service for presentation softwareGET /services/{eventId}Gets one event as a service, with each song's lyrics in slide-sized sections.