Introduction
Last updated
Last updated
The JourneyApps API allows you to integrate or "sync" your own databases or systems with your JourneyApps application. In other words, it allows you to connect one of your own systems to your app in a way that the two can "talk" to each other behind the scenes.
On a technical level, the API takes the form of an HTTP API, and uses standard HTTP authentication.
The API is configured on an App Deployment level, which means that each deployment of your app (you can see each deployment listed in the Deployments workspace or panel in OXIDE) has its own API credentials.
To obtain the API credentials for a specific App Deployment:
Open the deployment in the Data Browser
Open the dropdown in the top right corner, and click on Manage API. If this option is not immediately visible, you may need to elevate your permissions.
On the Manage API page, you'll be able to see the deployment's HTTP Basic Username and Password or create Named Tokens. Please keep this information private and record it in a secure place.
API authentication uses either a Named Token specified in the HTTP Authorization header, or using .
The syntax for the Named Token header is Authorization: Bearer O:mytokenhere.
All API requests must occur over HTTPS and each request must include authentication credentials.
An endpoint is the base URL that you connect to when using the API.
These base URLs are dynamic for each of your app's deployments, and can be reviewed on the Manage API data browser page for your deployment (see steps to access this page in the section above).
Base URLs have the following structure:
Parameters supplied to API functions may be in any of the following formats. It may be necessary to set the Content-Type HTTP header as shown.
application/json
{"client":{"address":"123 South"}}
application/x-www-form-urlencoded
This is the default for POST requests and usually does not have to be specified explicitly.
client[address]=123%20South
All v4 API responses are in currently in JSON. It is however still recommended that you indicate the acceptance of JSON by either:
Setting the Accept HTTP header to application/json
The API uses standard HTTP status codes to indicate the outcome of an API request.
A status code in the 2xx range indicates that the operation has completed successfully.
A status code in the 3xx range indicates a redirect. This is only used for specific calls, for example for fetching attachments.
Any other status code indicates that the operation has failed:
A status code in the 4xx range indicates that invalid input from your side is responsible for the error.
A status code in the 5xx range indicates that an internal server error on the JourneyApps side is responsible for the error.
No breaking changes will be made to an existing stable API version. If we do need to make a breaking change, we will do one of:
Publish it as part of a new API version, e.g. API v5.
Place it behind a feature flag, that is enabled on request for specific apps.
Give sufficient notice in the rare case that a change to an existing API cannot be avoided.
Note that we will periodically add new API calls to an existing API version, as well as new fields or HTTP headers to API responses. This is not considered a breaking change, and API clients must ignore any unrecognized fields.
Removing, renaming or changing the type or behavior of an existing API call or field is considered a breaking change, and the above breaking change policy will apply.
Certain APIs, such as the api.journeyapps.com, may be classified as "Beta". In this case, we may make breaking changes or even completely remove or replace the API, but will strive to give sufficient notice in such cases.
Throughout the rest of the documentation, we will indicate the URL that you need to use relative to the base URL to perform a particular function (e.g. , , , etc).
For example, in the section, we indicate that you need to send an HTTP POST request to the relative URL /api/v4/backend-deployment-id/objects/model.json
key-value pairs
For details on how to format the object fields that you send to the API, please see the section:
By appending .json to the end of the URL. For example: BASE-URL/api/v4/backend-deployment-id/objects/assets.json. Note: See the section about above to get the value for the BASE-URL placeholder.
For details on how your object fields received from the API will be formatted, please see the section.
Full details on error responses are described on the page: