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.

1 Like

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.

1 Like

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!

1 Like

Has your development team look at implementing a prepend to note action?

Append is wonderful and prepend may prove useful for keeping the most recent information at the top of a note versus scrolling to the bottom.

Maybe it’s possible. Maybe it’s not. I hadn’t seen it mentioned on any of the other comments.

I personally use Agenda’s URL scheme daily. Thanks for your effort!

It isn’t possible at the moment I’m afraid. Does it really need to be a prepend of text in the same note though? Wouldn’t it make sense to create a new note with the desired text? Given the default reverse chronological order this new note would sort to the top and as such keep the most recent info at the top of the project.

1 Like

Your reply makes me think I may not be using Agenda as intended. While the app doesn’t lock users into a specific workflow, there does appear to be an ideal paradigm.

If you have the patience, I can briefly explain how I use Agenda. I do welcome feedback from the community, and I am willing to adjust my workflow in favor of a more efficient process.

Currently, I keep several generalized Agenda projects (i.e., Finances) within broad Agenda categories (i.e., Family.) Within these general projects, I keep one note per specific project. For instance, last month my village sent out trash tax statements, so I created a note in the Finances project to keep track of the taxes. I updated this single note as I progressed through the project. I used Drafts to append text to the note with each update adding a timestamp followed by the update text.

I safeguard my events, only linking notes to actual events on my calendar. I do not assign new notes to the current date by default. I realize this causes complications with searching notes using Agenda’s date tools. Using the village taxes project as an example, I added the due date to my calendar and linked the tax note to that date. For projects not associated with a calendar event, I keep the note organized and updated but do not connect it with a date.

I hope I described my note setup clearly. I realize my workflow may not embrace all of Agenda’s functionality. I am happy to entertain other’s opinions or ideas if I can improve my workflow.