URL Scheme

Pinswift supports inter-app communication through its URL scheme. Opening any URL in iOS with the pinswift:// prefix will cause Pinswift to launch and potentially perform some action. Other apps (including Safari through the use of bookmarklets) , can use this URL scheme to create new bookmarks or to directly navigate to a particular view with the app. Using x-callback-url support, these actions can be chained together to create workflows involving multiple apps.

For more information on using URL schemes and X-callback-URL see the following:

Creating Bookmarks

To create a new bookmark in Pinswift from an external application, use the following URL:

pinswift:///add?url=<URL>

Pinswift will launch and allow you to create a new bookmark for the given URL. The parameter url must be supplied and property URL encoded. The following parameters may also be supplied

  • title - If empty or omitted, one is automatically chosen for you
  • description
  • tags - space separated
  • toread - “yes” or “no” values indicating bookmark “Read Later” status
  • private - “yes” or “no” indicating privacy of bookmark

You may also use x-callback-url with the add action with the same parameters.

pinswift://x-callback-url/add?url=<URL>&x-success=<URL>

Once a bookmark is saved, the x-success URL is opened. If the users cancels the creation of the bookmark, the x-cancel URL is opened.

The pinswift bookmarklet uses x-callback-url to create bookmarks from the mobile browser.

Browsing

The URL scheme can be used to open Pinswift on a particular bookmark list. Generally, the format of these URLs parallel the URLs used in the Pinboard website.

To view the bookmarks for a particular user, use the following URL

	pinswift:///u:<username>

To view all bookmarks with a particular tag, use the following URL

	pinswift:///t:<tag>

The user and tag URLs may be used in combination for at most three tags. For example, the following are all valid Pinboard URLs

  • pinswift:///u:pinswift
  • pinswift://t:markdown
  • pinswift:///u:pinswift/t:markdown/t:ios
  • pinswift:///t:cat/t:gif/t:funny

You can also view bookmarks for these special lists using the given URLs

  • Recent - /recent
  • Unread - /unread
  • Untagged - /untagged
  • Public - /public
  • Private - /private/
  • Network - /network/
  • Popular - /popular/
  • Wikipedia - /popular/wikipedia
  • Fandom - /popular/fandom

Searching

To search for bookmarks (either personal or public) containing the given text string use on of the following URLs:

pinswift:///search/?query=<text>
pinswift:///search/u:<username>?query=<text>
pinswift:///search/network?query=<text>

These search all public bookmarks, a particular users bookmarks, and network bookmarks respectively.

If you have an archival account, you can append the fulltext=on query for user bokmarks to perform a “full text” search

Opening the Web Browser

You can open the pinswift web browser on a specified URL using:

pinswift:///browse?url=<URL>