Introduction

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 REST API, and uses standard HTTP authentication.

Enabling the API

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:

1. Open the deployment in the Data Browser

2. 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.

Authentication

API authentication uses either a Named Token specified in the HTTP Authorization header, or using HTTP Basic Authentication.

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.

HTTP Endpoints

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 Enabling the API section above).

Base URLs have the following structure:

Current structure

For deployments created after 31 January 2023, the following structure applies:

https://{app-deployment-id}.backend.{region-code}.journeyapps.com/api/v4/{backend-deployment-id}

Deployment IDs

Note that deployments are identified by different IDs in the app (OXIDE), backend and CloudCode. The Backend API typically uses the backend deployment ID.

Example:

https://62d541f4156bc4dd685318da.backend.us.journeyapps.com/api/v4/62d541ff9f54b7000706c585

Legacy structure

For deployments created before 31 January 2023, the legacy structure applies:

https://run{deployment-environment-and-region-code}.journeyapps.com/api/v4/{backend-deployment-id}

Examples:

Testing environment:

https://run-testing-us.journeyapps.com/api/v4/615ae1ee8c5ef500078a4908

Production environment:

https://run-us.journeyapps.com/api/v4/615ae1ee8c5ef500078a4908

In this legacy structure, the {deployment-environment-and-region-code} placeholder of the base URL is constructed per deployment region and environment as follows:

Region	Environment	Base URL snippet
United States	Testing	https://run-testing-us.journeyapps.com
	Staging	https://run-staging-us.journeyapps.com
	Production	https://run-us.journeyapps.com
Europe	Testing	https://run-testing-eu.journeyapps.com
	Staging	https://run-staging-eu.journeyapps.com
	Production	https://run-eu.journeyapps.com
Australia	Testing	https://run-testing-au.journeyapps.com
	Staging	https://run-staging-au.journeyapps.com
	Production	https://run-au.journeyapps.com
South Africa (Deprecated)	Testing	https://run-testing.journeyapps.com
	Staging	https://run-staging.journeyapps.com
	Production	https://run.journeyapps.com

Base URL and Relative URL

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. Retrieve all Objects, Create a New Object, Update a Single Object, etc).

For example, in the Create a New Object section, we indicate that you need to send an HTTP POST request to the relative URL /api/v4/backend-deployment-id/objects/model.json

In order to create an object. In other words, let's say your deployment's backend ID is 54c89f71923a3be4fe00000f and you want to create a new 'car' object in in this deployment (which is in the United States region), you'll send an HTTP request to:

https://62d541f4156bc4dd685318da.backend.us.journeyapps.com/api/v4/54c89f71923a3be4fe00000f/objects/car.json

Request Parameter Formats

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.

Format	Content-Type Header	Example
JSON	application/json	{"client":{"address":"123 South"}}
URL-encoded key-value pairs	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

How do I format fields?

For details on how to format the object fields that you send to the API, please see the Field Representation section:

Field Representation

Response Data Formats

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

• 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 HTTP Endpoints above to get the value for the BASE-URL placeholder.

In what format will my fields be returned?

For details on how your object fields received from the API will be formatted, please see the Field Representation section.

Field Representation

Error Handling

Response Codes

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.

Full details on error responses are described on the Error Responses page:

Error Responses

API Stability

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:

1. Publish it as part of a new API version, e.g. API v5.

2. Place it behind a feature flag, that is enabled on request for specific apps.

3. 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.

Beta APIs

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.