Skip to content
On this page

X-Callback-URLs to Capacities

INFO

X-Callback-URLs are a way to communicate with the desktop app. You are calling the app at specific URLs to perform actions or return specific information.

X-Callback-URLs must have the following structure:

capacities://x-callback-url/<action>?
  x-source=SourceApp&
  x-success=sourceapp://x-callback-url/response&
  x-error=sourceapp://x-callback-url/error

with required parameters:

  • <action>: action you want to perform (see below)
  • x-source: name of the app calling the action
  • x-success: URL to call if the action was successful (needs to be a deeplink URL to the calling application)
  • x-error: URL to call if the action failed (needs to be a deeplink URL to the calling application)

Error handling

If an error occurs, Capacities will call the x-error URL with the following parameters:

  • x-source: "Capacities"
  • error-code: the error code (404, 500, etc.)
  • error-message: a human readable error message

Testing

Run a X-Callback-Url like this in the Terminal:

bash
open "capacities://x-callback-url/createNewObject?x-source=SourceApp&x-success=sourceapp://x-callback-url/response&x-error=sourceapp://x-callback-url/error&title=My%20new%20object"

You can also simply paste the URL into the address bar of your browser.

Actions

getCurrentObject

Returns the object that is currently opened in Capacities. If there is no active object, the x-error URL will be called with the error code 501. Otherwise, the x-success URL will be called with the following parameters:

  • x-source: "Capacities"
  • url: deeplink url to the object
  • title: title of the active object (can be empty)

createNewObject

Opens the app and creates a new object based on the following parameters (all parameters need to be provided as query parameters):

  • spaceId (optional): If no spaceId is provided the current or last active space will be used.
  • type (optional): The type need to be the exact spelling of the singular name of your object type. If no type is provided a page will be created.
  • title (optional)
  • content (optional): Content needs to be provided in markdown format. It will be appended to the objects first blocks property (if available).

A simple example:

capacities://x-callback-url/createNewObject?x-source=SourceApp&x-success=sourceapp://x-callback-url/response&x-error=sourceapp://x-callback-url/error&title=My%20new%20object

If something fails, the x-error URL will be called with the error code 501. Otherwise, the x-success URL will be called with the following parameters:

  • x-source: "Capacities"
  • url: deeplink url to the object
  • title: title of the active object (can be empty)

appendToDailyNote

Opens the app and appends the provided content to today's daily note (all parameters need to be provided as query parameters):

  • spaceId (optional): If no spaceId is provided the current or last active space will be used.
  • content: Content needs to be provided in markdown format.

A simple example:

capacities://x-callback-url/appendToDailyNote?x-source=SourceApp&x-success=sourceapp://x-callback-url/response&x-error=sourceapp://x-callback-url/error&content=My%20content

If something fails, the x-error URL will be called with the error code 501. Otherwise, the x-success URL will be called with the following parameters:

  • x-source: "Capacities"
  • url: deeplink url to todays daily note

Built with ❤️ and ☕️ in 🇪🇺.