Knowledgebase

Ulysses X-Callback-URL Support

| By Juraj

Ulysses supports x-callback-urls, allowing other apps to trigger certain actions in Ulysses such as opening existing sheets or creating new sheets, groups or attachments.

(Documentation for Ulysses 2.6 and later)

The URL Scheme

The used scheme is ulysses://. Every action can be called through the x-callback-url API using the following format:

ulysses://x-callback-url/[action]?[x-callback parameters]&[parameters]

For more information regarding the URL format, see the official specification.

Available Actions

In the following, all available actions are detailed. Please note that for reasons of clarity, the examples are not yet URL escaped. For instance, all whitespace must be replaced with %20.

 

new-sheet

Creates a new sheet.

Parameters:

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

  • group
    Optional. Specifies the group the new sheet should be inserted to. This argument can be set to one of the following values:

    1. A group name (e.g. My Group) that will match the first group having the same name, regardless of its position in the group hierarchy.
    2. A path to a particular target group (e.g. /My Group/My Subgroup). Any path must begin with a slash. (More…)
    3. A unique identifier of the target group. (More…)
    4. If no value is given, the sheet is created inside the Inbox.
  • format
    Optional. Specifies the format of the imported text: markdown, text, html. Defaults to Markdown.

Example: ulysses://x-callback-url/new-sheet?text=My new sheet

 

insert

Inserts or appends text to a sheet.

Parameters:

  • id
    The identifier of the sheet the text should be inserted to. (More…)
  • text
    The contents that should be inserted to the new sheet. Must be URL-encoded. Contents are imported as Markdown by default.
  • format
    Optional. Specifies the format of the imported text: markdown, text, html. Defaults to Markdown.
  • position
    Optional. Set begin or end in order to insert text at the beginning of a document. If not given, the text is appended.
  • newline
    Optional. 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.

Example: ulysses://x-callback-url/insert?id= H8zLAmc1I0njH-0Ql-3YGQ&text=Inserted text

 

attach-note

Creates a new note attachment on a sheet.

Parameters:

  • id
    The identifier of the sheet the note should be attached to. (More…)
  • text
    The contents that should be attached as note to the new sheet. Must be URL-encoded. Contents are imported as Markdown by default.
  • format
    Optional. Specifies the format of the imported text: markdown, text, html. Defaults to Markdown.

Example: ulysses://x-callback-url/attach-note?id= H8zLAmc1I0njH-0Ql-3YGQ&text=My new note

 

attach-image

Creates a new image attachment on a sheet.

Parameters:

  • id
    The identifier of the sheet the image should be attached to. (More…)
  • image
    The image data that should be used. The data must use base64 encoding. Make sure that the base64-encoded data is also URL encoded.
  • format
    The format of the provided image (use an image path extension, like png, pdf, jpg, raw, gif).
  • filename
    A filename the image format should be detected from. Either the argument format or filename must be provided.

Example: ulysses://x-callback-url/attach-image?id=H8zLAmc1I0njH-0Ql-3YGQ&image=iVBORw0KGgoAAAANSUhEUg…

 

attach-keywords

Adds one or multiple keywords to a sheet.

Parameters:

  • id
    The identifier of the sheet the image should be attached to. (More…)
  • keywords
    A comma separated list of keywords that should be attached to a sheet.

Example: ulysses://x-callback-url/attach-keywords?id=H8zLAmc1I0njH-0Ql-3YGQ&keywords=Draft,Important

 

new-group

Creates a new group.

Parameters:

  • name
    The name of the group to be created.

  • parent
    Optional. Specifies the parent group the new group should be inserted to. This argument can be set to one of the following values:

    1. A group name (e.g. My Group) that will match the first group having the same name, regardless of its position in the group hierarchy.
    2. A path to a particular target group (e.g. /My Group/My Subgroup). Any path must begin with a slash. (More…)
    3. A unique identifier of the target group. (More…)
    4. If no value is given, the group is created inside the top level group.

Example: ulysses://x-callback-url/new-group?name=My Group

 

open

Open a sheet or a group with a particular identifier in Ulysses.

Parameters:

  • id
    Specifies the sheet or group that should be opened. This argument can be set to one of the following values:

    1. A group name (e.g. My Group) that will match the first group having the same name, regardless of its position in the group hierarchy.
    2. A path to a particular group (e.g. /My Group/My Subgroup). Any path must begin with a slash. (More…)
    3. A unique identifier of a sheet or group that should be opened. (More…)

Notes: You can get an URL for opening sheets and groups directly within Ulysses. Just swipe on any sheet or group and select the action “More”. Then tap the “Share…” action and choose the “Copy URL” activity. An URL for opening your sheet or group has been now placed on your pasteboard.

Example: ulysses://x-callback-url/open?id=hZ7IX2jqKbVmPGlYUXkZjQ

 

open-all, open-recent, open-favorites

Opens the special groups “All”, “Last 7 Days” and “Favorites”.

 

Identifiers

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

Identifiers are created internally by Ulysses and allow to reference sheets and groups. You can get the identifier of a sheet or a group in Ulysses for iPad or by following these steps:

  1. Open the sheet list or library
  2. Swipe-left on a sheet or group and tap the „More” button
  3. Select the „Share” action
  4. Tap the „Copy Identifier” activity

Afterwards, the identifier of the sheet or group is copied to the pasteboard. The identifier itself has an 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 a Dropbox folder, Ulysses will resolve the path within this Dropbox folder.

Any 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/ReportsIf 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-success
    URL that should be opened when an action has been successfully completed. If not provided, the user stays in Ulysses. The URL will receive the following arguments:

    1. targetId
      The ID of the sheet or group that was either created, modified or revealed by the action.
    2. targetURL
      An URL that can be used to open the sheet or group that has been created , modified or revealed by the action.
  • x-error
    URL to be opened if an error occurred. It will receive 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):

ulysses://x-callback-url/new-sheet?
    x-success=sourceapp://x-callback-url/success&
    group=Lecture Notes

On success, Ulysses will call the following URL to return to the calling app:

sourceapp://x-callback-url/success?
    targetId=H8zLAmc1I0njH-0Ql-3YGQ&
    targetURL=ulysses://x-callback-url/open?id=H8zLAmc1I0njH-0Ql-3YGQ

Ulysses X-Callback-URL Support

Learn how to trigger actions from other apps using URLs.