X-callback-url Support and Reference



Sorry for not being clearer. I would like a callback that can open all agenda.app entries tagged with #todo. However as I have a saved overview that filers by this tag, I guess a callback to that saved overview would do the same thing. Is this possible?


I’m afraid it is not yet possible. We will extend the x-callback functions over time. For now we just added the very basics, namely appending some text to a note, and creating a new note. There is not querying of projects etc yet, but we certainly would like to do this.


Also very interested in this.


Since Agenda doesn’t support handwriting (yet), I use Nebo for handwriting and immediately get the converted text. I’d like to be able to share/export that into Agenda. The current model which is to Select All, Copy, change App, Paste is akward. It would be nice to just Share to Agenda, when I start Agenda, I get a message saying that a note was shared, where do you want to put it.


I’ll second that request!


Update: New in version 4.1 and higher

  • the open-project, open-note, create-note, and append-to-note actions now append a project or note result parameter to the x-success url containing the identifier of the created/changed project or note. This identifier can be used as input for subsequent action calls.
  • x-error parameters are now more informative.


Having trouble getting the create note action to work with project names that have multiple words. Using the %20 string doesn’t seem to be translating to a project in the app; just opens the app and does nothing. Might be an issue with the app’s recognition of the URL scheme with spaces for that command? Either that or I’m doing something dumb :smile: here’s the shortcut I’m using: https://www.icloud.com/shortcuts/defa202ae2c04555b3a1955fa14f9aa8


I had a quick try with raw urls and it seems to all work fine here:


so the issue must be with how you set up the shortcut and how it generates the url.


Could we get an example of what getting an x-callback result might look like? I’ve had absolutely no luck getting anything returned on a simple create-note call in Shortcuts. The notes are created just fine, but the X-Callback Result variable doesn’t contain a thing.


First make sure you use version 5, earlier versions didn’t return anything. Next, the return value is an added parameter to your return x-success url. In other words, the call itself returns nothing, but if you provide a callback url with the x-success parameter, that url will be called with an additional parameter containing the return value.

For example, if you call it with an x-success parameter that is something like:


we’ll call that on success as:


Hope that helps.


I think I understand. So to use the note ID, the shortcut would have to look something like…


The result would be to create a new note in the project Project with the title Note and text something, and then to copy the note ID to the clipboard via an x-success callback to a Shortcut named Copy Agenda Note ID to clipboard.

Assuming the Shortcut works as prescribed, that would work?

Update: I tested it and it worked—sorta. I updated the “Copy” shortcut to create a full x-callback-url to open the ID’d note but can’t seem to make that work and I’m tired of trial and error right now. :wink:


Yes, so if you provide the following x-success URL:

It will be called by Agenda as:


In the short cuts app you can then extract the identifier of the created note from the note parameter.


Just an observation… Agenda doesn’t appear to be listed on the Apps page of http://x-callback-url.com which you reference above. You might want to get yourself on that list.


Thanks for the tip, I’ve pinged them.


There was some mention of providing search support with the x-callback API. I would settle for being able to open Agenda in the Search All “tab” with text I passed in the URL as a good starting point. This would allow for some basic Alfred integration for me.

Also, while I am thinking of it, is there a way to create a note in a project and category? It is possible to have duplicate project names in different categories. Or do I have to rely on the identifier?


On the first problem: Keyboard Maestro would likely give you a way of doing the paste-text-in-search thing via Select Menu Item actions. I think.


The list above is complete, so you can’t create projects at this point. There are a bunch of things there (eg listing projects, listing categories, adding projects, searching) still to do. No rest for the wicked!