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 (v1.4.2 and later) and Keep It for Mac (v1.8 and later) support 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, and assume the default new file type is note, and not stationery.
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 List Identifier
Items:
- In list view, swipe left on the item, tap the … (ellipsis) button, and tap Copy Item Identifier
- In icon view, press and hold on the item to show the menu, then tap Copy Item Identifier
Copying Identifiers on Mac
Lists:
- Ctrl-click or right-click the list to show the contextual menu
- Hold on the Option key and choose Copy Identifier from the menu
Items:
- Hold on the Option key and choose Item > Copy Item Identifier from the menu
Available Actions
add
Add a note, text file, other file from data, or a web link.
Input Parameters:
text
The text to add. Required when creating notes or text files, and must not be specified for other types.style
Case-insensitive name of the note style to apply to the addedtext, as it appears in the app (e.g. Heading). Only used when creating Keep It notes.link
The link of thetextfor notes and rich text documents only. Ignored for everything else. Usesourcefor web links.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 ifdataspecified, optional for everything else.format
The format of the file. Required whendataspecified, but only ifnamedoes not include a file extension. Can be included whentextis specified to determine the type of file created — note, txt, rtf, rtfd and any Markdown file extension is supported (requires Keep It 1.5 or later). When saving a web link for offline, optionally use either “webarchive” or “pdf” to override the default.offline
1to save the web link for offline,0to save it as a live link. Optional for web links, ignored for everything else. If omitted, the default setting be used.minimal
1to save the web link in a minimal format, if possible, 0 to prevent that. Optional for web links, ignored for everything else. If omitted, the default setting be used.label
The identifier of a label for the new item. See Identifying Lists and Items for information on how to get a label’s identifier. Requires Keep It 1.11.5 or later.list
The identifier of a target 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 a folder, bundle, or All Items (and in versions earlier than v1.11.5 could also be a label), or it 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.comments
Any comments 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 specified in
data(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
formatand not innameto 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 plain text file with the text “The quick brown fox jumps over the lazy dog” (Keep It 1.5 and later):
keepit://x-callback-url/add?text=The%20quick%20brown%20fox%20jumps%20over%20the%20lazy%20dog&format=txt
Create a note with the text “The quick brown fox” in the All Items list:
keepit://x-callback-url/add?text=The%20quick%20brown%20fox&list=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 to a note, rich text, Markdown or plain text file. Append a file attachment to a note or rich text file.
Input Parameters:
text
The text to append. Required unlessdatais specified.style
Case-insensitive name of the note style to apply to the addedtext, as it appears in the app (e.g. Title or Heading). Only used when appending to Keep It notes.link
The link of thetextfor notes and rich text documents only. Ignored for everything else. Usesourcefor web links.data
Base64 encoded file attachment (must also be URL encoded). Required unlesstextis 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 ifnamedoes not include a file extension. Ignored for everything else.item
The identifier for the item. Required. For attachments, the item must be a Keep It note or rich text file, for text the item can be any note, rich text, Markdown or plain text file. 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
formatand not innameto 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…