iA Writer supports a variety of commands to open, create, read, and write files.

Summary

Overview

Commands can be set to iA Writer by constructing special URLs:

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

x-callback-url

All commands can support x-callback-url:

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

Some commands will return parameters on x-success.

Auth

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

Data Types

String
Percent encoded. 4,000 or fewer characters before encoding.
Path
Percent encoded.
/ 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.
Use contextual menu in Library and Organizer to copy paths on macOS.
Tap and hold items in Library to copy paths on iOS.
Boolean
Either true or false.

Interface Commands

Open a screen in iA Writer.


open command

Opens Editor with an existing document.

Parameters
path
Path. Required. Path to file.
edit
Boolean. Optional. If true, keyboard will be shown on iOS devices.
Return parameters on x-success

None.


new command

Opens Editor with a new document.

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 iOS devices.
Return parameters on x-success

None.


Opens Quick Search with a given query.

Parameters
query
String. Optional.

Return parameters on x-success

None.


Data Commands

Silenty read and write data.


read command

Reads and returns files contents.

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.

write command

Creates or modifies an existing file and returns file contents.

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.

version command

Returns iA Writer app version and URL scheme version.

Parameters

None.

Return parameters on x-success

scheme-version
String. URL scheme version.
app-version
String. App version.

Version History

1
Initial release.
2
Fixed write command parameter append-padding. It was inverted in version 1. It was inverted in version 1: padding was appended with false, and not appended with true.