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:
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), and note-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), or note (holding the note identifier)
    Examples
  • example1: agenda://x-callback-url/get-identifier?project-title=Welcome returns the identifier of project “Welcome”
  • example2: agenda://x-callback-url/get-identifier?project-title=Welcome&title=Things%20to%20Try returns the identifier of note “Things to Try” in project “Welcome”
  • example3: agenda://x-callback-url/get-identifier?title=Things%20to%20Try returns 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-project returns 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-note returns 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) or project (holding the project identifier), project-title (holding the project title)
    Examples
  • example: agenda://x-callback-url/get-selection returns 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) and note-title (holding the note title), or project (holding the project identifier) and project-title (holding the project title)
    Examples
  • example: agenda://x-callback-url/get-selection returns 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_content placeholder)
  • 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, or tiny, 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, or tiny, small, medium, large)
    Result
  • result parameter: note holding identifier, and note-title with 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-note command.

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

Note 2: If no date is provided Agenda looks for events with the given event-title on “Today”. Otherwise if either a date or start-date+end-date is given, Agenda looks for the first event that has the given event-title on the given day or in the given day range. The most precise way to link to an event is to provide both the event-title as well as the exact start_date of the event.

Note3: The text and title parameters also support the new text commands like \date(short) and \time as 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%2Fsuccess will open the url myapp://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%2Ferror will open the url myapp://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.

19 Likes

Example use cases

https://heyscottyj.com

1 Like

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:

agenda://x-callback-url/create-note?project-title=Scribbles&title=Test&text=blabla&date=2018-05-12

1 Like

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.

1 Like

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.

3 Likes

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: Agenda 4.0 Brings Support for File Attachments, Improved iOS Automation - MacStories

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.

2 Likes

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.

1 Like

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!

3 Likes

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

1 Like

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.

ScottyJ

2 Likes