X-callback-url Support and Reference

system · January 24, 2019, 3:39pm

A quick intro to x-callback-urls

The URL scheme is agenda or agenda-notes
Commands currently include on-the-agenda, today, open-project, etc. See below for a complete list.
For “open-project” and “open-note”, you can stipulate the target using a title parameter.
As usual, you can supply callback URLs via optional x-success and x-error parameters.

For example, to open Agenda to a note called “Meeting With Peta”, you could use this URL:
agenda://x-callback-url/open-note?title=Meeting%20With%20Peta

Read more about x-callback urls at http://x-callback-url.com

Tip: Agenda also comes with a set of App Shortcuts that match most of the below x-callback-url actions. Learn more about how to use those in the Shortcuts Support and Reference topic…

Supported Actions

Open the On the Agenda overview

command: on-the-agenda:
Parameters
parameters: none
Example
example: agenda://x-callback-url/on-the-agenda

Open the Today overview

command: today:
Parameters
parameters: none
Example
example: agenda://x-callback-url/today

Open a saved overview (identified by title or identifier)

command: open-overview :
Parameters
parameter (optional): title
parameter (optional): identifier (of overview)
New in Agenda 18.0:
parameter (optional): separate-window
Result
result parameter: overview (holds overview identifier)
Example
example: agenda://x-callback-url/open-overview?title=This%20Week

Open a search (optionally with a query)

command: open-search :
Parameters
parameter (optional): query
New in Agenda 18.0:
parameter (optional): separate-window
Examples
example: agenda://x-callback-url/open-search
example: agenda://x-callback-url/open-search?query=%23Important

Open a project (identified by title or identifier)

command: open-project:
Parameters
parameter (optional): title
parameter (optional): project-title
parameter (optional): identifier (of project)
New in Agenda 18.0:
parameter (optional): separate-window
Result
result parameter: project (holds project identifier)
Example
example: agenda://x-callback-url/open-project?title=Welcome

Open a note (identified by title or identifier)

command: open-note:
Parameters
parameter (optional): title
parameter (optional): identifier (of note)
parameter (optional): project-title
New in Agenda 18.0:
parameter (optional): separate-window
Result
result parameter: note (holding identifier), and note-title
Example
example: agenda://x-callback-url/open-note?title=Meeting%20With%20Peta

Get identifier for note or project (identified by title)

command: get-identifier:
Parameters
parameter (optional): project-title
parameter (optional): title (of note)
Result
result parameter: project (holding the project identifier), or note (holding the note identifier)
Examples
example1: agenda://x-callback-url/get-identifier?project-title=Welcome returns the identifier of project “Welcome”
example2: agenda://x-callback-url/get-identifier?project-title=Welcome&title=Things%20to%20Try returns the identifier of note “Things to Try” in project “Welcome”
example3: agenda://x-callback-url/get-identifier?title=Things%20to%20Try returns the identifier of note “Things to Try” in whichever project it resides

Get identifier and title of the selected project

command: get-selected-project:
Parameters
parameters: none
Result
result parameter: project (holding the project identifier), project-title (holding the project title)
Examples
example: agenda://x-callback-url/get-selected-project returns the identifier and title of the currently selected project in the sidebar"

Get identifier and title of the selected note

command: get-selected-note:
Parameters
parameters: none
Result
result parameter: note (holding the note identifier), note-title (holding the note title)
Examples
example: agenda://x-callback-url/get-selected-note returns the identifier and title of the currently selected note of the currently selected project"

Get identifier and title of the selected note or project (if no note is selected)

command: get-selection:
Parameters
parameters: none
Result
result parameter: note (holding the note identifier), note-title (holding the note title) or project (holding the project identifier), project-title (holding the project title)
Examples
example: agenda://x-callback-url/get-selection returns the identifier and title of the currently selected note or the currently selected project if no note is selected"

Get identifier and title of the selected note or project

command: get-selection:
Parameters
parameters: none
Result
result parameter: note (holding the note identifier) and note-title (holding the note title), or project (holding the project identifier) and project-title (holding the project title)
Examples
example: agenda://x-callback-url/get-selection returns the identifier and title of the currently selected note of the currently selected project. If there is no selected note, it will attempt to return the identifier and title of the currently selected project."

Create a category (with the given title)

command: create-category:
Parameters
parameter: title
Result
result parameter: category (holding identifier)
Example
example: agenda://x-callback-url/create-category?title=New%20Category

Create a project (in the category with the given title or identifier)

command: create-project:
Parameters
parameter (optional): category-title
parameter (optional): identifier (of category)
parameter: title
parameter (optional): select (true or false)
parameter (optional): sort-order (the sort order of the notes in the project, which can be one of the following: newest-first, oldest-first)
Result
result parameter: project (holding identifier)
Example
example: agenda://x-callback-url/create-project?category-title=Some%20Category&title=New%20Project

Create a note (in the project with the given project title or identifier, optionally from a template)

command: create-note:
Parameters
parameter: title
parameter: text
parameter (optional): project-title, or
parameter (optional): identifier (of project). New in Agenda 14.0: If no project-title is provided the currently selected project is used (if there is no single selected project, and error is returned)
parameter (optional): on-the-agenda (true or false)
parameter (optional): date (natural language or absolute dates)
parameter (optional): start-date (natural language or absolute dates)
parameter (optional): end-date (natural language or absolute dates)
parameter (optional): attachment (data as base64 encoded string without linebreaks)*
parameter (optional): filename (the filename of the attachment, including file extension)
parameter (optional): event-title (of the event to link the note to) **
parameter (optional): template-name (as shown in template manager)
parameter (optional): template-input (optional input, will replace the \shared_content placeholder)
parameter (optional): collapsed (true or false)
parameter (optional): completed (true or false)
parameter (optional): pinned (true or false)
parameter (optional): footnote (true or false)
parameter (optional): select (true or false, whether to select the created note in Agenda)
parameter (optional): display-style (the display style of the attachment, which can be one of the following: full-width, thumbnail, thumbnail-with-details, inline)
parameter (optional): display-size (the size at which a full-width attachment is displayed, which can be one of the following: 25, 50, 75, 100, or tiny, small, medium, large)
Result
parameter: note (holding identifier)
Examples
example1: agenda://x-callback-url/create-note?title=New%20Note&text=Hello%20World
example2: agenda://x-callback-url/create-note?project-title=My%20Project&title=New%20Note&text=Hello%20World&on-the-agenda=true&date=2018-03-12
example3: agenda://x-callback-url/create-note?project-title=Blogposts&title=New%20Post29&text=Hello%20World&on-the-agenda=false&start-date=yesterday&end-date=tomorrow
example4: agenda://x-callback-url/create-note?project-title=My%20Project&text=Hello%20World&event-title=Meeting&date=2020-07-22
example5: agenda://x-callback-url/create-note?project-title=Reviews&template-name=Book%20Review&template-input=blablabla

Append or replace text or an attachment to a note, link to a calendar event, or change the title or date

command: append-to-note:, or
command: replace-note:
Parameters
parameter (optional): title (of note)
parameter (optional): identifier (of note)
parameter (optional): project-title
parameter: text (to append)
parameter (optional): on-the-agenda (true or false)
parameter (optional): date (natural language or absolute dates)
parameter (optional): start-date (natural language or absolute dates)
parameter (optional): end-date (natural language or absolute dates)
parameter (optional): attachment (data as base64 encoded string without linebreaks)
parameter (optional): filename (the filename of the attachment, including file extension)
parameter (optional): event-title (of the event to link the note to) **
parameter (optional): collapsed (true or false)
parameter (optional): completed (true or false)
parameter (optional): pinned (true or false)
parameter (optional): footnote (true or false)
parameter (optional): select (true or false, whether to select the updated note in Agenda)
parameter (optional): display-style (the display style of the attachment, which can be one of the following: full-width, thumbnail, thumbnail-with-details, inline)
parameter (optional): display-size (the size at which a full-width attachment is displayed, which can be one of the following: 25, 50, 75, 100, or tiny, small, medium, large)
Result
result parameter: note holding identifier, and note-title with title
Example
example: agenda://x-callback-url/append-to-note?title=Some%20Note&text=More%20Text
example: agenda://x-callback-url/replace-note?title=Some%20Note&text=Replacement%20Text
see also above examples for the create-note command.

Note 1: Adding an attachment requires both the attachment and filename parameter. Attachment data should be provided as a base64 encoded string. Also make sure the string is properly URL escaped.

Note 2: If no date is provided Agenda looks for events with the given event-title on “Today”. Otherwise if either a date or start-date+end-date is given, Agenda looks for the first event that has the given event-title on the given day or in the given day range. The most precise way to link to an event is to provide both the event-title as well as the exact start_date of the event.

Note3: The text and title parameters also support the new text commands like \date(short) and \time as described in Creating and Using Templates - #4 by system

Success and Error Callbacks

Success Callback

command: x-success:
Parameters
parameters: see the Result section of each of the above actions
Example
example: agenda://x-callback-url/open-project?title=Welcome&x-success=myapp%3A%2F%2Fsuccess will open the url myapp://success?project=some_uuid

Error Callback

command: x-error:
Parameters
parameter: errorCode (holding the error code, following common HTML style error codes)
parameter: errorMessage (holding a description of the error)
Example
example: agenda://x-callback-url/open-project?title=Bogus&x-error=myapp%3A%2F%2Ferror will open the url myapp://error?errorCode=404&errorMessage=Target%20Not%20Found

Using x-callback URLs in the Shortcuts app

Agenda comes with a set of Shortcuts that you can use in the Shortcuts app to automate Agenda and integrate with other apps. These Shortcuts in many cases match 1-to-1 with the the above x-callback actions. The can also be mixed and matched however, learn more on how to use x-callback-urls in the Shortcuts app in the Shortcuts reference topic.