Struct Docs
Struct.PIM 4
Struct.PIM 4
  • Struct PIM Documentation
  • API Reference
  • Latest updates from Struct HQ
  • Latest updates in Documentation
  • Fundamental concepts
    • Get familiar with Struct PIM
    • Catalogues & categories
    • Products & variants
    • Attributes
    • Product structures
    • Identifiers
    • Global lists
    • Localization & segmentation
    • Revisions & changelog
    • Publications
    • Supplier onboarding portal
  • Tutorials
    • Helpful guides
      • How to search efficiently
      • How to use Import
        • How to import products
        • How to import data into a list property on entities
        • How to import categories
        • How to import with media
        • How to use File templates
    • Example projects
      • Working with the API
  • Integration
    • Integrate with Struct PIM
    • Web API
    • Webhooks
  • Media format
  • API Reference
    • Introduction
    • Endpoints
      • AssetFolders
      • Assets
      • AssetTypes
      • AttributeGroups
      • Attributes
      • AttributeScopes
      • Browse
      • BusinessUnits
      • Catalogues
      • Categories
      • Dimensions
      • Exports
      • EnrichmentInsightSetups
      • GlobalLists
      • Languages
      • Maintenance
      • Miscellaneous
      • Messaging
      • Permissions
      • Products
      • ProductStructures
      • Publications
      • Transactions
      • UserGroup
      • UserRoles
      • Users
      • VariantGroups
      • UserTasks
      • Variants
      • Webhooks
      • Workflows
      • Models
Powered by GitBook
On this page
  1. API Reference
  2. Endpoints

Assets

PreviousAssetFoldersNextAssetTypes

Assets are files that can be stored in the system and referenced on products, variants, categories and global list values. Assets uploaded to the system are assigned a URL based on the assets file name. Each image asset can be auto-scaled, cropped and formatted by adding parameters to the URL of the asset. Thus, you should only upload an image once in the highest quality you will need it and the system will take care of any scaling automatically. Assets are organized in folders, which can be nested within each other.

Get ids of all assets

get
Authorizations
Responses
200
OK
Responseinteger · int32[]
get
GET /v1/assets/ids HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*
200

OK

[
  1
]

Get an asset by its id

get
Authorizations
Path parameters
idinteger · int32Required

Id of asset

Responses
200
OK
400
Bad Request
404
Not Found
get
GET /v1/assets/{id} HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

{
  "Id": 1,
  "Uid": "123e4567-e89b-12d3-a456-426614174000",
  "CurrentFileVersion": 1,
  "Created": "2025-05-09T12:14:45.315Z",
  "LastModified": "2025-05-09T12:14:45.315Z",
  "CreatedBy": "text",
  "LastModifiedBy": "text",
  "AssetTypeUid": "123e4567-e89b-12d3-a456-426614174000",
  "IsPrivate": true,
  "FileSize": 1,
  "FileType": "text",
  "Extension": "text",
  "FileName": "text",
  "FolderUid": "123e4567-e89b-12d3-a456-426614174000",
  "FileUrl": "text",
  "CDNUrl": "text",
  "Tags": [
    "text"
  ],
  "BusinessUnits": [
    {
      "AccessPolicy": "text",
      "BusinessUnitUid": "123e4567-e89b-12d3-a456-426614174000"
    }
  ]
}

Delete an asset by its id

delete
Authorizations
Path parameters
idinteger · int32Required

Id of asset to delete

Responses
200
OK
400
Bad Request
delete
DELETE /v1/assets/{id} HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

No content

Get all file versions of an asset

get
Authorizations
Path parameters
idinteger · int32Required

Id of asset

Responses
200
OK
400
Bad Request
get
GET /v1/assets/{id}/fileversions HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

[
  {
    "Uid": "123e4567-e89b-12d3-a456-426614174000",
    "AssetUid": "123e4567-e89b-12d3-a456-426614174000",
    "AssetId": 1,
    "FileExtension": "text",
    "FileType": "text",
    "FileSize": 1,
    "FileName": "text",
    "FileUrl": "text",
    "Version": 1,
    "Created": "2025-05-09T12:14:45.315Z",
    "CreatedBy": "text"
  }
]

Get assets from page and page size. Assets are sorted by the created date.

get
Authorizations
Query parameters
pageinteger · int32Optional

Page

Default: 1
pageSizeinteger · int32Optional

Pagesize

Default: 100
Responses
200
OK
400
Bad Request
get
GET /v1/assets HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

{
  "Assets": [
    {
      "Id": 1,
      "Uid": "123e4567-e89b-12d3-a456-426614174000",
      "CurrentFileVersion": 1,
      "Created": "2025-05-09T12:14:45.315Z",
      "LastModified": "2025-05-09T12:14:45.315Z",
      "CreatedBy": "text",
      "LastModifiedBy": "text",
      "AssetTypeUid": "123e4567-e89b-12d3-a456-426614174000",
      "IsPrivate": true,
      "FileSize": 1,
      "FileType": "text",
      "Extension": "text",
      "FileName": "text",
      "FolderUid": "123e4567-e89b-12d3-a456-426614174000",
      "FileUrl": "text",
      "CDNUrl": "text",
      "Tags": [
        "text"
      ],
      "BusinessUnits": [
        {
          "AccessPolicy": "text",
          "BusinessUnitUid": "123e4567-e89b-12d3-a456-426614174000"
        }
      ]
    }
  ],
  "CurrentPage": 1,
  "PageSize": 1,
  "Total": 1
}

Create a new asset

post
Authorizations
Query parameters
assetTypeUidstring · uuidOptional

Uid of asset type

folderUidstring · uuidOptional

Uid of folder

Responses
201
Created
Responseinteger · int32
400
Bad Request
post
POST /v1/assets HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

1

Get assets from a folder by its uid

get
Authorizations
Path parameters
uidstring · uuidRequired

Uid of folder

Query parameters
pageinteger · int32Optional

Page

Default: 1
pageSizeinteger · int32Optional

Page size

Default: 100
Responses
200
OK
400
Bad Request
get
GET /v1/assets/folders/{uid}/assets HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

[
  {
    "Id": 1,
    "Uid": "123e4567-e89b-12d3-a456-426614174000",
    "CurrentFileVersion": 1,
    "Created": "2025-05-09T12:14:45.315Z",
    "LastModified": "2025-05-09T12:14:45.315Z",
    "CreatedBy": "text",
    "LastModifiedBy": "text",
    "AssetTypeUid": "123e4567-e89b-12d3-a456-426614174000",
    "IsPrivate": true,
    "FileSize": 1,
    "FileType": "text",
    "Extension": "text",
    "FileName": "text",
    "FolderUid": "123e4567-e89b-12d3-a456-426614174000",
    "FileUrl": "text",
    "CDNUrl": "text",
    "Tags": [
      "text"
    ],
    "BusinessUnits": [
      {
        "AccessPolicy": "text",
        "BusinessUnitUid": "123e4567-e89b-12d3-a456-426614174000"
      }
    ]
  }
]

Create a new version of an asset file

post
Authorizations
Path parameters
assetIdinteger · int32Required

Id of asset

Responses
200
OK
Responsestring · uuid
400
Bad Request
post
POST /v1/assets/{assetId}/fileversions HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

123e4567-e89b-12d3-a456-426614174000

Get attribute values for an asset

get
Authorizations
Path parameters
idinteger · int32Required

Id of asset

Query parameters
globalListValueReferencesOnlybooleanOptional

Indicate if only uids of referenced to global list values shall be returned instead of the materialized values

Default: false
Responses
200
OK
400
Bad Request
get
GET /v1/assets/{id}/attributevalues HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

{
  "AssetId": 1,
  "Values": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

Get enrichment insights for an asset

get
Authorizations
Path parameters
idinteger · int32Required

Id of asset

Responses
200
OK
400
Bad Request
get
GET /v1/assets/{id}/enrichmentinsights HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

[
  {
    "EnrichmentInsightSetupUid": "123e4567-e89b-12d3-a456-426614174000",
    "EntityId": 1,
    "Completeness": 1,
    "MissingData": [
      {
        "Type": "text",
        "DataReference": "text"
      }
    ],
    "Ignored": true
  }
]

Enable or disable an enrichment insight for an asset

patch
Authorizations
Path parameters
idinteger · int32Required

Id of asset

enrichmentInsightSetupUidstring · uuidRequired

Uid of enrichment insight to toggle ignore for

ignorebooleanRequired

Indicate whether to ignore the insight for the given enrichment insight and asset

Responses
200
OK
patch
PATCH /v1/assets/{id}/enrichmentinsights/{enrichmentInsightSetupUid}/{ignore} HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*
200

OK

No content

Get references to an asset

get
Authorizations
Path parameters
idinteger · int32Required

Id of asset

Responses
200
OK
400
Bad Request
get
GET /v1/assets/{id}/references HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

{
  "AssetId": 1,
  "ReferencingCategories": [
    {
      "EntityId": 1,
      "AttributeUid": "123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "ReferencingProducts": [
    {
      "EntityId": 1,
      "AttributeUid": "123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "ReferencingVariantGroups": [
    {
      "EntityId": 1,
      "AttributeUid": "123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "ReferencingVariants": [
    {
      "EntityId": 1,
      "AttributeUid": "123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "ReferencingAssets": [
    {
      "EntityId": 1,
      "AttributeUid": "123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "ReferencingGlobalListValues": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}

Get all available query fields for assets

get
Authorizations
Responses
200
OK
400
Bad Request
get
GET /v1/assets/queryablefields HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

[
  {
    "Uid": "text",
    "Name": "text",
    "SupportsSorting": true
  }
]
  • GETGet ids of all assets
  • GETGet an asset by its id
  • DELETEDelete an asset by its id
  • PATCHUpdate an assets data
  • POSTGet a list of assets by their ids (max 1000)
  • GETGet all file versions of an asset
  • POSTGet asset file versions for a list of assets
  • GETGet assets from page and page size. Assets are sorted by the created date.
  • POSTCreate a new asset
  • PATCHUpdate multiple assets' data
  • GETGet assets from a folder by its uid
  • POSTCreate a new version of an asset file
  • GETGet attribute values for an asset
  • POSTGet attribute values for multiple assets
  • GETGet enrichment insights for an asset
  • POSTGet enrichment insights for multiple assets
  • POSTGet insights for a batch of assets and a specific Enrichment Insight
  • PATCHEnable or disable an enrichment insight for an asset
  • PATCHEnable or disable an enrichment insight for a batch of assets
  • GETGet references to an asset
  • POSTGet references to a batch of assets
  • POSTGet ids of assets matching a certain criteria
  • POSTGet paged result of assets matching certain criteria. Result mapped with headers and item results
  • GETGet all available query fields for assets

Update an assets data

patch
Authorizations
Path parameters
idinteger · int32Required

Id of asset

Body

Model for updating an existing asset

AssetTypeUidstring · uuid | nullableOptional

The unique identifier of the asset type to change the asset to. This defines the asset's characteristics and available metadata fields.

FolderUidstring · uuid | nullableOptional

The unique identifier of the folder where the asset should be moved to.

WorkflowStateUidstring · uuid | nullableOptional

The unique identifier of the workflow state to move the asset to.

Tagsstring[] | nullableOptional

Collection of tags to replace the existing tags on the asset. Providing an empty list will remove all tags.

Responses
200
OK
400
Bad Request
patch
PATCH /v1/assets/{id} HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 327

{
  "AssetTypeUid": "123e4567-e89b-12d3-a456-426614174000",
  "FolderUid": "123e4567-e89b-12d3-a456-426614174000",
  "WorkflowStateUid": "123e4567-e89b-12d3-a456-426614174000",
  "Tags": [
    "text"
  ],
  "BusinessUnits": [
    {
      "AccessPolicy": "text",
      "BusinessUnitUid": "123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "Values": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}
No content

Get a list of assets by their ids (max 1000)

post
Authorizations
Body
integer · int32[]Optional
Responses
200
OK
400
Bad Request
post
POST /v1/assets/batch HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 3

[
  1
]
[
  {
    "Id": 1,
    "Uid": "123e4567-e89b-12d3-a456-426614174000",
    "CurrentFileVersion": 1,
    "Created": "2025-05-09T12:14:45.315Z",
    "LastModified": "2025-05-09T12:14:45.315Z",
    "CreatedBy": "text",
    "LastModifiedBy": "text",
    "AssetTypeUid": "123e4567-e89b-12d3-a456-426614174000",
    "IsPrivate": true,
    "FileSize": 1,
    "FileType": "text",
    "Extension": "text",
    "FileName": "text",
    "FolderUid": "123e4567-e89b-12d3-a456-426614174000",
    "FileUrl": "text",
    "CDNUrl": "text",
    "Tags": [
      "text"
    ],
    "BusinessUnits": [
      {
        "AccessPolicy": "text",
        "BusinessUnitUid": "123e4567-e89b-12d3-a456-426614174000"
      }
    ]
  }
]

Get asset file versions for a list of assets

post
Authorizations
Body
integer · int32[]Optional
Responses
200
OK
400
Bad Request
post
POST /v1/assets/batch/fileversions HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 3

[
  1
]
[
  {
    "Uid": "123e4567-e89b-12d3-a456-426614174000",
    "AssetUid": "123e4567-e89b-12d3-a456-426614174000",
    "AssetId": 1,
    "FileExtension": "text",
    "FileType": "text",
    "FileSize": 1,
    "FileName": "text",
    "FileUrl": "text",
    "Version": 1,
    "Created": "2025-05-09T12:14:45.315Z",
    "CreatedBy": "text"
  }
]

Update multiple assets' data

patch
Authorizations
Body

Update model for a batch of assets

AssetIdinteger · int32Optional

Uid of asset to update

Responses
200
OK
patch
PATCH /v1/assets HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 357

[
  {
    "AssetId": 1,
    "UpdateModel": {
      "AssetTypeUid": "123e4567-e89b-12d3-a456-426614174000",
      "FolderUid": "123e4567-e89b-12d3-a456-426614174000",
      "WorkflowStateUid": "123e4567-e89b-12d3-a456-426614174000",
      "Tags": [
        "text"
      ],
      "BusinessUnits": [
        {
          "AccessPolicy": "text",
          "BusinessUnitUid": "123e4567-e89b-12d3-a456-426614174000"
        }
      ],
      "Values": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  }
]
200

OK

No content

Get attribute values for multiple assets

post

No more than 5000 assets can be requested at a time.

Authorizations
Body

Define which assets to fetch data for and what data to fetch

AssetIdsinteger · int32[] | nullableOptional

Ids of assets to return

IncludeValuesinteger · enumOptional

Defines which attribute values to return

Possible values:
Scopesstring[] | nullableOptional

If IncludeValues is Scopes, define which scopes to return values for here

Aliasesstring[] | nullableOptional

If IncludeValues is Aliases, define aliases of the attributes to include values for

Uidsstring · uuid[] | nullableOptional

If IncludeValues is Uids, define uids of the attributes to include values for

LimitToCultureCodesstring[] | nullableOptional

Only return values for specific languages

LimitToSegmentsstring[] | nullableOptional

Only return values for specific dimension segments

GlobalListValueReferencesOnlybooleanOptional

Indicate if only uids of referenced to global list values shall be returned instead of the materialized values

FromTimestampstring · date-time | nullableOptional

Get attribute values back in time

Responses
200
OK
post
POST /v1/assets/batch/attributevalues HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 257

{
  "AssetIds": [
    1
  ],
  "IncludeValues": 1,
  "Scopes": [
    "text"
  ],
  "Aliases": [
    "text"
  ],
  "Uids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "LimitToCultureCodes": [
    "text"
  ],
  "LimitToSegments": [
    "text"
  ],
  "GlobalListValueReferencesOnly": true,
  "FromTimestamp": "2025-05-09T12:14:45.315Z"
}
200

OK

[
  {
    "AssetId": 1,
    "Values": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  }
]

Get enrichment insights for multiple assets

post
Authorizations
Body
integer · int32[]Optional
Responses
200
OK
400
Bad Request
post
POST /v1/assets/batch/enrichmentsinsights HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 3

[
  1
]
[
  {
    "EnrichmentInsightSetupUid": "123e4567-e89b-12d3-a456-426614174000",
    "EntityId": 1,
    "Completeness": 1,
    "MissingData": [
      {
        "Type": "text",
        "DataReference": "text"
      }
    ],
    "Ignored": true
  }
]

Get insights for a batch of assets and a specific Enrichment Insight

post
Authorizations
Path parameters
enrichmentInsightUidstringRequired
Query parameters
enrichmentInsightUidstring · uuidOptional

Uid of enrichment insight to get for batch of assets

Body
integer · int32[]Optional
Responses
200
OK
post
POST /v1/assets/batch/enrichmentinsights/{enrichmentInsightUid} HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 3

[
  1
]
200

OK

[
  {
    "EnrichmentInsightSetupUid": "123e4567-e89b-12d3-a456-426614174000",
    "EntityId": 1,
    "Completeness": 1,
    "MissingData": [
      {
        "Type": "text",
        "DataReference": "text"
      }
    ],
    "Ignored": true
  }
]

Enable or disable an enrichment insight for a batch of assets

patch
Authorizations
Path parameters
enrichmentInsightSetupUidstringRequired
ignorestringRequired
Query parameters
enrichmentInsightSetupUidstring · uuidOptional

Uid of enrichment insight to toggle ignore for

ignorebooleanOptional

Indicate whether to ignore the insight for the given enrichment insight and assets

Body
integer · int32[]Optional
Responses
200
OK
patch
PATCH /v1/assets/batch/enrichmentinsights/{enrichmentInsightSetupUid}/{ignore} HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 3

[
  1
]
200

OK

No content

Get references to a batch of assets

post
Authorizations
Body
integer · int32[]Optional
Responses
200
OK
post
POST /v1/assets/batch/references HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 3

[
  1
]
200

OK

[
  {
    "AssetId": 1,
    "ReferencingCategories": [
      {
        "EntityId": 1,
        "AttributeUid": "123e4567-e89b-12d3-a456-426614174000"
      }
    ],
    "ReferencingProducts": [
      {
        "EntityId": 1,
        "AttributeUid": "123e4567-e89b-12d3-a456-426614174000"
      }
    ],
    "ReferencingVariantGroups": [
      {
        "EntityId": 1,
        "AttributeUid": "123e4567-e89b-12d3-a456-426614174000"
      }
    ],
    "ReferencingVariants": [
      {
        "EntityId": 1,
        "AttributeUid": "123e4567-e89b-12d3-a456-426614174000"
      }
    ],
    "ReferencingAssets": [
      {
        "EntityId": 1,
        "AttributeUid": "123e4567-e89b-12d3-a456-426614174000"
      }
    ],
    "ReferencingGlobalListValues": [
      "123e4567-e89b-12d3-a456-426614174000"
    ]
  }
]

Get ids of assets matching a certain criteria

post
Authorizations
Body

Search model used for searching products or variants in PIM

IncludeArchivedbooleanOptional

Include archived items in result

Responses
200
OK
Responseinteger · int32[]
400
Bad Request
post
POST /v1/assets/search HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 59

{
  "IncludeArchived": true,
  "QueryModel": {
    "BooleanOperator": 0
  }
}
[
  1
]

Get paged result of assets matching certain criteria. Result mapped with headers and item results

post
Authorizations
Body

Extended search model used for searching products or variants in PIM with support for paging and sorting

Pageinteger · int32Optional
PageSizeinteger · int32 | nullableOptional
FieldUidsstring[] | nullableOptional
SortByFieldUidstring | nullableOptional
SortDescendingboolean | nullableOptional
IncludeArchivedbooleanOptional

Include archived items in result

Responses
200
OK
400
Bad Request
post
POST /v1/assets/search/paged HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 148

{
  "Page": 1,
  "PageSize": 1,
  "FieldUids": [
    "text"
  ],
  "SortByFieldUid": "text",
  "SortDescending": true,
  "IncludeArchived": true,
  "QueryModel": {
    "BooleanOperator": 0
  }
}
{
  "TotalHits": 1,
  "Page": 1,
  "PageSize": 1,
  "TotalPages": 1,
  "ItemListHeaders": [
    {
      "FieldUid": "text",
      "FieldName": "text",
      "FieldType": "text",
      "SupportsSearching": true,
      "SupportsSorting": true
    }
  ],
  "ListItems": [
    {
      "Id": 1,
      "ShownValues": [
        "text"
      ]
    }
  ]
}