iA / Writer / Support / Help

URL Commands

URL Commands 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 Commands can also be used to change some of iA Writer’s defaults.

On iOS, these URL Commands 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-Commands/EXAMPLES.txt

Opens EXAMPLES.txt (file) which is saved in iCloud → Website → URL-Commands (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:

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:


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:

🔆 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 StartedWe 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

Help

Troubleshooting

Here are some things you can do if iA Writer acts in unexpected ways.

FAQ

Below are answers to common questions. Everyone is special, but most questions that we get overlap.

iCloud

iA Writer is file storage provider agnostic but we recommend iCloud for the best experience across most devices:

Backups and Recovery

Lost progress in a document? Regret deleting that paragraph? No problem!

Legacy Apps

Whenever possible, troubleshooting steps are listed here for iA Writer Classic on macOS & iOS and Writer 1.5.2 for Android.

Version History

Scroll through the history of our apps, version by version, platform by platform, update by update.

Privacy Policy

Which information do we see, and what do we leave untouched?

Accessibility

We want our products to be enjoyed by the widest possible audience.

URL Commands

Open iA Writer from other applications on both macOS and iOS, and perform specific actions on opening.