Product Media API

Learn how to manage product media in AchieveApex using the REST API.

Overview

The Product Media API allows you to manage images and other media files for your products. You can list, retrieve, upload, update, and delete product media items.

Base Endpoint

/product-media

Product Media Object

The product media object contains information about a media file associated with a product.

Product Media Object

{
  "id": 456,
  "product_id": 123,
  "organization_id": 27,
  "file_name": "product-123-image.jpg",
  "file_type": "image/jpeg",
  "file_size": 245678,
  "file_path": "/products/123/images/product-123-image.jpg",
  "s3_key": "org-27/products/123/product-123-image.jpg",
  "s3_path": "https://achieveapex-storage.s3.amazonaws.com/org-27/products/123/product-123-image.jpg",
  "position": 1,
  "created_at": "2025-03-21T17:19:38.391Z",
  "updated_at": "2025-03-21T17:19:38.391Z",
  "deleted_at": null
}

List Product Media

Retrieve a list of media files for a specific product with optional filtering and pagination.

Request

GET /product-media

curl -X GET https://api.achieveapex.com/product-media \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "organization_id": 27,
      "product_id": 123,
      "$limit": 10,
      "$skip": 0,
      "$sort": { "position": 1 }
    }
  }'

Response

{
  "total": 3,
  "limit": 10,
  "skip": 0,
  "data": [
    {
      "id": 456,
      "product_id": 123,
      "organization_id": 27,
      "file_name": "product-123-front.jpg",
      "file_type": "image/jpeg",
      "file_size": 245678,
      "file_path": "/products/123/images/product-123-front.jpg",
      "s3_key": "org-27/products/123/product-123-front.jpg",
      "s3_path": "https://achieveapex-storage.s3.amazonaws.com/org-27/products/123/product-123-front.jpg",
      "position": 1,
      "created_at": "2025-03-21T17:19:38.391Z",
      "updated_at": "2025-03-21T17:19:38.391Z",
      "deleted_at": null
    },
    {
      "id": 457,
      "product_id": 123,
      "organization_id": 27,
      "file_name": "product-123-side.jpg",
      "file_type": "image/jpeg",
      "file_size": 232145,
      "file_path": "/products/123/images/product-123-side.jpg",
      "s3_key": "org-27/products/123/product-123-side.jpg",
      "s3_path": "https://achieveapex-storage.s3.amazonaws.com/org-27/products/123/product-123-side.jpg",
      "position": 2,
      "created_at": "2025-03-21T17:20:38.391Z",
      "updated_at": "2025-03-21T17:20:38.391Z",
      "deleted_at": null
    },
    {
      "id": 458,
      "product_id": 123,
      "organization_id": 27,
      "file_name": "product-123-back.jpg",
      "file_type": "image/jpeg",
      "file_size": 238921,
      "file_path": "/products/123/images/product-123-back.jpg",
      "s3_key": "org-27/products/123/product-123-back.jpg",
      "s3_path": "https://achieveapex-storage.s3.amazonaws.com/org-27/products/123/product-123-back.jpg",
      "position": 3,
      "created_at": "2025-03-21T17:21:38.391Z",
      "updated_at": "2025-03-21T17:21:38.391Z",
      "deleted_at": null
    }
  ]
}

Query Parameters

Parameter	Type	Description
organization_id	Number	ID of the organization (required)
product_id	Number	ID of the product to fetch media for
file_type	String	Filter by file type (e.g., "image/jpeg", "image/png")
$limit	Number	Number of media items to return (default: 10)
$skip	Number	Number of media items to skip (for pagination)
$sort	Object	Sort criteria (e.g., `{ "position": 1 }` for position ascending)

Get a Product Media Item

Retrieve a single product media item by ID.

Request

GET /product-media/:id

curl -X GET https://api.achieveapex.com/product-media/456 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Response

{
  "id": 456,
  "product_id": 123,
  "organization_id": 27,
  "file_name": "product-123-front.jpg",
  "file_type": "image/jpeg",
  "file_size": 245678,
  "file_path": "/products/123/images/product-123-front.jpg",
  "s3_key": "org-27/products/123/product-123-front.jpg",
  "s3_path": "https://achieveapex-storage.s3.amazonaws.com/org-27/products/123/product-123-front.jpg",
  "position": 1,
  "created_at": "2025-03-21T17:19:38.391Z",
  "updated_at": "2025-03-21T17:19:38.391Z",
  "deleted_at": null,
  "product": {
    "id": 123,
    "name": "Premium Subscription"
  }
}

Upload Product Media

Upload a new media file for a product.

Request

POST /product-media

curl -X POST https://api.achieveapex.com/product-media \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "organization_id=27" \
  -F "product_id=123" \
  -F "position=4" \
  -F "file=@/path/to/product-123-detail.jpg"

Response

{
  "id": 459,
  "product_id": 123,
  "organization_id": 27,
  "file_name": "product-123-detail.jpg",
  "file_type": "image/jpeg",
  "file_size": 256432,
  "file_path": "/products/123/images/product-123-detail.jpg",
  "s3_key": "org-27/products/123/product-123-detail.jpg",
  "s3_path": "https://achieveapex-storage.s3.amazonaws.com/org-27/products/123/product-123-detail.jpg",
  "position": 4,
  "created_at": "2025-03-22T14:30:25.142Z",
  "updated_at": "2025-03-22T14:30:25.142Z",
  "deleted_at": null
}

Update Product Media

Update an existing product media item's information.

Request

PATCH /product-media/:id

curl -X PATCH https://api.achieveapex.com/product-media/459 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "position": 2
  }'

Response

{
  "id": 459,
  "product_id": 123,
  "organization_id": 27,
  "file_name": "product-123-detail.jpg",
  "file_type": "image/jpeg",
  "file_size": 256432,
  "file_path": "/products/123/images/product-123-detail.jpg",
  "s3_key": "org-27/products/123/product-123-detail.jpg",
  "s3_path": "https://achieveapex-storage.s3.amazonaws.com/org-27/products/123/product-123-detail.jpg",
  "position": 2,
  "created_at": "2025-03-22T14:30:25.142Z",
  "updated_at": "2025-03-22T14:45:12.215Z",
  "deleted_at": null
}

Reorder Product Media

Update the display position of multiple product media items in a single request.

Request

POST /product-media/reorder

curl -X POST https://api.achieveapex.com/product-media/reorder \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 27,
    "product_id": 123,
    "positions": [
      { "id": 459, "position": 1 },
      { "id": 456, "position": 2 },
      { "id": 457, "position": 3 },
      { "id": 458, "position": 4 }
    ]
  }'

Response

{
  "success": true,
  "updated": 4
}

Delete Product Media

Delete a product media item.

Request

DELETE /product-media/:id

curl -X DELETE https://api.achieveapex.com/product-media/459 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

{
  "id": 459,
  "product_id": 123,
  "organization_id": 27,
  "file_name": "product-123-detail.jpg",
  "file_type": "image/jpeg",
  "file_size": 256432,
  "file_path": "/products/123/images/product-123-detail.jpg",
  "s3_key": "org-27/products/123/product-123-detail.jpg",
  "s3_path": "https://achieveapex-storage.s3.amazonaws.com/org-27/products/123/product-123-detail.jpg",
  "position": 1,
  "created_at": "2025-03-22T14:30:25.142Z",
  "updated_at": "2025-03-22T15:10:33.789Z",
  "deleted_at": "2025-03-22T15:10:33.789Z"
}

Note on File Storage

When a media item is deleted, the system performs a soft delete by setting the deleted_at timestamp. The actual media files in S3 storage will be scheduled for removal after a grace period.

Report an issue with this documentation

Please log in to report issues with our documentation.