Drafts URL Schemes

Greg Pierce
  • Updated
Follow

If you implement, or plan on implementing, Drafts integration in your app, please drop us a line and let us know, we’d be happy to help.

If you develop an app that support URL schemes and works with text and would like to have it considered for a new action in Drafts, please drop us a line and let us know.

Drafts supports for integration with other apps via the x-callback-url protocol. Drafts registers the following URL schema:

  • Drafts: drafts4://, x-drafts4://

 

x-callback-url Actions

All URLs should begin with the base URL "drafts4://x-callback-url/[action]" where action is one of the actions listed below.

/create

  • Action: create
  • Parameters:
    • text [string, required] : URL encoded text to be used for new draft.
    • action [string, optional] : URL encoded name of an action in the Drafts’ action list. If included, the action will be triggered on the new draft after it is created (* see notes below about action security).
    • afterSuccess [string, optional] : Can be a value of “Nothing”, “Archive” or “Delete”. If provided, along with an action parameter, it will override any “after success” settings for the action.
    • allowEmpty [string, optional] : Can by “YES” or “NO”. Default is “YES”. This parameter should only be needed in actions which recursively call Drafts’ own URL schemes. When “NO” and an action parameter is included, Drafts will fail gracefully when trying to perform the action on an empty draft.
  • Description: Calling this action with the required “text” parameter will launch Drafts, create a new draft with the text passed, and present the draft to the user for editing.
  • Examples
    • create a draft with the text “Hello World”:
      • drafts4://x-callback-url/create?text=Hello%20World
    • create a draft with the text “Hello World”, then fire the “Copy to Clipboard” action:
      • drafts4://x-callback-url/create?text=Hello%20World&action=Copy%20to%20Clipboard

 

/open

  • Action: open
  • Parameters:
    • uuid [string, required] : UUID of the draft to open. This can be determined by the "uuid" template tag.
    • action [string, optional] : URL encoded name of an action in the Drafts’ action list. If included, the action will be triggered on the new draft after it is created (* see notes below about action security).
    • afterSuccess [string, optional] : Can be a value of “Nothing”, “Archive” or “Delete”. If provided, along with an action parameter, it will override any “after success” settings for the action.
    • allowEmpty [string, optional] : Can by “YES” or “NO”. Default is “YES”. This parameter should only be needed in actions which recursively call Drafts’ own URL schemes. When “NO” and an action parameter is included, Drafts will fail gracefully when trying to perform the action on an empty draft.
  • Description: This action can be used to create a permalink to a particular draft in the Drafts' database.
  • Examples
    • open a draft:
      • drafts4://x-callback-url/open?uuid=UUID-TO-VALID-DRAFT

 

/get

  • Action: get
  • Parameters:
    • uuid [string, required] : UUID of the draft to open. This can be determined by the "uuid" template tag.
  • Description: This action can be used to fetch the contents of a draft. The current content of the draft will be returned as a "text" parameter on the x-success callback URL.
  • Examples
    • get a draft:
      • drafts4://x-callback-url/get?uuid=UUID-TO-VALID-DRAFT

 

/prepend

  • Action: prepend
  • Parameters:
    • uuid [string, required] : UUID of the draft. This can be determined by the "uuid" template tag.
    • text [string, required] : text to prepend to the beginning of the specified draft.
    • action [string, optional] : URL encoded name of an action in the Drafts’ action list. If included, the action will be triggered on the new draft after it is created (* see notes below about action security).
    • afterSuccess [string, optional] : Can be a value of “Nothing”, “Archive” or “Delete”. If provided, along with an action parameter, it will override any “after success” settings for the action.
    • allowEmpty [string, optional] : Can by “YES” or “NO”. Default is “YES”. This parameter should only be needed in actions which recursively call Drafts’ own URL schemes. When “NO” and an action parameter is included, Drafts will fail gracefully when trying to perform the action on an empty draft.
  • Description: This action will prepend the supplied text to the beginning of an existing draft.
  • Examples
    • prepend to a draft:
      • drafts4://x-callback-url/prepend?uuid=UUID-TO-VALID-DRAFT&text=TEXT-TO-PREPEND

 

/append

  • Action: append
  • Parameters:
    • uuid [string, required] : UUID of the draft. This can be determined by the "uuid" template tag.
    • text [string, required] : text to append to the end of the draft.
    • action [string, optional] : URL encoded name of an action in the Drafts’ action list. If included, the action will be triggered on the new draft after it is created (* see notes below about action security).
    • afterSuccess [string, optional] : Can be a value of “Nothing”, “Archive” or “Delete”. If provided, along with an action parameter, it will override any “after success” settings for the action.
    • allowEmpty [string, optional] : Can by “YES” or “NO”. Default is “YES”. This parameter should only be needed in actions which recursively call Drafts’ own URL schemes. When “NO” and an action parameter is included, Drafts will fail gracefully when trying to perform the action on an empty draft.
  • Description: This action will append the text provided to the end of an existing draft.
  • Examples
    • append to a draft:
      • drafts4://x-callback-url/append?uuid=UUID-TO-VALID-DRAFT&text=TEXT-TO-APPEND

 

/replaceRange

  • Action: replaceRange (requires Drafts 4.6 or greater)
  • Parameters:
    • uuid [string, required] : UUID of the draft. This can be determined by the "uuid" template tag.
    • text [string, required] : Text to insert in the designated range
    • start [integer, required] : The index of the first character to replace.
    • length [integer, required] : The length of the range to replace.
    • retParam [string, optional] : If included, Drafts will look for the text to use to insert in a parameter of this name instead of the default "text" parameter. Useful if an app you are integrating with via x-callback returns it's values using a specific named parameter.
  • Description: This action will append the text provided to the end of an existing draft.
  • Examples
    • append to a draft:
      • drafts4://x-callback-url/replaceRange?uuid=UUID-TO-VALID-DRAFT&text=TEXT-TO-APPEND&start=0&length=10

 

/runAction

  • Action: runAction
  • Parameters:
    • text [string, action] : text to use for the requested action.
    • action [string, required] : URL encoded name of an action in the Drafts’ action list. If included, the action will be triggered on the new draft after it is created (* see notes below about action security).
    • afterSuccess [string, optional] : Can be a value of “Nothing”, “Archive” or “Delete”. If provided, along with an action parameter, it will override any “after success” settings for the action.
    • allowEmpty [string, optional] : Can by “YES” or “NO”. Default is “YES”. This parameter should only be needed in actions which recursively call Drafts’ own URL schemes. When “NO” and an action parameter is included, Drafts will fail gracefully when trying to perform the action on an empty draft.
  • Description: This action can be used run an action in Drafts without creating a draft in the drafts database.  If text is provided, the action will be run with that text as the "draft" for the action, but the text will not be saved after completion.
  • Examples
    • open a draft:
      • drafts4://x-callback-url/runAction?text=TEXT&action=ACTION-NAME

 

/drafts

  • Action: drafts
  • Parameters:
    • filter [string, optional] : The name of the filter tab you wish to present. Typically this would be "Inbox", "Archive" or "Flagged" or the name of any user-defined filter tab in your installation. If not present, the action will open the first filter tab.
    • query [string, optional] : If a query parameter is present, it will be used to run a full text search. This is useful to create saved search bookmarks/actions.
  • Description: Opens drafts to the inbox panel. (Requires Drafts 4.1 or greater)
  • Examples
    • get a draft:
      • drafts4://x-callback-url/drafts?filter=Inbox&query=SEARCH-TERM

 

/markdown

  • Action: markdown
  • Parameters:
    • text [string, required] : The input text to pass through the Markdown processor.
    • processor [string, optional] : Specify which of Drafts' Markdown processors to use. Without this parameter, the default Markdown processor selected in settings will be used. Possible values are:
      • multimarkdown
      • githubflavored
      • discount
    • retParam [string, optional] : the name of the parameter to use to send the output HTML to the x-success URL. Default to "result".
    • x-success [url, required] : URL to send the result back to after processing.
  • Description: Passes the text in the text parameter through the Markdown processor, and calls the URL provided with the x-success parameter with the resulting HTML as a "result" parameter.
  • Examples
    • process markdown:
      • drafts4://x-callback-url/markdown?text=URLENCODED-MARKDOWN-TEXT&processor=multimarkdown&x-success=URL-TO-SEND-RESULT-HTML

 

/dictate

  • Action: dictate
  • Version: Requires Drafts 4.7.0 or better running on iOS 10.
  • Parameters:
    • retParam [string, optional] : the name of the parameter to use to send the output text to the x-success URL. Default to "text".
    • 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. More information on locale identifiers at Apple, or in the reference of supported locales below.
    • x-success [url, required] : URL to send the result back to after processing.
  • Description: Opens Drafts directly to dictation. This can be used to dictate a new draft, or can be used to pass dictated text back to another app using the x-success parameter.
  • Examples
    • process markdown:
      • drafts4://x-callback-url/dicate?x-success=URL-TO-SEND-RESULT-HTML
Supported Locales
ar-SA Arabic (Saudi Arabia) ca-ES Catalan (Spain) cs-CZ Czech (Czech Republic)
da-DK Danish (Denmark) de-AT German (Austria) de-CH German (Switzerland)
de-DE German (Germany) el-GR Greek (Greece) en-AE English (United Arab Emirates)
en-AU English (Australia) en-CA English (Canada) en-GB English (United Kingdom)
en-ID English (Indonesia) en-IE English (Ireland) en-IN English (India)
en-NZ English (New Zealand) en-PH English (Philippines) en-SA English (Saudi Arabia)
en-SG English (Singapore) en-US English (United States) en-ZA English (South Africa)
es-CL Spanish (Chile) es-CO Spanish (Colombia) es-ES Spanish (Spain)
es-MX Spanish (Mexico) es-US Spanish (United States) fi-FI Finnish (Finland)
fr-BE French (Belgium) fr-CA French (Canada) fr-CH French (Switzerland)
fr-FR French (France) he-IL Hebrew (Israel) hr-HR Croatian (Croatia)
hu-HU Hungarian (Hungary) id-ID Indonesian (Indonesia) it-CH Italian (Switzerland)
it-IT Italian (Italy) ja-JP Japanese (Japan) ko-KR Korean (South Korea)
ms-MY Malay (Malaysia) nb-NO Norwegian Bokmål (Norway) nl-BE Dutch (Belgium)
nl-NL Dutch (Netherlands) pl-PL Polish (Poland) pt-BR Portuguese (Brazil)
pt-PT Portuguese (Portugal) ro-RO Romanian (Romania) ru-RU Russian (Russia)
sk-SK Slovak (Slovakia) sv-SE Swedish (Sweden) th-TH Thai (Thailand)
tr-TR Turkish (Turkey) uk-UA Ukrainian (Ukraine) vi-VN Vietnamese (Vietnam)
yue-CN Cantonese (China) zh-CN Chinese (China) zh-HK Chinese (Hong Kong [China])
zh-TW Chinese (Taiwan)        

 

The ||clipboard|| Tag

All actions with "text" parameters support a special clipboard tag.  If the string "||clipboard||" is found in the value of the "text" parameter, it will be replaced with the current contents of the iOS system clipboard.  This allows for incoming URLs to utilize clipboard values without further user interaction.

Callbacks

All Drafts URL actions support x-callback-url formatted callback parameters, as follows:

  • x-success [url, optional] : When used in conjunction with the ‘action’ parameter, this URL will be opened after the action is successfully completed.
  • x-error [url, optional] : When used in conjunction with the ‘action’ parameter, this URL will be opened if the action generates an error and cannot be completed successfully.

URL Security

For URLs with can accept an "action" parameter to fire a Drafts' action, an additional layer of security is provided via the "URL Security" section in Settings. By default, firing actions via URL schemes is disabled, because though it is unlikely, it is possible that a URL could be embedded in a web page or email designed to trick you into tapping it and firing an action which used an action to post to a public space using your account, etc.

If you wish you use actions via URL schemes, you can enabled the "Allow URLs to trigger actions" setting.  If you want an additional layer of security, you can also enable the "Require key" settings and create a key.  If on, incoming URLs which fire actions will be required to have the "key=XXXXX" parameter.  Think of it as a password for allowing URLs to fire actions.

 

Related articles

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk