Your notes. Your Dropbox. You're welcome.™

Introducing… A URL Scheme for Notesy

We've implemented a few URL schemes for Notesy in the past six months. It wasn't until we settled on the x-callback-url protocol that we were comfortable releasing it into the wild. Our earlier versions did not give us the flexibility to enhance Notesy's URL support in future releases. We think you will find this URL scheme for Notesy to be very useful.

Most of the actions involve opening a note, or adding text to a new or previously existing note. But we also have an action which allows you to use Notesy as a service for other apps. And we have ideas for other actions which we may provide in future releases too. If you have ideas for actions which will benefit you, please let us know and we'll consider it as well. We believe that the protocol we settled on will allow us to add more features to the URL scheme for Notesy in the future.

The protocol for Notesy's URL scheme can be found below. The next release of Notesy will include this URL scheme, which we expect to be available within two weeks. We'll be happy to answer any questions you may have and we're always open for comments and suggestions.

Notesy x-callback-url API


Notesy supports a URL scheme based on the x-callback-url 1.0 (http://x-callback-url.com/) protocol. The format for Notesy's URL scheme looks like this:

  • notesy://x-callback-url/[action]?[x-callback parameters]&[action parameters]

The x-callback parameters are defined by the x-callback-url protocol, and are optional for all actions.

The action parameters are defined in the API below, and are unique to each action.

Some actions will return information to the calling app. When an action returns information, the parameters passed back to the calling app are documented with the API below.

Supported x-callback-url Parameters
All of Notesy's actions will accept all of the x-callback parameters: x-source, x-success, x-error, and x-cancel. There are some cases where the action and callback do not make sense. For example, when the open action successfully opens a Note, there is no reason to callback the x-success URL. In these cases, the x-callback parameter is ignored.

  • x-source - The name of the calling app.
  • x-success - A complete URL to call when the action completed successfully.
  • x-error - A complete URL to call when the action failed.
  • x-cancel - A complete URL to call when the action was canceled by the user.

Actions
Note: The following examples assume that Notesy uses .txt file extensions by default. Also, to simplify the documentation, URLs below are not URL-encoded. Parameters passed to Notesy from an app must be URL-encoded.

open
Open Notesy to a specific note or folder.

Params
  • path - The directory path. If not specified, defaults to the root folder.
  • name - The name of the file to open. If not specified, the folder specified by the path param will be opened. If the file extension is missing, Notesy's configured default file extension will be used.

Examples
Open Notesy to /:

  • notesy://x-callback-url/open

Open Notesy to /foo.txt:

  • notesy://x-callback-url/open?name=foo
  • notesy://x-callback-url/open?name=foo.txt

Open Notesy to /dir1/dir2:

  • notesy://x-callback-url/open?path=dir1/dir2

Open Notesy to /dir1/dir2/foo.txt:

  • notesy://x-callback-url/open?path=dir1/dir2&name=foo
  • notesy://x-callback-url/open?path=dir1/dir2&name=foo.txt

append
Append text to an existing note, or create a new note if the requested note does not exist. The text to append can come from the clipboard or from a parameter passed to the action.

Params
  • path - The dir path, creating all directories if needed. If not specified, assumes root folder.
  • name - The name of the file to append. If not specified, the note name will come from the first line of text. If the file extension is missing, Notesy's configured default file extension will be used.
  • text - The text to append. If not specified, the text to append will come from the clipboard.

Examples
Append contents of clipboard to /foo.txt:

  • notesy://x-callback-url/append?name=foo
  • notesy://x-callback-url/append?name=foo.txt

Append hello world to /dir1/dir2/foo.txt:

  • notesy://x-callback-url/append?path=dir1/dir2&name=foo&text=hello+world
  • notesy://x-callback-url/append?path=dir1/dir2&name=foo.txt&text=hello+world

Append "hello world" to an unspecified note in the `/dir1/dir2` directory:

notesy://x-callback-url/append?path=dir1/dir2&text=hello+world

Append contents of clipboard to an unspecified note in the root directory:

notesy://x-callback-url/append

restore
Open Notesy to the note or folder displayed when Notesy was last closed. This action has the same behavior as the basic URL (notesy://), except for the potential to return an error back to the calling application.

Examples
Open Notesy to the note or folder displayed when Notesy was last closed:

notesy://x-callback-url/restore
notesy://

render-markdown
Use Notesy to render Markdown-formatted text. The text to render can come from the clipboard or from a parameter passed to the action. The resulting HTML will also contain the inline Markdown Header defined in Notesy's settings. The output can be copied to the clipboard or returned to the calling application.

Params
  • text - The text to render. If not specified, the contents of the clipboard will be rendered.
  • output-param - The resulting HTML will be passed to the x-success URL using this parameter name. If not set, the resulting HTML will be copied to the clipboard.

Examples
Render contents of clipboard and copy resulting HTML to clipboard:

notesy://x-callback-url/render-markdown

Render specific text and set a return parameter:

notesy://x-callback-url/render-markdown?text=hello+world&output-param=result