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 actionx-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:
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 objecttitle
: 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 content 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 objecttitle
: title of the active object (can be empty)