X-callback-url Support and Reference

Your workflow sounds fine to me.

There is not really one way to use the app. It depends on the “granularity” of your projects as to what is best. For example, if you were finding that your notes for each project you have were getting really long and ungainly, you might consider making the real life project into an Agenda project, and splitting that really big note over several notes (eg one per week, one per sub-topic etc).

But if you find your notes are workable with the current setup, I think your approach is the right one.

1 Like

I am trying to set up a x-callback-url which will append a line to a note if it exists. If the note does not exist I am trying to use the &x-error parameter to add the note (with the intent of then putting an &x-success behind that to add the line). This currently works if the note exists, but it does not seem to add the note if it does not. Hoping someone can see what I am doing wrong.



Hmm, we haven’t tested this type of thing, to be honest. You are trying to call into Agenda while Agenda is still handling the previous request. I suspect that could lead to some odd behavior.

A way around may be to go back to shortcuts on error and issue the create-note there.

Ah, and you probably need to “percent encode” the special characters in the error URL, otherwise they could be confused for the first URL. Eg. & and ? etc.

To do this, you can use a web site like this:


To add to Drew’s comment, the Shortcuts app has a URL encode step you can use in your workflow.

1 Like

I’ve just created a Shortcut that seems to almost successfully create a note with an image attachment using the URL scheme and base64 encoding. The image appears as a thumbnail in the note as I would expect; however, when I long press the image to get the image options popover, the “Preview” button does nothing. When I insert an image into a note normally, this button shows a full-screen version of the image. Does adding images via the URL scheme make the Preview function not work?

Can you give an example of how one would extract the note ID from Shortcuts after this step? I can’t seem to figure it out. See this Shortcut that I’m working on to create a new Agenda and Things item at once: I’d like the Agenda note ID to be passed into a new Things task, but am getting stuck.


Is this still an issue? Sounds a bit odd that you can see the image, but can’t preview it.

I’m not that familiar with the Shortcuts app, but it seems to me you should do the same for Agenda as you are doing for Things. Namely, use an “Open X-Callback URL” stage, and set a x-success option so that it calls back to shortcuts. Agenda will then pass back a parameter in the URL (ie note=ABCDE or something). That is the note id.

I don’t know how you extract that parameter, but it must be possible using the Open X-Callback URL section.

I recommend throwing the question out in a separate topic in the Shortcuts section. There are some experts that can surely point the way.

1 Like

A post was split to a new topic: Creating a reminder with Shortcuts

A post was split to a new topic: Append-to-note without changing insertion pointer

Just to summarize findings: it turns out there is a bug in the iOS version of Agenda that prevents results being passed back through x-success. We have fixed it, an it will be in a future version. The macOS version does not have the bug.

1 Like

First off, great app!

I’m using the functionality described above. However, on macOS, using Agenda 6.0.1, it appears that the url passed to x-success is losing some of its path and/or parameters. It seems a bit similar to the bug that was recently fixed on iOS but no results need to be passed back (only the url needs to be called).

Here’s an experiment that illustrates the problem (I have a project called “Test”):

First, this command works as expected and creates a note:

open "agenda://x-callback-url/create-note?title=Test1&text=testcontent&project-title=Test"

Second, also this command works as expected and the Apple website is opened in Safari (or the note if it exists):

open "agenda://x-callback-url/open-note?title=TestTitle&project-title=Test2&x-error=http%3A%2F%2Fapple.com"

Third, this combination of the two previous commands fails (the intention is to create the note if it does not exists):

open "agenda://x-callback-url/open-note?title=Test3&project-title=Test&x-error=agenda%3A%2F%2Fx-callback-url%2Fcreate-note%3Ftitle%3DTest3%26text%3Dtestcontent%26project-title%3DTest"

If I try this with another app’s callback url in the x-success parameter (e.g. Bear or LaunchBar), the other app is activated but the specific action is also there not executed.

1 Like

I’m afraid we never considered the possibility that the calls would be re-entrant, ie, that Agenda would activate Agenda via one of the URLs. So I would need to test why this happens. Will add to list. Thanks for reporting it.

Kind regards,

1 Like

An awesome app indeed :slight_smile:

Is that possible to use x-callback-url to open saved overview/searches?
Seems like currently it’s not really the case

We’ll have a look if this is possible indeed.

1 Like

I would like to see a callback for general searches. I have a lot of searches that I would like to do, that I don’t want showing up in my saved searches side bar. I’d like to put search links directly within Agenda notes. What would be amazing is that, in addition to the “save search as overview,” there was a “copy search as link” so I can set up a search via the UI and then copy and paste its search link into one of my other notes.


Makes a lot of sense to extend the x-url-callback scheme to allow to create searches indeed.

Quick Update: We’ve just finished adding support for triggering a search with a given query, as well showing overviews just like you can show projects, through new x-callback-urls. This will become available in the update following those that are already awaiting the new iOS and macOS releases, most likely version 9. The moment they become available I’ll update the reference at the top of this post with examples.


Version 9 of what?