API integrations allow you to connect PXM with external systems such as ERPs, ecommerce platforms, or custom applications. Instead of manually updating data, APIs enable systems to communicate automatically -- saving time, reducing errors, and keeping your product content in sync.

The PXM API is a RESTful HTTP API using JSON for request and response bodies. It supports operations on collections (products), files (digital assets), categories (navigation folders), attributes (metadata fields), and more.

Base URL: https://entapi.amplifi.io

Most API endpoints are versioned under /v2.1/. The search endpoints also support /v2/ and /v3/. See the API Reference below for details.

Understanding how PXM objects relate to each other is essential before building any integration.

Basic PXM Hierarchy

Categories organize collections (products) into folder structures for navigation. Files are media assets linked to collections. A collection can be associated with one or more categories depending on its parent/direct_parent configuration. Files can also be associated with multiple collections.

Product Variant Hierarchy

The variant hierarchy is separate from the category hierarchy. collection_type designates whether a collection is a parent or variant. parent_topic_id links each variant back to its parent collection. A standalone product omits collection_type entirely.

Full Account Structure

A Collection is the core product record. It can stand alone, act as a parent (product family), or be a variant (a specific SKU). Collections are placed inside Categories for navigation, linked to Files for media, and carry Attribute values for product data.

Key relationship fields and what they do:

Before building your integration, be aware of the following known behaviors. They are not bugs -- they are characteristics of the API that every integration needs to handle:

Response shapes are not uniform across endpoints. Some list endpoints return a raw JSON array. Others wrap results in a keyed object. Your code must handle both. See the Response Format Variations section below.

The Swagger documentation and actual runtime behavior sometimes differ. Some fields marked readOnly in the spec are writable in practice. Test against the live API when in doubt.

PUT requests fully replace array fields. If you PUT collections with one ID, all previously linked collections are removed. Always GET first, merge, then PUT. See Understanding PUT Behavior below.

Access tokens are long-lived (1 year). This is unusual for OAuth. Store tokens securely and treat them like passwords.

Before using the API, you'll need:

1. A PXM account with API access enabled

2. A Client ID and Client Secret (generated in PXM settings)

3. Basic understanding of REST APIs and JSON

To generate your API credentials in PXM:

1. Log in to PXM and navigate to Settings

2. Go to Integrations → API

3. Click Create New Integration

4. Give your integration a name and save

5. You may now use the Client ID and Client Secret

6. The Client ID and Client Secret are tied to the individual user. Deactivation of the user will deactivate the Client ID and Client Secret.

The PXM API uses the OAuth 2.0 Client Credentials flow. You exchange your Client ID and Client Secret for a Bearer token included on every subsequent API request.

Endpoint: POST https://entapi.amplifi.io/v2.1/oauth/authorize

Headers:

Request Body:

Python Example (Option A -- recommended):

Python Example (Option B -- manual Base64):

Response:

The expires_in value is 31,536,000 seconds (1 year). Tokens are long-lived -- cache and reuse them rather than generating a new one per request.

Include the token on every API call:

Token Security

* Treat your token like a password -- never expose it in client-side code, logs, or version control

* Store it in environment variables or a secrets manager (e.g., AWS Secrets Manager, HashiCorp Vault)

* Rotate tokens proactively before expiry rather than waiting for them to expire in production

* If a token is compromised, revoke it from PXM Settings immediately and generate a new one

The full interactive API documentation (Swagger UI) is available at:

https://entapi.amplifi.io/docs/index.html

Note: The Swagger spec is a useful reference for endpoint structure and field names, but some runtime behaviors differ -- for example, some fields marked readOnly are writable in practice. Treat it as a starting point and validate against the live API when in doubt.

Different endpoints return data in different shapes. Do not assume every endpoint returns the same wrapper format -- inspect each endpoint's documented response shape and write your parser accordingly.

GET /v2.1/category -- returns a raw JSON array:

GET /v2.1/collection -- returns an object with a collections key:

GET /v2.1/file -- returns a raw JSON array:

GET /v3/folder/search -- returns an object with hits and total:

Defensive pagination helper (handles all response shapes):

All endpoints use https://entapi.amplifi.io as the base URL. Most are versioned at /v2.1/. Include your Bearer token in every request.

Categories are folder structures used to organize collections and files in PXM. They support nested hierarchies.

To create a category, only name is required. Use parent_id to nest it inside another category.

Collections are product records in PXM. They hold attribute values, linked files, and product metadata. A collection can be a standalone product, a parent (product family), or a variant (specific SKU).

List Parameters (GET /v2.1/collection)

CREATING a Collection -- POST /v2.1/collection

Only name is required. All other fields are optional on create.

To create a parent collection (product family):

To create a variant linked to a parent:

UPDATING a Collection -- PUT /v2.1/collection/{id}

Only include the fields you want to change. You do not need to send the full object.

⚠️ Array fields are fully replaced: direct_parent and attributes replace their entire previous values on every PUT. Always GET the current state first, merge your changes, and then PUT the full merged value.

Collection Fields Reference

Files are digital assets -- images, PDFs, videos, and other media -- stored in PXM's Digital Asset Manager (DAM). Files are uploaded via a presigned URL flow and can be linked to one or more collections.

List Parameters (GET /v2.1/file)

File Upload Lifecycle

Uploading a file to PXM is a multi-step process:

1. Request Upload -- Call POST /v2.1/file/request-upload to get a presigned S3 URL

Note: Send both filename and file_name for compatibility across tenant configurations.

2. Check Upload Type -- The response includes upload_type: either standard (single PUT) or multipart (multiple parts for large files)

3. Upload to S3 (Single) -- If upload_type == "standard", PUT the file bytes directly to the presigned URL

4. Upload to S3 (Multipart) -- If upload_type == "multipart": upload each part to its presigned URL, capture the ETag header from each response, then confirm with the upload_id and array of parts

5. Confirm Upload -- Call POST /v2.1/file/confirm-upload to register the file in PXM:

🌍 region_ids: Include the region UUID(s) where this file should be available. Use GET /v2.1/region to get your region IDs. If omitted, the file goes into the account's default primary region.

6. Processing -- PXM processes the file asynchronously (OCR, auto-labeling via Google Vision)

7. Available -- File is available via GET /v2.1/file/{id} and can be linked to collections

Confirm Upload for Multipart

Updating a File

Use PUT /v2.1/file/{id} to update file metadata. Like collections, array fields are fully replaced:

Link a file to collections:

Update region access on a file:

region_ids: Include region UUIDs to scope access. Omit to use the account default region. This is a full replace -- GET first and merge if needed.

File Response Fields

Attributes are metadata fields that can be attached to collections, files, or categories. Global attributes are defined at the account level and assigned to objects.

Attribute types supported: Text, Date, List, Pick List, Boolean, Number

To update attributes via collection PUT, include them in the attributes array. Each entry requires an id and a type:

Attribute groups organize related attributes into named sections on a collection. They are display-only groupings and do not affect API calls to individual attributes.

Search endpoints allow full-text keyword search across folders (collections) and files.

Entity can be folder or file.

v3 Response Shape:

Regions define localization scopes in PXM. Files and collections can be scoped to specific regions for multi-market deployments.

Note: In the PXM platform UI, Regions are also referred to as Org Units. The terms are interchangeable -- the API uses region_ids, but you may see "Org Unit" in the platform settings.

Use GET /v2.1/region to retrieve all region IDs for your account. The primary region has is_primary: true. When you include region_ids on a file or collection, it scopes that content to those specific regions. If you omit region_ids, content defaults to the account's primary/default region.

Always GET before PUT on array fields -- collections, direct_parent, and region_ids are fully replaced on every PUT. Merge existing values with your updates before writing.

Resources are URL-based references -- spec sheets, external documents, or links -- that can be attached to categories or collections.

Required: description, link

All list endpoints support limit and offset for pagination. The default limit is typically 20. Fetch the next page by incrementing offset by limit. Stop when the returned count is less than limit.

The same limit/offset approach works for /v2.1/file, /v2.1/category, and other list endpoints.

The PXM API uses PUT for updates -- not PATCH. This has an important implication for array fields: sending a partial array replaces the entire array, not just the items you specify.

Fields affected by full-replacement:

* collections on a file

* direct_parent on a collection

* region_ids on a file or collection

* attributes on a collection (when passed as an array)

Safe update pattern:

Rate Limiting

The PXM API allows 1,000 requests per 60 seconds. When you exceed this limit, you'll receive a 429 Too Many Requests response:

For bulk operations, target 950 requests per 60 seconds to stay safely under the limit.

Retry Logic

Delta Sync Pattern

Rather than re-fetching all data on every sync, use date filters to fetch only changed records:

Concurrency with Rate Limiting (Python asyncio)

Token Caching

PXM tokens are valid for 1 year. Avoid requesting a new token on every script run:

The PXM API has an interactive Swagger UI available at https://entapi.amplifi.io/docs/index.html. It is a useful starting point for endpoint discovery and field reference, but there are a few things to be aware of when using it for integration work.

This article reflects practical, tested behavior. Where Swagger and this documentation differ, follow this article.

* Always GET before PUT on array fields -- collections, direct_parent, and region_ids are fully replaced on every PUT. Merge existing values with your updates before writing.

* Handle response shapes defensively -- Use the defensive parsing pattern in the Response Format Variations section. Do not assume all list endpoints return the same JSON structure.

* Validate payloads before sending -- Several issues in integrations come from incorrect data values, not platform bugs. Test against the API schema before scaling up.

* Respect rate limits -- Target 950 requests/60s to leave a buffer. Implement retry logic with exponential backoff for 429s.

* Cache your token -- Tokens last 1 year. There is no need to request a new one on every run.

* Use delta syncs -- Use updated_start_date / updated_end_date filters on list endpoints to fetch only changed records rather than pulling everything every time.

* Test in a sandbox first -- Run bulk write operations on a small batch before scaling to your full catalog. Confirm the behavior matches expectations before processing thousands of records.

If you run into issues with the API or need help with a specific integration, reach out to your Customer Success Manager or contact PXM Support through the in-app chat.