Sway URI scheme
This document defines the format of Uniform Resource Identifiers (URIs) for the Sway application for Windows. You can use this URI scheme to invoke the Sway application with various commands.
Sway URI scheme syntax
The following is the URI scheme syntax:
<ms-sway>:<command-argument>
<ms-sway>
– Indicates that Sway is the application to invoke. When Sway for Windows is installed,ms-sway
is registered with Windows to be the Sway handler.<command-argument>
– A URI might have one or more command arguments, delimited by the ampersand (&
) character. When more than one command argument is included in a URI, an ampersand (&
) character must separate each command argument from the following command argument. Command arguments vary according to the scenario.
Command arguments
Several command arguments can be included as part of the Sway URL scheme. These command arguments are not required. If you do not include the command arguments, the Sway application is invoked.
Command argument name | Description | Type | Possible values | Required? |
---|---|---|---|---|
id | The unique identifier of a Sway. Used to indicate the Sway to be opened. | String | A valid unique identifier for a Sway. The id is always part of the URL to a Sway. For example, for the following Sway https://sway.com/dBheQgVZ1RQBfiQU , the id is dBheQgVZ1RQBfiQU .If the user account associated with the Sway application has edit permissions, the application opens the Sway in edit mode. Otherwise, the application opens the Sway in view mode. |
No |
mode | The mode in which a specific Sway should be opened, whether for editing or for viewing. | String | edit view NOTE: If no id is specified, this command argument is ignored. |
No |
auth_upn | The account to use when opening Sway. | String | A valid email address. If the specified email address is not associated with a Sway account, Sway asks the user to sign in as the specified user. If more than one account is associated with the Sway application and the specified email address exists, the Sway application switches to using that account when invoked. |
No |
auth_pvr | The type of account to use to open the Sway—either a Microsoft account or an Microsoft Entra ID account. | String | WindowsLiveId – Specifies that the auth_upn account is a Microsoft account. OrgId – Specifies that the auth_upn account is an Microsoft Entra account. If no auth_upn is specified, this command argument is ignored. |
No |
invoking_app | The name of the Windows application used to invoke Sway. | String | The friendly name of the Windows application used to invoke Sway via the Sway URL scheme. The purpose of this command argument is for telemetry and tracking. |
No |
URI scheme semantics
The <ms-sway>
scheme defines a URI syntax for opening a Sway or for invoking the Sway application. The scheme defines several command arguments, which can be used to do the following:
Open the Sway application – No command arguments need to be specified.
Open a Sway for viewing in the Sway application – The id and mode set to view need to be specified.
Open a Sway for editing in the Sway application – The id and mode set to edit needs to be specified. We recommend that you also include auth_upn and auth_pvr to help ensure that the right account with editing permissions is used when Sway is opened.
Example
ms-sway:id=CyrvEYLmFKi1B2_I&auth_upn=account@email.com&auth_pvr=WindowsLiveId&invoking_app=MyApp
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for