---
title: "Asset Management API"
url: "https://earlyaccess.developers.bynder.com/apis/asset-management-api-1/versions/b623ec0a-a559-4667-a0ee-28fa2b9cd7ce"
---

# Asset Management API

OpenAPI specification document.

```json
{"components":{"securitySchemes":{"OAuth2":{"flows":{"authorizationCode":{"authorizationUrl":"https://{your-auth-url}","scopes":{"ARCHIVEDOWNLOAD":"","ARCHIVEMEDIA":"","EMARGOMEDIA":"","KEYVISUALDOWNLOAD":"","MARKPUBLIC":"","MEDIAEDIT":"","MEDIAREMOVE":"","STATISTICS":""},"tokenUrl":"https://{your-bynder-domain}/v6/authentication/oauth2/token"},"clientCredentials":{"scopes":{"ARCHIVEDOWNLOAD":"","ARCHIVEMEDIA":"","EMARGOMEDIA":"","KEYVISUALDOWNLOAD":"","MARKPUBLIC":"","MEDIAEDIT":"","MEDIAREMOVE":"","STATISTICS":""},"tokenUrl":"https://{your-bynder-domain}/v6/authentication/oauth2/token"}},"type":"oauth2"},"permanentToken":{"in":"header","name":"Authorization","type":"apiKey"}}},"info":{"title":"Asset Management API","version":"1.0.0"},"openapi":"3.1.0","paths":{"/api/media/options":{"delete":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"asset_id":{"example":"00000000-0000-0000-0000000000000000","type":"string"},"metaproperty_id":{"example":"00000000-0000-0000-0000000000000000","type":"string"},"metaproperty_option_ids":{"items":{"example":"00000000-0000-0000-0000000000000000","type":"string"},"type":"array"}},"type":"object"}}},"required":true},"responses":{"204":{"content":{"application/json":{"schema":{"properties":{"message":{"example":"No Content","type":"string"},"statuscode":{"example":204,"type":"integer"}},"type":"object"}}},"description":"No Content"},"403":{"content":{"application/json":{"schema":{"properties":{"message":{"example":"Access denied","type":"string"},"statuscode":{"example":403,"type":"integer"}},"type":"object"}}},"description":"Access denied"},"404":{"content":{"application/json":{"schema":{"properties":{"message":{"example":"Not Found","type":"string"},"statuscode":{"example":404,"type":"integer"}},"type":"object"}}},"description":"Not Found"}},"security":[{"permanentToken":["MEDIAEDIT"]},{"OAuth2":["MEDIAEDIT"]}],"summary":"Delete metaproperty options","tags":["Media options"]},"post":{"description":"These calls allow you to change the metaproperty options attached to an asset.\n\n**Note that this is an append operation; the options you add here will be appended to the existing option on the asset, it does not overwrite them.**","requestBody":{"content":{"application/json":{"examples":{"example1":{"value":{"asset_id":"00000000-0000-0000-0000000000000000","metaproperty_id":"00000000-0000-0000-0000000000000000","metaproperty_option_ids":["00000000-0000-0000-0000000000000000","00000000-0000-0000-0000000000000001"]}}},"schema":{"properties":{"asset_id":{"example":"00000000-0000-0000-0000000000000000","type":"string"},"metaproperty_id":{"example":"00000000-0000-0000-0000000000000000","type":"string"},"metaproperty_option_ids":{"items":{"example":"00000000-0000-0000-0000000000000000","type":"string"},"type":"array"}},"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"message":{"example":"Created","type":"string"},"statuscode":{"example":201,"type":"integer"}},"type":"object"}}},"description":"Created"},"403":{"content":{"application/json":{"schema":{"properties":{"message":{"example":"Access denied","type":"string"},"statuscode":{"example":403,"type":"integer"}},"type":"object"}}},"description":"Access denied"},"404":{"content":{"application/json":{"schema":{"properties":{"message":{"example":"Not Found","type":"string"},"statuscode":{"example":404,"type":"integer"}},"type":"object"}}},"description":"Not Found"}},"security":[{"permanentToken":["MEDIAEDIT"]},{"OAuth2":["MEDIAEDIT"]}],"summary":"Add metaproperty options","tags":["Media options"]}},"/api/v4/media/":{"get":{"description":"`original` is only returned for assets marked as public and requires the account to have the `seoBaseUrl` setting configured.\n","parameters":[{"description":"OAuth 2.0 Bearer access token.","in":"header","name":"Authorization","required":true,"schema":{"type":"string"}},{"description":"Brand id, can be retrieved using the Retrieve brands and subbrands call.","in":"query","name":"brandId","schema":{"format":"uuid","type":"string"}},{"description":"Sub-brand id, can be retrieved using the Retrieve brands and subbrands call.","in":"query","name":"subBrandId","schema":{"format":"uuid","type":"string"}},{"description":"Category id, can be retrieved using the Retrieve categories call.","in":"query","name":"categoryId","schema":{"format":"uuid","type":"string"}},{"description":"Collection id, can be retrieved using the Retrieve collections call.","in":"query","name":"collectionId","schema":{"format":"uuid","type":"string"}},{"description":"Asset id, will return the asset for that id.","in":"query","name":"id","schema":{"format":"uuid","type":"string"}},{"description":"Comma-separated list of asset ids. Will return an asset for each existing id.","in":"query","name":"ids","schema":{"type":"string"}},{"description":"Comma-separated list of (metaproperty) option ids, can be retrieved using the Retrieve metaproperties call.","in":"query","name":"propertyOptionId","schema":{"type":"string"}},{"description":"Comma-separated list of tags, can be retrieved using the Retrieve tags call.","in":"query","name":"tags","schema":{"type":"string"}},{"description":"Comma-separated list of asset types.","in":"query","name":"type","schema":{"enum":["image","document","audio","video","3d"],"type":"string"}},{"description":"Comma-separated list of asset orientation.","in":"query","name":"orientation","schema":{"enum":["square","portrait","landscape"],"type":"string"}},{"description":"Metaproperty option name or comma-separated list ids of metaproperty options for that metaproperty. Beware that NAME should be replaced with the actual metaproperty name. This is an AND operation when passing multiple values. If a Date type metaproperty is added, retrieving assets using the dates for that metaproperty is not supported.","in":"query","name":"property_NAME","schema":{"type":"string"}},{"description":"Indicates whether or not the response should only contain assets marked as \"limited usage\".","in":"query","name":"limited","schema":{"type":"boolean"}},{"description":"Indicates whether or not the response should only contain archived assets.","in":"query","name":"archive","schema":{"type":"boolean"}},{"description":"Indicates whether or not the response should only contain assets marked as public.","in":"query","name":"isPublic","schema":{"type":"boolean"}},{"description":"Search on filenames, tags, extensions, collection names, guidelines, brandstore, campaigns in workflow, enriched PDFs, word documents.","in":"query","name":"keyword","schema":{"type":"string"}},{"description":"Retrieve assets created after this date. ISO8601 format yyyy-mm-ddThh:mm:ssZ.","in":"query","name":"dateCreated","schema":{"format":"date-time","type":"string"}},{"description":"Set a date range together with the \"dateCreated\" parameter. ISO8601 format yyyy-mm-ddThh:mm:ssZ.","in":"query","name":"dateCreatedTo","schema":{"format":"date-time","type":"string"}},{"description":"Retrieve assets created on this specific date. ISO8601 format yyyy-mm-ddThh:mm:ssZ.","in":"query","name":"dateCreatedOn","schema":{"format":"date-time","type":"string"}},{"description":"Retrieve assets modified after this date. ISO8601 format yyyy-mm-ddThh:mm:ssZ.","in":"query","name":"dateModified","schema":{"format":"date-time","type":"string"}},{"description":"Set a date range together with the \"dateModified\" parameter. ISO8601 format yyyy-mm-ddThh:mm:ssZ.","in":"query","name":"dateModifiedTo","schema":{"format":"date-time","type":"string"}},{"description":"Retrieve assets modified on this specific date. ISO8601 format yyyy-mm-ddThh:mm:ssZ.","in":"query","name":"dateModifiedOn","schema":{"format":"date-time","type":"string"}},{"description":"Order of the returned list of assets.","in":"query","name":"orderBy","schema":{"enum":["dateCreated asc","dateModified asc","datePublished asc","name asc","dateCreated desc","dateModified desc","datePublished desc","name desc"],"type":"string"}},{"description":"Maximum number of results.","in":"query","name":"limit","schema":{"default":50,"maximum":1000,"type":"integer"}},{"description":"Offset page for results: return the N-th set of limit-results.\n","in":"query","name":"page","schema":{"default":1,"type":"integer"}},{"description":"Indicating whether or not the response should include count results.","in":"query","name":"count","schema":{"default":false,"type":"boolean"}},{"description":"Indicating whether or not the response should include the total count of results.","in":"query","name":"total","schema":{"default":false,"type":"boolean"}},{"description":"Indicating whether or not the response should include all the different media items (derivatives) available for each asset.","in":"query","name":"includeMediaItems","schema":{"default":false,"type":"boolean"}},{"description":"Indicating whether or not the response should include the active version number.","in":"query","name":"includeVersionNumber","schema":{"default":false,"type":"boolean"}},{"description":"cursorMark returned in the X-Bynder-NextCursor response header which allows to return the next set of results.","in":"query","name":"cursor","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"properties":{"archive":{"type":"boolean"},"brandId":{"format":"uuid","type":"string"},"copyright":{"type":"string"},"dateCreated":{"format":"date-time","type":"string"},"dateModified":{"format":"date-time","type":"string"},"datePublished":{"format":"date-time","type":"string"},"description":{"type":"string"},"extension":{"items":{"type":"string"},"type":"array"},"fileSize":{"type":"integer"},"height":{"type":"integer"},"id":{"format":"uuid","type":"string"},"idHash":{"type":"string"},"isPublic":{"type":"boolean"},"limited":{"type":"boolean"},"mediaItems":{"items":{"properties":{"name":{"type":"string"},"publicUrl":{"type":"string"},"type":{"type":"string"}},"type":"object"},"type":"array"},"name":{"type":"string"},"orientation":{"type":"string"},"original":{"type":"string"},"propertyOptions":{"items":{"type":"string"},"type":"array"},"property_limitedrights":{"type":"string"},"tags":{"items":{"type":"string"},"type":"array"},"thumbnails":{"properties":{"mini":{"type":"string"},"thul":{"type":"string"},"webimage":{"type":"string"}},"type":"object"},"transformBaseUrl":{"type":"string"},"type":{"type":"string"},"userCreated":{"type":"string"},"videoPreviewURLs":{"items":{"type":"string"},"type":"array"},"watermarked":{"type":"boolean"},"width":{"type":"integer"}},"type":"object"},"type":"array"}}},"description":"Successful response","headers":{"X-Bynder-NextCursor":{"description":"SOLR nextCursorMark which can be used to return the next X number of results. Returned when solr-cursor account feature is enabled.","schema":{"type":"string"}}}},"404":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"statuscode":{"type":"string"}},"type":"object"}}},"description":"Not Found"}},"security":[{"permanentToken":["","ARCHIVEMEDIA","ARCHIVEDOWNLOAD","EMARGOMEDIA","KEYVISUALDOWNLOAD"]},{"OAuth2":["","ARCHIVEMEDIA","ARCHIVEDOWNLOAD","EMARGOMEDIA","KEYVISUALDOWNLOAD"]}],"summary":"Retrieve assets","tags":["Media"]}},"/api/v4/media/{id}":{"delete":{"description":"Requires the **MEDIAREMOVE** security role.","parameters":[{"description":"OAuth 2.0 Bearer access token.","in":"header","name":"Authorization","required":true,"schema":{"type":"string"}},{"description":"Asset id.","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"No Content"},"403":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"statuscode":{"type":"string"}},"type":"object"}}},"description":"Access denied"},"404":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"statuscode":{"type":"string"}},"type":"object"}}},"description":"Media not found"}},"security":[{"permanentToken":["","MEDIAREMOVE"]},{"OAuth2":["","MEDIAREMOVE"]}],"summary":"Delete asset","tags":["Media ID"]},"get":{"description":"Requires the **STATISTICS** security role in order to retrieve *views* and *downloads* statistics data in the response, using the `stats` parameter.","parameters":[{"description":"OAuth 2.0 Bearer access token.","in":"header","name":"Authorization","required":true,"schema":{"type":"string"}},{"description":"Asset id.","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Include information about the different asset media items including versions.","in":"query","name":"versions","schema":{"default":false,"type":"boolean"}},{"description":"Include information about *views* and *downloads*.","in":"query","name":"stats","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"activeOriginalFocusPoint":{"properties":{"x":{"type":"integer"},"y":{"type":"integer"}},"type":"object"},"archive":{"type":"boolean"},"brandId":{"format":"uuid","type":"string"},"copyright":{"type":"string"},"dateCreated":{"format":"date-time","type":"string"},"dateModified":{"format":"date-time","type":"string"},"datePublished":{"format":"date-time","type":"string"},"description":{"type":"string"},"downloads":{"type":"integer"},"extension":{"items":{"type":"string"},"type":"array"},"fileSize":{"type":"integer"},"height":{"type":"integer"},"id":{"format":"uuid","type":"string"},"idHash":{"type":"string"},"isPublic":{"type":"boolean"},"limited":{"type":"boolean"},"name":{"type":"string"},"orientation":{"type":"string"},"original":{"type":"string"},"propertyOptions":{"items":{"type":"string"},"type":"array"},"property_assettype":{"items":{"type":"string"},"type":"array"},"relatedAssets":{"items":{"properties":{"assets":{"items":{"type":"string"},"type":"array"},"metaPropertyId":{"type":"string"},"metaPropertyName":{"type":"string"}},"type":"object"},"type":"array"},"tags":{"items":{"type":"string"},"type":"array"},"thumbnails":{"properties":{"mini":{"type":"string"},"thul":{"type":"string"},"webimage":{"type":"string"}},"type":"object"},"transformBaseUrl":{"type":"string"},"type":{"type":"string"},"userCreated":{"type":"string"},"videoPreviewURLs":{"items":{"type":"string"},"type":"array"},"views":{"type":"integer"},"watermarked":{"type":"boolean"},"width":{"type":"integer"}},"type":"object"}}},"description":"Successful response"},"404":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"statuscode":{"type":"string"}},"type":"object"}}},"description":"File not found"}},"security":[{"permanentToken":["","STATISTICS"]},{"OAuth2":["","STATISTICS"]}],"summary":"Retrieve specific asset","tags":["Media ID"]},"post":{"description":"Requires the **MEDIAEDIT** security role. Requires the **MARKPUBLIC** security role in order to change an asset's isPublic state.\n\n**Custom thumbnails**\n\nTo set a custom thumbnail, first upload the thumbnail image using the [Modern Stack File Upload](https://api.bynder.com/reference/modern-stack-file-upload) flow, then call this endpoint with the returned file id as `customThumbnailFileId`. To remove an existing custom thumbnail and revert to the automatically generated one, call this endpoint with `removeCustomThumbnail=true`. The two fields are mutually exclusive.","parameters":[{"description":"Asset id.","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/x-www-form-urlencoded":{"examples":{"real example":{"summary":"Update an asset via x-www-form-urlencoded with metaproperty values","value":{"customThumbnailFileId":"7d3015f1-fadf-4fca-b49e-e6d08a29f9bb","description":"Updated title and metadata from Postman form-data example","id":"8EC04DC8-F7FE-4D2D-BE2F2789A632393D","metaproperty.C53BC6FD-21A0-4DF1-AE80F0A329D7":"Option 1,Option 2","metaproperty.C74B9496-16E8-41AA-80D83D8549C8":"B7F3232E-D2A9-40CF-8551-DA2B1FF4E97D,C5215523-AEBD-4A72-92F8-5D8C5E0F2E11","metaproperty.E1202866-306B-43A5-ADE20BDAB6D1":"This is the alt text","metaproperty.E8D9B6EF-F969-49B1-BDB95982F05D":"551CB615-965F-4643-A2A7-A4974AA0B128","name":"Spring campaign hero image","tags":"spring,hero,campaign-2026"}}},"schema":{"properties":{"archive":{"description":"Indicating the archived state of the asset.","type":"boolean"},"archiveDate":{"description":"Archive datetime. ISO8601 format: yyyy-mm-ddThh:mm:ssZ.\n","format":"date-time","type":"string"},"brandId":{"description":"Id of the brand to save the asset to.","type":"string"},"copyright":{"description":"Copyright information of the asset.","type":"string"},"customThumbnailFileId":{"description":"The file id of the custom thumbnail to be set for the asset. Custom thumbnails must first be uploaded by following the steps described in the [Modern Stack File Upload](https://api.bynder.com/reference/modern-stack-file-upload) documentation; use the `fileId` returned by that flow. Cannot be combined with `removeCustomThumbnail`.","example":"00000000-0000-0000-0000-000000000000","type":"string"},"datePublished":{"description":"Publication datetime. ISO8601 format: yyyy-mm-ddThh:mm:ssZ.\n","format":"date-time","type":"string"},"description":{"description":"Asset description.","type":"string"},"id":{"description":"Asset id.","type":"string"},"isPublic":{"description":"Indicating the public state of the asset. Warning irreversible, once changed to true it cannot be changed back.","type":"boolean"},"limited":{"description":"Indicating the limit state of the asset.","type":"boolean"},"limitedDate":{"description":"Limit datetime. ISO8601 format: yyyy-mm-ddThh:mm:ssZ.\n","format":"date-time","type":"string"},"metaproperty":{"additionalProperties":{"type":"string"},"description":"Mapping of metaproperty UUIDs to the option value(s) to set on the asset. Each value may be provided as option label, option DB name, or option UUID. For multi-select metaproperties, pass multiple values as a comma-separated string. <br><br>In x-www-form-urlencoded requests, fields are sent as `metaproperty.<metaproperty_uuid>=<value1>,<value2>`.","example":{"02509778-CEE3-43D5-9E96-9A60B1E78314":"option_id1,option_id2","EF122F1F-9BA0-4772-80F1-BF05588B1A59":"option_id3"},"type":"object"},"name":{"description":"Name of the asset, beware the asset will have no name when this is empty.","type":"string"},"removeCustomThumbnail":{"description":"Remove the current custom thumbnail from the asset, reverting to the automatically generated thumbnail. Cannot be combined with `customThumbnailFileId`.","example":true,"type":"boolean"},"tags":{"description":"Comma-separated tags. Tags will overwrite the current tags list.","type":"string"},"watermarkDate":{"description":"Watermark datetime. ISO8601 format: yyyy-mm-ddThh:mm:ssZ.\n","format":"date-time","type":"string"}},"type":"object"}}}},"responses":{"202":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"statuscode":{"type":"integer"}},"type":"object"}}},"description":"Accepted"},"403":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"statuscode":{"type":"string"}},"type":"object"}}},"description":"Access denied"},"404":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"statuscode":{"type":"string"}},"type":"object"}}},"description":"Media not found"}},"security":[{"permanentToken":["","MEDIAEDIT","MARKPUBLIC"]},{"OAuth2":["","MEDIAEDIT","MARKPUBLIC"]}],"summary":"Modify asset","tags":["Media ID"]}}},"servers":[{"url":"https://{your-bynder-domain}/"}],"tags":[{"description":"","name":"Media"},{"description":"","name":"Media ID"},{"description":"","name":"Media options"}]}
```