URL Schemes

Drafts implements URL actions based on the x-callback-url specification, and registers the drafts: URL scheme. All actions below should be formatted as follows:

drafts://x-callback-url/[actionName]?[queryParameters]

Note that the x-callback-url host is optional in all drafts URLs. It is supported for consistency with the specification, but functionally it is not required and drafts://[actionName]... will have the same result as drafts://x-callback-url/[actionName]...

All URLs should be proper valid URLs with URL encoded values in query arguments. With a few exceptions, all actions support x-callback-url x-success, x-error and x-cancel arguments where appropriate.

Clipboard Parameter

URLs which accept an incoming text parameter, can use the special markup ||clipboard|| in the parameter and Drafts will insert the current text from the clipboard.

NOTE: Some URL scheme parameters and actions require a Pro subscription. PRO

Table of Contents

/create
/open
/get
/getCurrentDraft
/prepend
/append
/replaceRange
/search
/quickSearch
/commandPalette
/actionSearch
/workspace
/loadActionGroup
/loadActionBarGroup
/runAction
/capture
/dictate
/scanDocument
/arrange
/refresh_text_expander

Supported Actions

/create

Create a new draft with the content passed in the “text” argument. If an x-success url is provided, it will be called the uuid parameter indicating the UUID of the draft which was created.

Arguments
- text [string, required] : Text to be used at the content of the new draft.
- tag [string] : Name of a tag to attach to the draft. Parameter can appear multiple times to add more than one tag.
- folder [inbox|archive, optional] : Location for the new draft. Default: inbox
- flagged [boolean, optional] : Should the newly created draft by flagged. Default: false
- action [string, optional] : Name of an action in the action list. If provided, this action will be run on the specified draft.
- allowEmpty [boolean, optional] : If an action parameter is provided, adding allowEmpty=false to the URL will prevent that action from running if the text is empty. This can be used to terminate a loop of x-callback-urls running on lines of a draft.
- retParam [string, optional] : The name of the argument to use to pass the draft UUID back to the x-success URL. Defaults to “uuid”, but if the requesting app expects another value (like Workflow’s “input”) use this argument to override.
Examples
- drafts://x-callback-url/create?text=Hello%20World
  - Create new draft with the content “Hello World”

/open

Open an existing draft based on the UUID argument.

Arguments
- uuid [string, optional] : The UUID identifier for a draft.
- title [string, optional] : The title of the draft to open. Drafts will search for drafts matching the title provided. If more than one draft matching the title is found, a warning will be issued, and a search opened to help identify the correct draft. Title parameters can also support navigation to specific markers with the target draft, using the format Title/Marker-Label. Typical use case would be for navigation within Markdown drafts, where passing a title parameter of MyDraft/Header Name would open the “MyDraft” draft, and scroll to a “# Header Name” header.
- marker [string, optional] : The name of a navigation marker in the draft to navigate to after opening. Works like including the marker in the title parameter above, but can be combined with uuid to specify a particular draft more accurately.
- action [string, optional] : Name of an action in the action list. If provided, this action will be run on the specified draft.
- allowEmpty [boolean, optional] : If an action parameter is provided, adding allowEmpty=false to the URL will prevent that action from running if the text is empty. This can be used to terminate a loop of x-callback-urls running on lines of a draft.
- allowCreate [boolean, optional] : Using in conjunction with the title parameter, if allowCreate is passed and is “true”, and no draft matching the title value is found, the user will be prompted asking if they wish to create the draft with that title.
- showDraftList [boolean, optional] : Set visibility of draft list.
- showActionList [boolean, optional] : Set visibility of action list.
- loadWorkspace [string, optional] : Name of workspace to apply.
- loadActionGroup [string, optional] : Name of action group to load in action list.
- loadActionBarGroup [string, optional] : Name of action group to load in action bar.
Examples
- drafts://x-callback-url/open?uuid=UUID-TO-VALID-DRAFT
  - Open the draft in the editor with the UUID provided.

/get

Return the current content of the draft specified by the UUID argument as an argument to the x-success URL provided.

Arguments
- uuid [string, required] : The UUID identifier for a draft.
- retParam [string, optional] : The name of the argument to use to pass the draft content back to the x-success URL. Defaults to “text”, but if the requesting app expects another value (like Workflow’s “input”) use this argument to override.
Examples
- drafts://x-callback-url/get?uuid=UUID-TO-VALID-DRAFT&x-success=APP-URL
  - Retrieves the content of the identified draft, and calls the x-success URL with the argument text=DRAFT-CONTENT added.

/getCurrentDraft

Return the information about the current draft loaded in the editor. To use, you must include an x-success callback URL. Drafts will call the x-success URL with uuid, url, title, content parameters with values related to the current draft. Mostly useful to access a link to the current draft from outside the app.

Arguments
- none
Examples
- drafts://x-callback-url/getCurrentDraft?x-success=[callbackurl]

/prepend

Prepend the passed text to the beginning of a draft identified by the UUID argument.

Arguments
- uuid [string, required] : The UUID identifier for a draft.
- text [string, required] : Text to add.
- action [string, optional] : Name of an action in the action list. If provided, this action will be run on the specified draft.
- allowEmpty [boolean, optional] : If an action parameter is provided, adding allowEmpty=false to the URL will prevent that action from running if the text is empty. This can be used to terminate a loop of x-callback-urls running on lines of a draft.
- tag [string] : Name of a tag to attach to the draft. Parameter can appear multiple times to add more than one tag.
Examples
- drafts://x-callback-url/prepend?uuid=UUID-TO-VALID-DRAFT&text=TEXT-TO-ADD
  - Adds “TEXT-TO-ADD” to the beginning of the draft.

/append

Append the passed text to the end of a draft identified by the UUID argument.

Arguments
- uuid [string, required] : The UUID identifier for a draft.
- text [string, required] : Text to add.
- action [string, optional] : Name of an action in the action list. If provided, this action will be run on the specified draft.
- allowEmpty [boolean, optional] : If an action parameter is provided, adding allowEmpty=false to the URL will prevent that action from running if the text is empty. This can be used to terminate a loop of x-callback-urls running on lines of a draft.
- tag [string] : Name of a tag to attach to the draft. Parameter can appear multiple times to add more than one tag.
Examples
- drafts://x-callback-url/append?uuid=UUID-TO-VALID-DRAFT&text=TEXT-TO-ADD
  - Adds “TEXT-TO-ADD” to the end of the draft.

/replaceRange

Replace content in an existing draft, based on a range.

Arguments
- uuid [string, required] : The UUID identifier for a draft.
- text [string, required] : Text to insert in the specified range
- start [integer, required] : Start position of the range to replace.
- length [integer, required] : Number of characters in the range to replace.
Examples
- drafts://x-callback-url/replaceRange?uuid=UUID-TO-VALID-DRAFT&text=TEXT-TO-INSERT&start=0&length=10
  - Open the draft and replace characters 0 through 10 with TEXT-TO-INSERT.

/search

Open drafts directly to the draft search field.

Arguments
- query [string, optional] : Initial text to use in the search.
- tag [string, optional] : Tag to use to filter the query.
Examples
- drafts://x-callback-url/search?query=QUERY-TEXT

/quickSearch

Open drafts directly to quick search, if available.

Arguments
- query [string, optional] : Initial text to use in the search.
Examples
- drafts://x-callback-url/quickSearch?query=QUERY-TEXT

/commandPalette

Open drafts directly to command palette, if available.

Arguments
- query [string, optional] : Initial text to use in the search.
Examples
- drafts://x-callback-url/commandPalette?query=QUERY-TEXT

/actionSearch

Open drafts directly to search of the action list.

Arguments
- query [string, optional] : Initial text to use in the search.
Examples
- drafts://x-callback-url/actionSearch?query=QUERY-TEXT

/workspace

Open drafts directly the draft list with a named workspace selected.

Arguments
- name [string, required] : Name of a saved workspace to load. Use “Default” as name to clear filters and load the default workspace.
Examples
- drafts://x-callback-url/workspace?name=WORKSPACE-NAME

/loadActionGroup

Load an action group in the action list side panel.

Arguments
- name [string, required] : Name of a valid action group to load.
Examples
- drafts://x-callback-url/loadActionGroup?name=GROUP-NAME

/loadActionBarGroup

Load an action group in the action bar row.

Arguments
- name [string, required] : Name of a valid action group to load.
Examples
- drafts://x-callback-url/loadKeyboardActionGroup?name=GROUP-NAME

/runAction

Run a drafts action on the passed text without saving that text to a draft.

Arguments
- text [string, required] : Text to add.
- action [string, optional] : Name of an action in the action list. If provided, this action will be run on the specified draft.
- allowEmpty [boolean, optional] : If an action parameter is provided, adding allowEmpty=false to the URL will prevent that action from running if the text is empty. This can be used to terminate a loop of x-callback-urls running on lines of a draft.
Examples
- drafts://x-callback-url/runAction?text=TEXT&action=VALID-ACTION-NAME
  - If found, runs the VALID-ACTION-NAME action on an unsaved draft containing “TEXT”.

/capture

Open Drafts to a new capture window, like used in the Share extension, which can be used to create a new draft, or append-prepend to existing drafts.

Arguments
- text [string, optional] : Initial text for the capture window.
- tag [string] : Comma-separated list of tags to set as the initial tags assignments.
Examples
- drafts://x-callback-url/capture?text=INITIAL-TEXT

/dictate

Open Drafts dictation interface. The resulting text is passed to the x-success callback, and saved as a draft unless the save parameter is used to disable saving.

Arguments
- locale [string, optional] : Locale identifier to use for dictation, in the standard language-country abbreviated format. Examples: en-US (English-United States), it-IT (Italian-Italy), es-MX (Spanish-Mexico), etc. Any locale supported by Siri dictation can be used.
- save [boolean] : Default to “true”. If “false”, the results of the dictation will be returned to the callback, but not saved as a draft in Drafts.
- retParam [string, optional] : The name of the argument to use to pass the draft content back to the x-success URL. Defaults to “text”, but if the requesting app expects another value (like Workflow’s “input”) use this argument to override.
Examples
- drafts://x-callback-url/dictate?x-success=APP-URL
  - Retrieves the content of the identified draft, and calls the x-success URL with the argument text=DICTATED-TEXT added.

/scanDocument

Open Drafts document scanning interface. The resulting text is passed to the x-success callback, and saved as a draft unless the save parameter is used to disable saving.

Arguments
- save [boolean] : Default to “true”. If “false”, the results of the scan will be returned to the callback, but not saved as a draft in Drafts.
- retParam [string, optional] : The name of the argument to use to pass the draft content back to the x-success URL. Defaults to “text”, but if the requesting app expects another value (like Workflow’s “input”) use this argument to override.
Examples
- drafts://x-callback-url/scandocument?x-success=APP-URL
  - Retrieves the content of the identified draft, and calls the x-success URL with the argument text=DICTATED-TEXT added.

/arrange

Open Drafts arrange interface. Pass the resulting arranged text to the x-success URL instead of saving it in Drafts.

Arguments
- text [string, required] : Text to arrange.
- retParam [string, optional] : The name of the argument to use to pass the draft content back to the x-success URL. Defaults to “text”, but if the requesting app expects another value (like Workflow’s “input”) use this argument to override.
Examples
- drafts://x-callback-url/arrange?x-success=APP-URL
  - Retrieves the content of the identified draft, and calls the x-success URL with the argument text=ARRANGED-TEXT added.

/refresh_text_expander

Convenience command which immediately launches TextExpander to trigger a refresh of the TextExpander snippet library. Note that this URL does not support callbacks.