X-Callback-URL API and Other URL Schemes

Textastic for iOS exposes actions that can be used by other apps using the x-callback-url specification.

All currently implemented actions involve opening an existing file or creating a new one and inserting or replacing text.

Registered URL schemes

To target any installed version of Textastic, use the textastic:// URL scheme.

These additional URL schemes are registered by the various versions of Textastic:

App	URL Scheme
Textastic v6 and later (universal app)	x-textastic-universal://
Textastic v5 and earlier for iPad	x-textastic-ipad://
Textastic v5 and earlier for iPhone	x-textastic-iphone://

The “x-” versions are provided if you need to specifically call or test for the installation of the Universal vs. the iPad or iPhone version.

x-callback-url URL Format

The format for Textastic’s URL scheme looks like this:

textastic://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 Textastic’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 file, 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

new

Create a new file in the local file system or in iCloud.

If a file with the specified name already exists, Textastic will generate a unique file name by appending a number to the file name (e.g. “test 2.txt” instead of “test.txt”).

Parameters

location: iCloud, local, or external. If not specified, defaults to the local file system.
path: The directory path. If not specified, defaults to the root folder.
name: The name of the file to create. If a file with that name already exists, Textastic will append a number to the file name to make it unique. If not specified, a file name will be generated by Textastic.
externalUUID: If location is “external”, use this parameter to specify the identifier of an external folder. You can get the UUID by showing the context menu of an external folder in Textastic and selecting “Copy Identifier (UUID)”.
text: The text to insert into the new file.
snippet: The snippet to insert. If both the snippet and the text parameter are present, only the snippet parameter will be used.

If neither the text parameter nor the snippet parameter is specified, the text to append will come from the clipboard.

Examples

Create a new file “foo.txt” in the local root directory and insert “bar”:

textastic://x-callback-url/new?name=foo.txt&text=bar

Create a new file “foo.txt” in iCloud in the “test” folder and insert the snippet “foo $0 bar”. This snippet places the cursor between foo and bar after the insertion.

textastic://x-callback-url/new?location=icloud&name=foo.txt&path=test&snippet=foo%20$0%20bar

Create a new file “test.txt” in the specified external folder in the “test” folder and insert the clipboard contents.

textastic://x-callback-url/new?location=external&externalUUID=62E8D362-7DFA-413C-874E-20C1D98B17C0&name=test.txt&path=test

open

Open an existing file in the local file system, iCloud, or an external folder.

If the file doesn’t exist, calls the url from the x-error parameter.

Parameters

location: iCloud, local, external, or fullPath.

If not specified, defaults to the local file system.

Use “fullPath” to open an external file if you don’t know the UUID of an external folder, but have the full local path of the file in the file system. This is useful for apps that include a file provider and want to open a file in Textastic. It is used by the “Edit in Textastic” command of the Git client app Working Copy.
path: The directory path. If not specified, defaults to the root folder.
name: The name of the file to open.
externalUUID: If location is “external”, use this parameter to specify the identifier of an external folder. You can get the UUID by showing the context menu of an external folder in Textastic and selecting “Copy Identifier (UUID)”.
suggestedExternalFolderPath: If location is “fullPath”, you can specify this parameter and Textastic will prompt for adding that folder as an external folder if the file could not be accessed.

Example

Open the file “index.html” in the “example.com” folder in the local file system.

textastic://x-callback-url/open?path=example.com&name=index.html

append

Open an existing file or create a new file and append text.

Parameters

location: iCloud, local, or external. If not specified, defaults to the local file system.
path: The directory path. If not specified, defaults to the root folder.
name: The name of the file to open. If the file doesn’t exist, it will be created.
externalUUID: If location is “external”, use this parameter to specify the identifier of an external folder. You can get the UUID by showing the context menu of an external folder in Textastic and selecting “Copy Identifier (UUID)”.
text: The text to append to the file.
snippet: The snippet to append to the file. If both the snippet and the text parameter are present, only the snippet parameter will be used.

If neither the text parameter nor the snippet parameter is specified, the text to append will come from the clipboard.

Example

Append the contents of the clipboard to the file clipboard.txt in the iCloud root folder:

textastic://x-callback-url/append?location=iCloud&name=clipboard.txt

replace

Open an existing file or create a new file and replace its contents with the specified text.

Parameters

location: iCloud, local, or external. If not specified, defaults to the local file system.
path: The directory path. If not specified, defaults to the root folder.
name: The name of the file to open. If the file doesn’t exist, it will be created.
externalUUID: If location is “external”, use this parameter to specify the identifier of an external folder. You can get the UUID by showing the context menu of an external folder in Textastic and selecting “Copy Identifier (UUID)”.
text: The text to insert into the file after its contents are deleted.
snippet: The snippet to insert into the file after its contents are deleted. If both the snippet and the text parameter are present, only the snippet parameter will be used.

If neither the text parameter nor the snippet parameter is specified, the replacement text will come from the clipboard.

Example

Replace the contents of the file scratchpad.txt in the iCloud root folder with the string “foo”:

textastic://x-callback-url/replace?location=iCloud&name=scratchpad.txt&text=foo

reloadCustomizations

Reload customizations (custom syntax definitions, themes, and code completions) from the “Local Files/#Textastic” folder.

Parameters

None.

Example

textastic://x-callback-url/reloadCustomizations

Download using the textastic:// scheme

In addition to x-callback-url support, the textastic:// scheme can be used to easily download the server response of HTTP URLs.

You can use this feature to view the source code of a website or download files into Textastic.

This is what you need to do:

Make sure your iPad or iPhone has an active internet connection
Open a website in Safari or another browser app like Chrome
Tap on the address bar
Replace http:// with textastic://
Tap Go on the on-screen keyboard
Textastic will open and start to download the file at the URL. It will be saved to the root directory in the local file system. When the file is downloaded, it will be opened in the editor.