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

General guidelines

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)

and optional parameters:

• 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)

If you want to receive the result of the action, you need to provide a x-success and x-error URL.

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:

open "capacities://x-callback-url/createNewObject?name=Test"

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

Open an existing object

Opening an object is not an X-Callback action. Use a deep link:

capacities://{spaceId}/{objectId}

Both spaceId and objectId are required. The object ID alone is not enough.

After creating an object via the API or MCP, build this URL from the returned IDs. createNewObject with x-success already returns a url that is this deep link.

The same path works on the web as https://app.capacities.io/{spaceId}/{objectId}. This matches the format from Copy object reference in the app.

Actions

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): title of the object (can be empty)
• content (optional): Content needs to be provided in markdown format. It will be appended to the object's first Content property (if available).

Example:

capacities://x-callback-url/createNewObject?name=My%20new%20object

capacities://x-callback-url/createNewObject?name=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.

Example:

capacities://x-callback-url/appendToDailyNote?content=My%20content

capacities://x-callback-url/appendToDailyNote?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

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)
• name: title of the active object (can be empty)

Example:

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