Overview

Moloco Ads APIs are updated on a regular basis to keep up with the changing needs of our users. Some of the changes are backward compatible while others aren't. Given that some of the updates are inevitably backward incompatible, we bundle these changes into a new version to prevent any compatibility issues. You can find a list of available versions and the backward incompatible changes for each available version in the release notes. Backward compatible changes can be found in the change logs.

Release schedule

Our policy is to release a new version every 6 months. In the event that there are no breaking changes made during the 6 month period, new version release may be delayed another 6 months. The least recent version supported is deprecated every 6 months such that every version is supported for at least 12 months. See the release notes for the latest release timeline.

At the time the least recent version is deprecated, you may be at risk of losing important data from breaking changes, without having migrated to one of the later versions. Users at risk of being impacted by an upcoming version deprecation are notified by email well ahead of time.

How to specify API version

When making an API request, you must specify the API version you would like to use as in the following example.

curl https://api.moloco.cloud/cm/v1/campaigns \
  -H "Moloco-Cloud-Api-Version: v1.1" \

❗️
Important:
We strongly advise against specifying multiple API versions across a single organization. If you have multiple Moloco Ads API users in your organization, be sure that they are all using the same version.

When a version hasn't been specified, the system defaults to using the most recent version available. This means that you will be automatically using v1.5 when the available versions are v1.3, v1.4, and v1.5.

📘
Note for version migration:
During the 1 month period between new version release and oldest version deprecation, the newest version released won't be called as the latest available version by default when no version has been specified in the API request. This is to allow ample time for version migration, and prevent any unforeseen disruptions to service resulting from any breaking changes in the latest available version.
For example, v1.9 is still the default version for API requests without a version specified during the 1 month period between v1.10 release (March 1, 2026) and v1.8 deprecation (April 1, 2026).

Types of changes to the APIs

Breaking changes

Breaking changes require developer resources to maintain existing functionality. As these changes aren't backward compatible, they aren't applied immediately but are instead accumulated over a timeframe of at least 6 months before being released in a bundle as a new API version. All breaking changes are documented in the release notes. Breaking changes include but aren't limited to the following.

Removing or renaming a feature, property, method, or value of a property of the enum type.
Changing the field type (e.g., string to enum).
Changing the functionality of an endpoint (e.g., synchronous to asynchronous API, changes in default functionality, etc.)
Adding a new validation or updating an existing validation.
Adding additional required parameter(s) and/or changing parameter type from optional to required.
Adding a read/write property to a resource message.
Changing the API quota.
Changing the error code(s).

Non-breaking changes

Non-breaking changes are backward compatible. They are applied immediately to all available API versions at the time of release. All non-breaking changes are documented in the change logs. Non-breaking changes include but aren't limited to the following.

Adding a new resource or API endpoint.
Adding a new optional request property.
Adding a new property to the response (not the resource).
Adding a new value for a property of the enum type that is only used in the request.
Adding a new value for a property of the enum type to both the resource and response.

Note: On the client side, you must handle the new value for a property of the enum type that the API client isn't aware of (e.g., flag as an unknown value) and be sure to keep the same value when sending back to the server (e.g., update the API resource with PUT APIs).

Adding a new read-only property to the resource.
Changing the error message.