Migrating from 0.5 to 2.0 REST API

Overview

Buyer Cloud's Advertiser APIs exposes two REST API versions:

• 2.0 API (current) – the primary surface for all development, with consistent schemas, richer object models, and support for modern patterns like PATCH, bulk operations, and reference resources.
• 0.5 API (legacy) – maintained temporarily for backward compatibility while customers complete their migration to 2.0.

All 0.5 endpoints now have equivalents in the 2.0 API. New functionality and ongoing improvements are delivered only on 2.0. If your integration still calls 0.5 endpoints, you should plan a full transition to 2.0 and treat 0.5 as a legacy compatibility layer.

This guide explains how the two versions relate, what changes to expect when moving to 2.0, and how to migrate safely.

Compatibility

The 2.0 API is not backwards compatible with the 0.5 API. Paths, payloads, and filtering syntax differ, and some resources have been redesigned.

• For most Buzz objects, 2.0 preserves the intent of the 0.5 endpoints but introduces clearer schemas, more explicit validation, and improved error reporting.
• For some areas, such as targeting expressions and reporting, 2.0 represents a meaningful upgrade over the 0.5 design and adds capabilities that did not exist previously.

Every 0.5 endpoint has a corresponding 2.0 endpoint, though the path and payload shape may differ. When migrating, use the 2.0 reference documentation to identify the mapped endpoint and follow its specific guidelines.

Paths

The two APIs use different URL patterns:

• 0.5 API: /rest/[resource]
• 2.0 API:
  • Core resources: /rest/v2/[resource]
  • Reference and metadata resources: /rest/v2/ref/[resource]

Examples:

• 0.5 campaigns list: /rest/campaign
• 2.0 campaigns list: /rest/v2/campaigns
• 2.0 reference resources: /rest/v2/ref/operating-systems, /rest/v2/ref/metros, etc.

Authentication

Currently, both 0.5 and 2.0 APIs share the same cookie-based authentication model and session cookie. Once you authenticate, you can call either version with the resulting credentials.

• Authenticate using the Authentication guide in the API documentation.
• The authentication endpoint issues a Buzz session cookie that is valid for both /rest/... (0.5) and /rest/v2/... (2.0) requests.

Upcoming change: Credentials-based API authentication will be introduced in a future release. This will make it easier to:

• Authenticate non-interactive, machine-to-machine clients.
• Manage API credentials (creation, rotation, revocation) in a more modern way.

Those features and corresponding migration timelines will be documented as they become available. Credentials-based API authentication will replace the existing cookie-based model as the primary way to authenticate headless and service integrations.

Object Hierarchy

The fundamental Buzz object hierarchy remains the same across 0.5 and 2.0:

• Accounts contain advertisers.
• Advertisers contain campaigns.
• Campaigns contain line items.
• Line items reference creatives, segments, targeting, and reporting.

The 2.0 API exposes the same core objects but updates their schemas and adds new derived resources (for example, targeting expressions and reporting views).

API Syntax

The largest differences between 0.5 and 2.0 are in request/response syntax and filtering.

Key changes in 2.0:

• Filtering syntax – 2.0 uses a standardized double-underscore operator pattern on query parameters.
  • Example: to filter records where id is greater than or equal to 2, use id__gte=2 on the GET request.
  • Common operators include __eq, __in, __gte, __lte, and date/time operators, as documented in the "Getting Data from the API" guide.
• Views and reference resources – rather than multi-purpose views on primary resources, 2.0 exposes separate endpoints under /rest/v2/ref/ (and other namespaces) for reference data and lookup tables.
• HTTP semantics – 2.0 formalizes how GET, POST, PUT, PATCH, DELETE, and OPTIONS behave across resources:
  • GET – request parameters are passed as URL query parameters rather than in the HTTP payload.
  • POST – creates new objects; supports richer validation and improved error messages.
  • PUT / DELETE – operate on a specific resource identified by its id in the URL path (for example, /rest/v2/line-items/{id}), not by id in the JSON body.
  • PATCH – supports partial updates and flexible bulk operations.
  • OPTIONS – describes supported methods, fields, and constraints for a resource.

For detailed examples, see the core syntax guides:

• Getting data from the API
• Creating objects with POST
• PUT-ing objects with the API
• DELETE-ing objects with the API
• OPTIONS to understand resources

Bulk Actions

Bulk operations are more consistent and powerful in 2.0 than in 0.5.

Improvements include:

• Bulk creation – many resources now support bulk object creation via POST, allowing you to create multiple objects in a single request.
• Resource-specific bulk endpoints – each object type exposes dedicated bulk endpoints instead of sharing generic bulk methods.
• PATCH for bulk updates – 2.0 allows:
  • Different changes per object within a single PATCH payload.
  • The same change applied across many objects in one request.

These patterns reduce the number of calls required for large updates and make bulk workflows more predictable.

Quick Guide: 0.5 vs 2.0 APIs

Authentication

• 0.5 and 2.0 currently share the same cookie-based authentication model and session cookie.
• You can authenticate once and call both versions in the same session.
• New integrations and migrations should follow the 2.0 Authentication documentation.
• Credentials-based API authentication will be introduced in coming months; once available, you can adopt it alongside your existing 2.0 endpoints.

Paths

• 0.5: /rest/[resource]
• 2.0:
  • Core objects: /rest/v2/[resource]
  • Reference data: /rest/v2/ref/[resource]

Filtering

• 0.5: ad hoc filtering patterns that vary by endpoint.
• 2.0: standardized double-underscore operators appended to field names, such as id__gte=2, status__in=active,paused.

Views and Reference Data

• 0.5: views provided alternate field sets under primary resources.
• 2.0: views are replaced by explicit reference and helper endpoints under /rest/v2/ref/... and related paths.

Multi-Account Usage

• 0.5: multi-account users often used account_id=any patterns.
• 2.0: multi-account users can use parameters like all_accounts=true where supported to query across all accessible accounts.

HTTP Methods

• GET – variables passed as query parameters, not request body.
• POST – used for creation; 2.0 adds better errors and often supports bulk creation.
• PUT / DELETE – require the target resource id in the URL path.
• PATCH – available only on 2.0; supports partial updates and bulk operations.
• OPTIONS – available only on 2.0; returns metadata about supported methods and fields for a resource.

Targeting

• 0.5: targeting templates.
• 2.0: targeting expressions, a more flexible and expressive resource that replaces 0.5 templates.

Reporting

• 0.5: legacy reporting endpoints.
• 2.0: redesigned reporting resources with more powerful querying, improved parameterization, and better alignment with modern analytics use cases.

Migration Recommendations

• Treat 2.0 as the primary API for all development and system integrations.
• For existing integrations, inventory the 0.5 endpoints you are using and identify the corresponding 2.0 endpoints in the API reference.
• Migrate each call from /rest/[resource] to its /rest/v2/[resource] or /rest/v2/ref/[resource] equivalent, updating parameters, payloads, and filtering to match the 2.0 syntax.
• Use the 2.0 filtering and reference patterns as the default for all new work.
• Keep any remaining 0.5 usage scoped to legacy code paths and plan to retire it once your migration is complete.

Following these guidelines will let you take advantage of the 2.0 API’s consistency and capabilities while maintaining continuity for existing workloads during the transition and positioning your integration for upcoming credentials-based API authentication.