Home | Appendix

|  |  | Item links

Every database, group, or document in your DEVONthink database has a URL (uniform resource locator) associated with it. While web URLs typically begin with `http://` or `https://`, DEVONthink's URLs take the form of `x-devonthink-item://` followed by a long alphanumeric ID. For PDFs, the link can contain a reference to a specific page. For audio and video, a reference to the current playback time. And for RTFs, you can get a reference to a specific paragraph in the document. These links can be used in any file type or application that supports live hyperlinks, e.g., the notes fields of OmniFocus tasks. This allows you to access DEVONthink documents as easily as clicking a link in a web browser. You can get this item link manually by selecting a document or group and choosing Edit > Copy Item Link. In addition you can manually extend the copied URL with the following parameters: app: Used in conjunction with the `openexternally` parameter, specify the name of the app to open the referenced file with, e.g., `x-devonthink-item://E35A4AFF-BD90-4131-9D54-62849E0EF4DE?openexternally=1&app=preview`. length: Specify the number of characters from the `start` parameter. Used in selection links. openexternally: Opens the referenced item in the system default application, e.g., opening a PDF in Preview. Used with a value of 1, e.g., `openexternally=1`. opentab: Opens the referenced item in a new tab in the current main window if a document is already being viewed. Used with a value of 1, e.g., `opentab=1` page: Opens a PDF to the specified page. Usage: `page=<integer>`. reveal: Reveals an item in the item list instead of opening it in a new window. Usage: `reveal=1`. search: Directly jumps to the first occurrence of the search string in the specified document. Usage: `search=<string>`. start: Specify the starting character on the current page. Used in selection links. time: Directly jumps to the specified time in seconds in a video or audio document. Usage: `time=<float>`.
Example: x-devonthink-item://<recordID>?reveal=1 x-devonthink-item://<pdfID>?page=5 x-devonthink-item://<textFileID>?search=iPad%20Pro x-devonthink-item://<movieID>?time=43.5
Note: The first parameter after the ID is always added after a question mark (?), additional ones after an ampersand (&), and any values must be percent-encoded.
Terminology Manually getting item links can be useful for some hard-coded cases, but there are many times you want to get them programmatically. There are two AppleScript properties for a `record` related to item links: reference URL: This is the item link as described above. UUID: This is the unique identifier of the item, i.e., the long alpha-numeric string in the reference URL. Here is an example of getting and using an item link to create a Markdown compliant link on the clipboard:
Example: tell application "DNtp" set recordName to name of content record set recordURL to reference URL of content record set the clipboard to ("[" & recordName & "](" & recordURL & ")") end tell
The terminology for using item links can depend on the capabilities of the application you're scripting. Here is an example, using a hard-coded URL, with an application that can open URLs:
Example: tell application "Opera" tell window 1 make new tab with properties {URL:"x-devonthink-item://929D101B-35AC-474C-801C-D8818C48DB80?line=125"} end tell end tell
P.S.: For the shell scripters, the URLs can be used with an `open` command.