URL Schemes

URL schemes allow you to open iA Writer from other applications on both macOS and iOS, and perform specific actions on opening. For example, you can turn a text snippet into a new iA Writer document. URL schemes can also be used to change some of iA Writer’s defaults.

On iOS, these URL schemes can be leveraged with the iOS Shortcuts app. (iOS 12+).

Requirements

iA Writer for Mac: version 5.1+
iA Writer for iOS: version 5.1+ *iOS 12+ for iOS Shortcuts
Registered URL scheme: iawriter://

Overview

Starting from scratch you can put together a URL-scheme with 3 key building blocks. The following workflow should work for novice and seasoned users alike:

Choose CommandAdd ParametersAdd Values

By selecting the appropriate command from the list below, you can quickly get a feel for what parameters and values will be necessary for your own URL.

The general structure of a special URL will resemble:

ia-writer://command?parameter1=value1&parameter2=value2

x-callback-url

All commands can support x-callback-url. This comes in handy when you want to send or receive information to/from another app.

The structure for a url including x-callback:

ia-writer://x-callback-url/command?x-parameter1=x-value1&parameter1=value1&parameter2=value2

Some commands will return parameters on x-success.


Interface Commands

Commands that allow you to interact with iA Writer.

Select Details tab to see more details and an example of each command.

open command

Opens Editor with an existing document.

Details
Parameters
path
Path. Required. Path to file. Must point to a file and not a folder
edit
Boolean. Optional. If true, keyboard will be shown on compatible iOS devices.
Return parameters on x-success

None.

EXAMPLE:

ia-writer://open?path=/Locations/iCloud/Website/URL-Schemes/EXAMPLES.txt

Opens EXAMPLES.txt (file) which is saved in iCloud → Website → URL-Schemes (folder)

new command

Opens Editor with a new document.

Details
Parameters
path
Path. Optional. Path for the file to be created. If omitted the file will be created at the root of the default location. If the path points to a directory, the file will be automatically named. If the path points to a file, it must have a plain text file extension, or the path will be ignored. The proposed filename will be used, but adjusted to avoid overwriting an existing file.
text
String. Optional. File contents.
edit
Boolean. Optional. If true, keyboard will be shown on compatible iOS devices.
Return parameters on x-success

None.

EXAMPLE:

ia-writer://new?path=/Locations/iCloud/Journal/entry123.txt

Creates a new file titled entry123.txt in iCloud → Journal (folder)

Opens Quick Search with a given query.

Details
Parameters
query
String. Optional.
Return parameters on x-success

None.

EXAMPLE:

ia-writer://quick-search?query=%23unfinishedtask

Opens a Quick Search window for terms "#unfinishedtask"
Note: # symbol needs to be percent encoded → %23


Data Commands

Silently read and write data to/from iA Writer. Handy for: external apps interacting with iA Writer.

read command

Reads and returns files contents.

Details
Parameters
auth-token
String. Required.
path
Path. Required. Path to the file to read.
Return parameters on x-success
path
Path. Path to the file.
text
String. File text.

EXAMPLE:

ia-writer://read?auth-token=y0uRt0K3Nh3r3&path=/Locations/iCloud/Journal/entryXYZ.md

On x-success returns:

  • Path to (file) entryXYZ.md found in iCloud → Journal (folder)
  • Text contained in entryXYZ.md

write command

Creates or modifies an existing file and returns file contents.

Details
Parameters
auth-token
String. Required.
path
Path. Required.
text
String. Optional.
mode
String. Optional.
create Default. Adjusts last path component to avoid replacing an existing file.
replace Replaces an existing file.
append Appends the given text to an existing file.
append-location
String. Optional. Used only when mode is append.
beginning Append text at the beginning of a file.
end Default. Append text at the end of a file.
append-padding
Boolean. Optional. Default: true. Make a paragraph out of appended text. Used only when mode is append.
Return parameters on x-success
path
Path. Path to the file that was created or modified.
text
String. File contents after writing.

EXAMPLE:

ia-writer://write?auth-token=r4nd0m5tr1n9&path=/Locations/iCloud/Journal/entry123.txt&text=%2A%2ALOG+COMPLETE%2A%2A&mode=append&append-location=end&append-padding=true

Appends the term "LOG COMPLETE" in a new paragraph at the end of document entry123.txt found in iCloud → Journal

version command

Returns iA Writer app version and URL scheme version.

Details
Parameters

None.

Return parameters on x-success
scheme-version
String. URL scheme version.
app-version
String. App version.


EXAMPLE:

ia-writer://x-callback-url/version?

On x-success returns:

  • current URL-scheme version
  • current version of iA Writer

Data Types

Learn more and see examples of the various data types your URL-scheme may call for.
String
A string is any series of letters, numbers or symbols. To work within a URL, these must be “URL or percent encoded”.
Example: Alice's Diary becomes `Alice%27s%20Diary` where the invalid characters (apostrophe and space) are replaced with `%27` and `%20`.
Limits: 4,000 characters max before encoding
Path
Points to the location of the file to be created, opened or edited. This must be percent encoded to work in your URL.
/ this leading slash refers to the default location (iCloud or local).
/Locations/From Other Apps/ is available on iOS.
/Locations/Name/ can be used to filter files from custom locations on macOS.
Example: Path to Tester's Folder, found within the default iCloud folder. → /Tester%27s%20Folder
? You can use the right-click menu in Library and Organizer to copy paths on macOS.
? You can tap and hold items in Library to copy paths on iOS.
Boolean
Either true or false.

Auth

Learn more about why some commands require an Auth-token.

For privacy and security, commands that modify or return data using x-callback-url require the auth-token parameter. This Auth token is synced across all your devices using iCloud. This can be found in:

  • On Mac: iA Writer → Preferences → General → URL Commands → Manage.
  • On iOS: Library → Settings → URL Commands.

? If you reset your auth-token you will need to replace this parameter in any x-callback-urls you’ve previously created.


Sample iOS Shortcuts – FREE

Get Started

We wanted to share these in-house Shortcuts created for iOS(12+) users!

In adding these to your Shortcut library you will have not only handy Shortcuts but also something you can refer to or modify to your own liking.

Note: If you have not enabled Allow Untrusted Shortcuts in iOS settings → Shortcuts, you will be prompted to do so when trying to add these Shortcuts.

untrusted shortcuts iOS