A quick intro to x-callback-urls
- The URL scheme is
agendaoragenda-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
titleparameter. - As usual, you can supply callback URLs via optional
x-successandx-errorparameters.
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), andnote-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), ornote(holding the note identifier)
Examples - example1:
agenda://x-callback-url/get-identifier?project-title=Welcomereturns the identifier of project “Welcome” - example2:
agenda://x-callback-url/get-identifier?project-title=Welcome&title=Things%20to%20Tryreturns the identifier of note “Things to Try” in project “Welcome” - example3:
agenda://x-callback-url/get-identifier?title=Things%20to%20Tryreturns 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-projectreturns 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-notereturns 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) orproject(holding the project identifier),project-title(holding the project title)
Examples - example:
agenda://x-callback-url/get-selectionreturns 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) andnote-title(holding the note title), orproject(holding the project identifier) andproject-title(holding the project title)
Examples - example:
agenda://x-callback-url/get-selectionreturns 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_contentplaceholder) - 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, ortiny, 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, ortiny, small, medium, large)
Result - result parameter:
noteholding identifier, andnote-titlewith 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-notecommand.
Note 1: Adding an attachment requires both the
attachmentandfilenameparameter. 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-titleon “Today”. Otherwise if either adateorstart-date+end-dateis given, Agenda looks for the first event that has the givenevent-titleon the given day or in the given day range. The most precise way to link to an event is to provide both theevent-titleas well as the exactstart_dateof the event.
Note3: The text and title parameters also support the new text commands like
\date(short)and\timeas 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%2Fsuccesswill open the urlmyapp://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%2Ferrorwill open the urlmyapp://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.
