textThe contents that should be inserted to the new sheet. Must be URL-encoded. Contents are imported as Markdown by default.

formatOptional. Specifies the format of the imported text: markdown, text or html. Defaults to Markdown.

positionOptional. Set begin or end in order to insert text at the beginning of a document. If not given, the text is appended.

newlineOptional. Specifies how newlines should be inserted to the text: Set prepend to prepend the inserted text by a newline. Set append to append the inserted text with a newline and enclose to enclose the entire text with newlines.

set-sheet-title

sheetThe identifier of the sheet for which the title should be changed. (More…)

titleThe new title. Must be URL-encoded.

typeThe type of paragraph to use for the title. This argument can be set to one of the following values:

heading1, …, heading6 to use a heading paragraph.

comment to use a comment paragraph.

filename to use a filename paragraph such as @: My Filename. Only applies to sheets in external folders.

If the sheet has a first paragraph with the requested type, the paragraph contents will be changed (a heading replaces any existing heading). Otherwise, a new paragraph with the requested type and contents will be inserted at the beginning of the sheet.

Example:

ulysses://x-callback-url/set-sheet-title?sheet=hZ7IX2jqKbVmPGlYUXkZjQ&title=The new title&type=heading4&access-token=67be78e8b61e946dbc44fd5135ec99bf

move

Moves an item (sheet or group) to a target group and/or to a new position. Requires authorization.

hasLifetimeIdentifier Whether the identifier stays the same even if the group is moved or renamed. truefor items that are stored in the sections “iCloud” or “On My Mac” / “On My iPad”. false for items in external folders or Dropbox.

containersThe item descriptions for all child groups of this group. Will be empty if the parameter recursive was set to NO.

sheetsThe item descriptions for all sheets of this group. Will be empty for filters.

Sheets:

If the item is a sheet, then the object has this format:

titleThe title of the sheet.

titleTypeThe markup type of the title. Will be set to heading1…heading6, comment if the title is a heading or comment. Will be set to filename on external folders or Dropbox if the title is the sheet’s filename (e.g. @: My Filname). If no title is given this vlaue is set to null.

hasLifetimeIdentifierWhether the identifier stays the same even if the group is moved or renamed. true for items that are stored in the sections “iCloud” or “On My Mac” / “On My iPad”. false for items in external folders or Dropbox.

changeTokenA value that identifies the current verison of the sheet. The change token will have a different value whenever the sheet changes.

modificationDateThe timestamp when the sheet was last modified. The timestamp is given as the number of seconds relative to 00:00:00 UTC on 1 January 2001.

read-sheet

textOptional. Determines whether the full text of the sheet should be included in the result. The allowed values are YES and NO. Defaults to NO.

Results:

The x-success callback retrieves an argument sheet. The value is a URL-encoded JSON object. It has the following structure:

titleThe title of the sheet.

titleTypeThe markup type of the title. Will be set to heading1…heading6, comment if the title is a heading or comment. Will be set to filename on external folders or Dropbox if the title is the sheet’s filename (e.g. @: My Filname). If no title is given this vlaue is set to null.

typeThe type of the item (always sheet).

changeTokenA value that identifies the current verison of the sheet. The change token will have a different value whenever the sheet changes.

modificationDateThe timestamp when the sheet was last modified. The timestamp is given as the number of seconds relative to 00:00:00 UTC on 1 January 2001`.

hasLifetimeIdentifierWhether the identifier stays the same even if the group is moved or renamed. true for items that are stored in the sections “iCloud” or “On My Mac” / “On My iPad”. false for items in external folders or Dropbox.

textThe sheets content encoded as Markdown. This is only available if the text parameter was set to YES.

keywordsThe keywords of the sheet as an array of strings.

notesThe notes of the sheet as an array of strings. All notes are encoded as Markdown.

You can get a URL for opening sheets and groups directly within Ulysses. On iOS, just swipe on any sheet or group and select the action “More”. Then tap the “Share…” action and choose the “Copy URL” activity. A URL for opening your sheet or group has been now placed on your pasteboard. On the Mac, hold ⌥ while right-clicking an item in the Library, or a sheet in the sheets column. Select „Copy Callback URL” from the menu.

get-version

apiVersion: The version of Ulysses’ X-Callback API (e.g. 2). Use this to find out which actions (and parameters) are supported.

buildNumber: The build version number of Ulysses itself (e.g. 32193).

Identifiers

Several callbacks use so-called identifier arguments to specify the sheet or group an operation should be executed on. Identifiers are 22 characters long and are in a URL-safe encoding. E.g. ulysses://x-callback-url/open?id=DCj45UWKr_g15y2vBPwJdQ will open the item with this identifier.

Identifiers are created internally by Ulysses and allow to reference sheets and groups. If you’re using iCloud or a local library, an identifier remains the same, even if the item is edited, renamed or moved around. In external folders, the identifier can change if you move or rename an item. You can get the identifier of a sheet or a group on iOS by following these steps:

Open the sheet list or library

Swipe-left on a sheet or group and tap the „More” button

Select the „Share” action

Tap the „Copy Identifier” activity

On the Mac, hold ⌥ while right-clicking an item in the Library, or a sheet in the sheets column. Select „Copy Callback Identifier” from the menu.

Afterwards, the identifier of the sheet or group is copied to the pasteboard. The identifier has a URL-safe encoding that can be directly pasted to your x-callback action.

Paths

As an alternative to identifiers, the target group of many actions can be also specified by a path of group names. Usually, a path refers to groups inside the sections „iCloud”, „On My iPad” or „On My iPhone”. However, if a path begins with the name of an external folder (e.g. Dropbox), Ulysses will resolve the path within this folder.

A path must begin with a slash character /. Ulysses will try to match the group names in the path with the original casing first. If the group is not found, Ulysses will fall back to case-insensitive matching.

Example:

/Books/Huckleberry Finn Matches a group named „Huckleberry Finn” inside the group „Books”.

/My Dropbox/Reports If a Dropbox folder „My Dropbox” exists, this path will match the folder „Reports” inside of it.

x-callback Parameters

In addition to action parameters, there are some generic parameters you can provide optionally for any action. Many automation apps provide these arguments automatically:

x-successURL that should be opened when an action has been successfully completed. If not provided, the user stays in Ulysses. The URL will retrieve at least the following arguments:

targetIdThe ID of the sheet or group that was either created, modified or revealed by the action.

targetURLA URL that can be used to open the sheet or group that has been created , modified or revealed by the action. Depending on the action, the URL may retrieve more arguments containing additional results.

x-errorURL to be opened if an error occurred. It will retrieve the arguments errorCode and errorMessage providing further details on the error. Errors will mostly occur, if an identifier cannot be resolved. If not provided, the user stays in Ulysses if an error occurred.

Example:

If a new sheet should be created and Ulysses should return to the calling app, use the following URL (line breaks are for legibility):

On MacOS, an app can also prevent Ulysses switching to foreground. This can be done by setting the option NSWorkspaceLaunchWithoutActivation when opening the URL using NSWorkspace.

API Versions

Every Ulysses version from 2.8 onwards has an API version number, which can be retrieved using the get-version action. The version indicates which actions and parameters can be called.

If you would like to distribute an app that communicates with the X-Callback API of Ulysses, please let it call get-version first, and ensure that it only calls actions that are supported in the Ulysses version installed on the user’s system.

The table below shows the API versions supported by different versions of Ulysses: