Keep It URL Support

Contents


Links to Lists and Items

Both Keep It for Mac and Keep It for iPad and iPhone can link to items and lists:

Linking to Items

Keep It can copy a link to a specific item that can be pasted anywhere.

On Mac:

  • Choose Item > Copy Item Link from the menu

While listing items on iPad or iPhone:

  • In list view, swipe left on the list, tap the … (ellipsis) button, and tap Copy Link
  • In icon view, press and hold on the item to show the menu, then tap Copy Link

While viewing an item on iPad or iPhone:

  • Tap on the item to view it
  • Tap the action button (looks like a rectangle with an arrow pointing upwards)
  • Tap Copy Item Link

The link will be in the following format:

keepit://link?item=[identifier]

Linking to Lists

Keep It can copy a link to a specific list that can be pasted anywhere.

On Mac:

  • Ctrl-click or right-click the list
  • Choose Copy Link from the menu shown

On iPad or iPhone:

  • Swipe left on the list
  • Tap the … (ellipses) button
  • Tap Copy Link

The link will be in the following format:

keepit://link?list=[identifier]

X-Callback-URLs

Keep It for iPad and iPhone supports the x-callback-url format.

Use the keepit:// scheme, ensure URLs are in the standard x-callback-url format and that all parameters are URL encoded.

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

The examples shown omit x-callback parameters for brevity.

Identifying Lists and Items

All lists and items in Keep It have unique identifiers, which can be incorporated into links (see above). It is possible to obtain these identifiers without copying a full link.

Copying Identifiers on iPad or iPhone

Lists:

  • Swipe left on the list, tap the … (ellipsis) button, and tap Copy Link Identifier

Items:

  • In list view, swipe left on the list, tap the … (ellipsis) button, and tap Copy Link Identifier
  • In icon view, press and hold on the item to show the menu, then tap Copy Link Identifier

Copying Identifiers on Mac

Although x-callback-urls are only used on iOS, it is possible to get a link identifier for both lists and items on Mac.

Lists:

  • Ctrl-click or right-click the list to show the contextual menu
  • Hold on the Option key and choose Copy Link Identifier from the menu

Items:

  • Hold on the Option key and choose Item > Copy Item Link Identifier from the menu

Available Actions

add

Add a note, file or link.

Input Parameters:
  • text
    The text of a note to add. Required for notes, and must not be specified for other types.
  • data
    Base64 encoded data of a file (must also be URL encoded). Required for files, and must not be specified for other types.
  • source
    The source URL. Required for web links, optional for everything else.
  • name
    The name for the new item. The name will be made unique if another item with the name already exists in the same location. Required if data specified, optional for everything else.
  • format
    The format of the file. Required when data specified, but only if name does not include a file extension. Ignored for everything else.
  • offline
    1 to save the web link for offline, 0 to save it as a live link. Optional for web links, ignored for everything else. If omitted, the default setting be used.
  • list
    The identifier of a target list (e.g. a folder or bundle) for the new item. See Identifying Lists and Items for information on how to get a list identifier. The list must be able to accept new items, or will be ignored. Optional for all types, and if not specified, the default import destination will be used instead.
  • tags
    Comma-separated list of tags to add to the new item. Optional for all types.
Return Values:
  • identifier
    Identifier of the newly created item, which can be used in a Keep It item link.
Notes
  • File packages (e.g. an RTFD file) must be zipped. The file will be unzipped, provided Keep It can recognize that the format would normally be a file package. Adding folders is not supported.
  • Specify the file extension in format and not in name to hide the extension in Keep It.
Examples:

Create a web link called “Apple Homepage” with the URL http://apple.com:

keepit://x-callback-url/add?name=Apple%20Homepage&source=http%3A%2F%2Fapple.com

Create a web link called “Apple” with the URL http://apple.com, and the tags “tag 1” and “tag 2”:

keepit://x-callback-url/add?name=Apple&source=http%3A%2F%2Fapple.com&tags=tag%201,tag%202

Create a note with the text “The quick brown fox jumps over the lazy dog”:

keepit://x-callback-url/add?text=The%20quick%20brown%20fox%20jumps%20over%20the%20lazy%20dog

Create a note with the text “The quick brown fox” in the All Items group:

keepit://x-callback-url/add?text=The%20quick%20brown%20fox&group=AllItems

Create a PNG image from the data (truncated in example):

keepit://x-callback-url/add?format=png&data=iVBORw0KGgoAAAANSUhEUgAAAgA…

Create an image with the name “Keep It.png” from the data (truncated in example):

keepit://x-callback-url/add?name=Keep%20It.png&data=iVBORw0KGgoAAAANSUhEUgAAAgA…

append

Append text or a file attachment to a note.

Input Parameters:
  • text
    The text to append. Required unless data is specified.
  • data
    Base64 encoded file attachment (must also be URL encoded). Required unless text is specified, in which case it’ll be ignored.
  • name
    The name for the attachment. Required for file attachments, ignored for text.
  • format
    The format of the file. Required for a file attachment if name does not include a file extension. Ignored for everything else.
  • item
    The identifier for the item. Required. The item must be a Keep It note, no other formats are supported. See Identifying Lists and Items for information on how to get an item identifier. Required.
Return Values:
  • identifier
    Identifier of the updated item (will match input).
Notes
  • File packages (e.g. an RTFD file) must be zipped. The file will be unzipped, provided Keep It can recognize that the format would normally be a file package. Attaching folders is not supported.
  • Specify the file extension in format and not in name to hide the extension in Keep It.
Examples:

Append “The quick brown fox” to an item with identifier C96F26E6-A566-457E-A448-5B0F527714DE:

keepit://x-callback-url/append?text=The%20quick%20brown%20fox&item=C96F26E6-A566-457E-A448-5B0F527714DE

Append an image (data truncated in example) with the name “App Icon.png” to an item with identifier 079B3A6A-18B4-41A6-858B-3F3DBA6F87F3:

keepit://x-callback-url/append?name=App%20Icon.png&item=079B3A6A-18B4-41A6-858B-3F3DBA6F87F3&data=iVBORw0KGgoAAAANSUhEUgAAAHgAAAB4CAYAAAA5ZDb…