X-callback-url Support and Reference



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:

Support Actions

  • open the On the Agenda overview

    • command: on-the-agenda:
    • parameters: none
    • example: agenda://x-callback-url/on-the-agenda
  • open the Today overview

    • command: today:
    • parameters: none
    • example: agenda://x-callback-url/today
  • open a project (identified by title or identifier)

    • command: open-project:
    • parameter (optional): title
    • parameter (optional): project-title
    • parameter (optional): identifier (of project)
    • result parameter: project (holds project identifier)
    • example: agenda://x-callback-url/open-project?title=Welcome
  • open a note (identified by title or identifier)

    • command: open-note:
    • parameter (optional): title
    • parameter (optional): identifier (of note)
    • parameter (optional): project-title
    • result parameter: note (holding identifier), and note-title
    • example: agenda://x-callback-url/open-note?title=Meeting%20With%20Peta
  • create a note (in the project with the given project title or identifier)

    • command: create-note:
    • parameter (optional): project-title
    • parameter (optional): identifier (of project)
    • parameter: title
    • parameter: text
    • parameter: 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 (base64 encoded data)*
    • parameter (optional): filename (the filename of the attachment, including file extension)
    • result parameter: note (holding identifier)
    • example: agenda://x-callback-url/create-note?project-title=My%20Project&title=New%20Note&text=Hello%20World&on-the-agenda=true&date=2018-03-12
    • example: 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
  • append text or an attachment to a note, or change the title or date

    • command: append-to-note:
    • parameter (optional): title (of note)
    • parameter (optional): identifier (of note)
    • parameter (optional): project-title
    • parameter: text (to append)
    • parameter: 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 (base64 encoded data with no line breaks)
    • parameter (optional): filename (the filename of the attachment, including file extension)
    • result parameter: note holding identifier, and note-title with title
    • example: agenda://x-callback-url/append-to-note?title=New%20Note&text=More%20Text

Note: 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.

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

Import, Export, Sharing, and Automation
Email linking from MailMate
Trying to understand how to create a shortcut

Example use cases


Hi there, what format does the date need to be in if using absolute date? I’m passing through DD-MM-YYYY but it’s not accepting it. Relative dates work (ie. Today).


Try YYYY-MM-DD, for example, this works for me:



Is there a way to use the x-callback scheme make the shortcuts app choose the parameter “Project Title” from the existing projects in Agenda?


Unfortunately not at this time I’m afraid.


If you play around with it, you will find that you can pre-add the project names to “shortcuts”, then have it ask you which project to use, I do the same for adding multiple entries to omnifocus with the same project.

split this topic #18

A post was split to a new topic: [Shortcut] Copy iOS Reminders to Agenda


After looking at both the Shortcuts actions available and the x-callback-url scheme for Agenda, I want a lot more. :smile:

Basically I’d like to have the following added, preferably as actions in Shortcuts, but x-callback-url if needed:

  • Ability to get a list of current categories, projects, and notes (each in their own list rather than one huge list is fine).
  • Ability to get any dates/times associated with a note, if they exist.
  • Ability to grab any information out of a note from Shortcuts actions without opening Agenda.

Currently all the shortcuts actions are just ways of opening Agenda to a specific point. The most useful Shortcuts actions for apps allow manipulation of data in that app without that app coming to the front and requiring manual input or further interaction.

Shortcut actions that are nothing more than launchers to specific views within an app have extremely limited automation usefulness.

Really what I want to do is to easily be able to create or edit something in Agenda and at the same time create or edit a matching task in Things, and creating shortcuts with that kind of easy coupling would be easier with greater Shortcuts utility. Also being able to automatically grab categories and projects would mean not having to manually update Shortcut menu items or programmatic choices in the Shortcut.

Thanks! Keep up the great work.


Note that we do have create-note and append-to-note x-callback-urls. These can be used from the Shortcut app to create a new note with some text, even attachment, and return to some other app. See the review by Federico: https://www.macstories.net/ios/agenda-4-0-brings-support-for-file-attachments-improved-ios-automation/

Has an example Shortcut at the end that does this.


Yeah, I know. It doesn’t make a lot of sense to me without being able to retrieve what categories and projects exist and other information.

I want a full two way street. The current x-callback-url is a partial one way street, mostly.

Also, really full native shortcut actions that don’t just open a specific app view matter to me personally.


The fact that he has to hard code note names into that shortcut is bad news. You can’t even change a note title without manually editing your Shortcut, let alone being able to support new notes or projects without more hard coding in the shortcut.


Yes, we focused so far on writing things into Agenda, we plan to add more reading abilities in the future.


Is it possible to create a project with the URL scheme somehow? My use case is that when I start a new project, I invoke a shortcut that creates folders or projects in dropbox, things, and ulysses with the title I specify. I’d like to add Agenda to the shortcut


Not yet, but it is indeed a good idea. Plenty of options to extend the scheme. We wanted something basic in place, and even bumped it up the roadmap a bit. Now that you can do basic stuff like add a new note or append, we can look to extend to a more full control. Thanks all for the feedback!


Callback support to display notes with tag XYZ and Callback support to open specific saved overviews would be great too.


I guess a callback to do a search, and get the list of note ideas in the search would be similar. You could just search for the tag.


Currently Agenda can go straight to a saved overview (iOS only) using Siri (shortcuts). But I would prefer to put a callback x-url in my separate todo app to remind me to process notes in Agenda on a repeating basis. At the moment the best Agenda callback I can manage for this use case is to simply open the app automatically in iOS


Can you explain exactly what the callback should do? Do you want to query how many notes are in Today, for example, and based on that, open the app?


Is there a way to link a note to a calendar event when creating one with a URL? I’d love to build a Shortcut that creates a note for each event on the calendar for the day.

Possible? Thanks!

Edit: Alternatively, can the URL scheme set a time along with the date? that would do it for me.