API Versioning¶

CX Platform partner API endpoints are moving to explicit versioned URLs. For all new REST integrations, use the /cx/v2/ path prefix.

Current Version¶

The current public API version is v2.

Use this request pattern for partner API operations:

https://<environment-host>/cx/v2/<resource>

Example:

https://cx2-main.pit.cxgp.us/cx/v2/action/setCustomer

Why Versioning Matters¶

Versioned URLs let CX introduce future API revisions without breaking existing integrations.

Benefits for integrators:

Predictable behavior — Your integration can stay pinned to a known API version.
Safer upgrades — New versions can be introduced without forcing an immediate rewrite.
Clearer documentation — The version you see in examples matches the version you should call.

What You Should Call¶

Use case	Recommended path
New REST API integration	`/cx/v2/...`
Existing unversioned integration during rollout	Migrate to `/cx/v2/...`
Java SDK client configuration	Use the environment host only, for example `https://cx2-main.pit.cxgp.us`

Best practice

Even if an older unversioned request still works during rollout, update your integration to call /cx/v2/... explicitly.

Example Endpoint Changes¶

Before	After
`POST /cx/apikey`	`POST /cx/v2/apikey`
`POST /cx/action/setServiceLocation`	`POST /cx/v2/action/setServiceLocation`
`POST /cx/action/setCustomer`	`POST /cx/v2/action/setCustomer`
`GET /cx/serviceLocation`	`GET /cx/v2/serviceLocation`
`GET /cx/customer/{id}`	`GET /cx/v2/customer/{id}`

Request Outcomes by Version¶

Request pattern	Expected outcome
`/cx/v2/...`	Supported and recommended
`/cx/...`	Legacy form that should be migrated to `/cx/v2/...`
`/cx/v1/...`	Not supported
`/cx/v99/...`	Not supported

When a version is not supported, expect a 400 Bad Request response rather than assuming the request will be routed to another version.

REST Example¶

curl -X POST "https://cx2-main.pit.cxgp.us/cx/v2/action/setCustomer" \
  -H "CX-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "givenName": "Ol",
    "familyName": "Persson",
    "primaryEmail": {
      "value": "ol.persson@example.com"
    }
  }'

Java SDK Note¶

If you are using the Java SDK, do not append /cx/v2 to baseUrl().

Use the environment host only:

CxSdkClient client = new CxSdkClient.Builder()
    .apiKey(System.getenv("CX_API_KEY"))
    .baseUrl("https://cx2-main.pit.cxgp.us")
    .build();

The SDK configuration stays host-based, while REST API examples on this site use explicit versioned request paths.

Swagger UI and OpenAPI¶

Swagger UI and the published OpenAPI document continue to use their documented access URLs:

Swagger UI: /cx/oas/swagger-ui/index.html
OpenAPI JSON: /cx/oas/cx-oas.json

These documentation URLs are separate from the versioned partner API operation paths.

Migration Checklist¶

[ ] Update hard-coded REST URLs from /cx/... to /cx/v2/...
[ ] Keep the environment host configurable between PIT and Production
[ ] Re-test your integration in PIT before promoting to Production
[ ] Watch the Changelog for future version announcements