> ## Documentation Index > Fetch the complete documentation index at: https://docs.aiderx.io/llms.txt > Use this file to discover all available pages before exploring further. # Product and Content Data Integration > Register product and content data in A2, keep it up to date, and connect user activity using consistent item IDs. Register the names, images, and categories of your service's products or content in A2 and keep them up to date. A2 manages this list as a **Catalog**. The registered data is used for recommendations, and when you send user activity logs, such as views and purchases, with the same item IDs, it is also used for recommendations that reflect user activity. The Catalog API is a Data Management API, so it requires an access token. See [API Access and Authentication](https://docs.aiderx.io/development/en/api-access-and-auth.md) to issue one. ## Prepare data and IDs The item ID links a Catalog item to user activity logs. Using the product or content IDs from your service as they are lets you connect data without conversion. Item IDs must be unique across the A2 environment and can't be changed after registration. If several data sources use the same IDs, make them distinct before registering, for example with a per-source prefix. Put the item ID in `id` and the same value in `metadata.id`. Use `metadata` for the product data you need, such as its name, image, and category. For field details, see [Create a catalog item]() in API Reference. ## Register and look up items ### Register ```bash theme={null} curl -X POST "https://your_a2_service/api/manager/catalogs" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "id": "1001", "schema": "creative.catalog", "status": "active", "metadata": { "id": "1001", "title": "Daily Running Shoes", "thumbnail": "https://cdn.example.com/items/1001.jpg", "link": "https://shop.example.com/products/1001", "category": "Shoes", "brand": "Example", "ext": {"price": 89000} } }' ``` On success, the API returns `201` with the registered item. If an item with the same ID exists, it returns `409` and leaves the existing item unchanged. A field in the wrong format returns `422`. ### Look up Read a single item to check the stored values. ```bash theme={null} curl "https://your_a2_service/api/manager/catalogs/1001" \ -H "Authorization: Bearer " ``` The list endpoint (`GET /api/manager/catalogs`) supports `keyword` (searches `title`), `category`, and `source`. It returns up to 100 items per page; use `page` and `page_size` to page through results. For details, see [List items]() in API Reference. > [!NOTE] > > Detailed specifications for single-item lookup and the batch create, update, and delete APIs are being updated. For now, use the request and response examples on this page. ## Apply changes When your service data changes, reflect it in the Catalog. Changes reach A2 features asynchronously, so they may not appear in results right away. | Service data change | Catalog action | | - | - | | New product | Register | | Product information changes | Update | | Product no longer used | Delete | ### Update Send only the fields you want to change. `metadata`, however, is replaced as a whole, so include the attributes you want to keep even when changing only some of them. ```bash theme={null} curl -X PATCH "https://your_a2_service/api/manager/catalogs/1001" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "metadata": { "id": "1001", "title": "Daily Running Shoes", "thumbnail": "https://cdn.example.com/items/1001.jpg", "link": "https://shop.example.com/products/1001", "category": "Shoes", "brand": "Example", "ext": {"price": 79000} } }' ``` To delete an item, send `DELETE /api/manager/catalogs/{catalog_id}`; a successful request returns `204`. For details, see [Update an item]() and [Delete an item]() in API Reference. ### Changing an ID An item ID can't be changed after registration. An item registered under a new ID is treated as a different item, and activity logs accumulated under the old ID aren't linked to it. Your service code and logs must switch to the new ID as well, so if you need to change an ID, agree on a migration approach with your integration contact first. ## Batch integration The batch APIs process up to 1,000 items per request. Each item is handled separately, so the rest are applied even if some fail; the response is HTTP `200` with the succeeded items (`succeeded`) and failed items (`failed`). If a request has more than 1,000 items or is malformed, the whole request is rejected with `422`. | Operation | Request | Body | | - | - | - | | Batch create | `POST /api/manager/catalogs/batch-create` | `items`: an array of items in the same form as a create request | | Batch update | `POST /api/manager/catalogs/batch-update` | `items`: an array of items with `id` and the fields to update | | Batch delete | `POST /api/manager/catalogs/batch-delete` | `ids`: an array of item IDs to delete | This example creates two items when `1002` is already registered. ```bash theme={null} curl -X POST "https://your_a2_service/api/manager/catalogs/batch-create" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "items": [ { "id": "1001", "schema": "creative.catalog", "status": "active", "metadata": {"id": "1001", "title": "Daily Running Shoes"} }, { "id": "1002", "schema": "creative.catalog", "status": "active", "metadata": {"id": "1002", "title": "Trail Running Shoes"} } ] }' ``` ```json Response theme={null} { "succeeded": [ { "id": "1001", "source": null, "status": "active", "schema": "creative.catalog", "metadata": {"id": "1001", "title": "Daily Running Shoes"}, "created_at": "2026-10-20T00:00:00Z", "updated_at": "2026-10-20T00:00:00Z" } ], "failed": [ {"id": "1002", "reason": "Already exists."} ] } ``` Match failed items to your source data by `failed[].id`. Batch update returns results in ID order, not request order, so don't rely on the order. For batch delete, `succeeded` contains the deleted item IDs. `failed[].reason` is a human-readable message, and no separate error code is currently provided. Its wording can change, so use it only to check why an item failed. Batch create doesn't overwrite existing items. For periodic syncs, send only the changed items: new items through batch create and existing items through batch update. Avoid deleting everything and registering it again. Deleting also removes the feature data extracted from the items, so re-registering doesn't immediately restore their previous state. ## Connect and verify activity data To use Catalog data for recommendations that reflect user activity, connect it to user activity logs. When you send activity logs such as views, add-to-cart events, and purchases, put the registered item ID in `catalogs[].id`. To send activity logs, see [Record Activity Log](https://docs.aiderx.io/en/0.5.0/decision/activity-log/record-activity-log.md) in API Reference. If you use recommendations, use the same item IDs in the recommendation request's `seed_item_id`, the response's `items[].catalog_id`, and the recommendation event log's `event_items`. Send item IDs as the same string in every request. For example, converting `"001001"` to a number drops the leading zeros, so it may not match the original item. After integrating, check the following: * Read a registered item and confirm that `metadata` was stored as intended. * Confirm that the item IDs in your activity logs are the same strings you registered. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.