Bynder Asset Management API

{"openapi":"3.1.0","info":{"title":"Asset Management API","version":"1.0.0"},"servers":[{"url":"https://{your-bynder-domain}/"}],"tags":[{"name":"Media","description":""},{"name":"Media ID","description":""},{"name":"Media options","description":""}],"paths":{"/api/v4/media/":{"get":{"summary":"Retrieve assets","description":"`original` is only returned for assets marked as public and requires the account to have the `seoBaseUrl` setting configured.\n","tags":["Media"],"parameters":[{"in":"header","name":"Authorization","required":true,"schema":{"type":"string"},"description":"OAuth 2.0 Bearer access token."},{"in":"query","name":"brandId","schema":{"type":"string","format":"uuid"},"description":"Brand id, can be retrieved using the Retrieve brands and subbrands call."},{"in":"query","name":"subBrandId","schema":{"type":"string","format":"uuid"},"description":"Sub-brand id, can be retrieved using the Retrieve brands and subbrands call."},{"in":"query","name":"categoryId","schema":{"type":"string","format":"uuid"},"description":"Category id, can be retrieved using the Retrieve categories call."},{"in":"query","name":"collectionId","schema":{"type":"string","format":"uuid"},"description":"Collection id, can be retrieved using the Retrieve collections call."},{"in":"query","name":"id","schema":{"type":"string","format":"uuid"},"description":"Asset id, will return the asset for that id."},{"in":"query","name":"ids","schema":{"type":"string"},"description":"Comma-separated list of asset ids. Will return an asset for each existing id."},{"in":"query","name":"propertyOptionId","schema":{"type":"string"},"description":"Comma-separated list of (metaproperty) option ids, can be retrieved using the Retrieve metaproperties call."},{"in":"query","name":"tags","schema":{"type":"string"},"description":"Comma-separated list of tags, can be retrieved using the Retrieve tags call."},{"in":"query","name":"type","schema":{"type":"string","enum":["image","document","audio","video","3d"]},"description":"Comma-separated list of asset types."},{"in":"query","name":"orientation","schema":{"type":"string","enum":["square","portrait","landscape"]},"description":"Comma-separated list of asset orientation."},{"in":"query","name":"property_NAME","schema":{"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":"limited","schema":{"type":"boolean"},"description":"Indicates whether or not the response should only contain assets marked as \"limited usage\"."},{"in":"query","name":"archive","schema":{"type":"boolean"},"description":"Indicates whether or not the response should only contain archived assets."},{"in":"query","name":"isPublic","schema":{"type":"boolean"},"description":"Indicates whether or not the response should only contain assets marked as public."},{"in":"query","name":"keyword","schema":{"type":"string"},"description":"Search on filenames, tags, extensions, collection names, guidelines, brandstore, campaigns in workflow, enriched PDFs, word documents."},{"in":"query","name":"dateCreated","schema":{"type":"string","format":"date-time"},"description":"Retrieve assets created after this date."},{"in":"query","name":"dateCreatedTo","schema":{"type":"string","format":"date-time"},"description":"Set a date range together with the \"dateCreated\" parameter."},{"in":"query","name":"dateCreatedOn","schema":{"type":"string","format":"date-time"},"description":"Retrieve assets created on this specific date."},{"in":"query","name":"dateModified","schema":{"type":"string","format":"date-time"},"description":"Retrieve assets modified after this date."},{"in":"query","name":"dateModifiedTo","schema":{"type":"string","format":"date-time"},"description":"Set a date range together with the \"dateModified\" parameter."},{"in":"query","name":"dateModifiedOn","schema":{"type":"string","format":"date-time"},"description":"Retrieve assets modified on this specific date."},{"in":"query","name":"orderBy","schema":{"type":"string","enum":["dateCreated asc","dateModified asc","datePublished asc","name asc","dateCreated desc","dateModified desc","datePublished desc","name desc"]},"description":"Order of the returned list of assets."},{"in":"query","name":"limit","schema":{"type":"integer","maximum":1000,"default":50},"description":"Maximum number of results."},{"in":"query","name":"page","schema":{"type":"integer","default":1},"description":"Offset page for results: return the N-th set of limit-results.\n"},{"in":"query","name":"count","schema":{"type":"boolean","default":false},"description":"Indicating whether or not the response should include count results."},{"in":"query","name":"total","schema":{"type":"boolean","default":false},"description":"Indicating whether or not the response should include the total count of results."},{"in":"query","name":"includeMediaItems","schema":{"type":"boolean","default":false},"description":"Indicating whether or not the response should include all the different media items (derivatives) available for each asset."},{"in":"query","name":"includeVersionNumber","schema":{"type":"boolean","default":false},"description":"Indicating whether or not the response should include the active version number."},{"in":"query","name":"cursor","schema":{"type":"string"},"description":"cursorMark returned in the X-Bynder-NextCursor response header which allows to return the next set of results."}],"security":[{"permanentToken":["","ARCHIVEMEDIA","ARCHIVEDOWNLOAD","EMARGOMEDIA","KEYVISUALDOWNLOAD"]},{"OAuth2":["","ARCHIVEMEDIA","ARCHIVEDOWNLOAD","EMARGOMEDIA","KEYVISUALDOWNLOAD"]}],"responses":{"200":{"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"}}},"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"dateModified":{"type":"string","format":"date-time"},"propertyOptions":{"type":"array","items":{"type":"string"}},"type":{"type":"string"},"brandId":{"type":"string","format":"uuid"},"fileSize":{"type":"integer"},"id":{"type":"string","format":"uuid"},"height":{"type":"integer"},"description":{"type":"string"},"idHash":{"type":"string"},"name":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"orientation":{"type":"string"},"width":{"type":"integer"},"datePublished":{"type":"string","format":"date-time"},"copyright":{"type":"string"},"extension":{"type":"array","items":{"type":"string"}},"userCreated":{"type":"string"},"dateCreated":{"type":"string","format":"date-time"},"archive":{"type":"boolean"},"property_limitedrights":{"type":"string"},"watermarked":{"type":"boolean"},"limited":{"type":"boolean"},"isPublic":{"type":"boolean"},"thumbnails":{"type":"object","properties":{"mini":{"type":"string"},"webimage":{"type":"string"},"thul":{"type":"string"}}},"transformBaseUrl":{"type":"string"},"videoPreviewURLs":{"type":"array","items":{"type":"string"}},"original":{"type":"string"},"mediaItems":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"publicUrl":{"type":"string"},"type":{"type":"string"}}}}}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"statuscode":{"type":"string"}}}}}}}}},"/api/v4/media/{id}":{"get":{"summary":"Retrieve specific asset","description":"Requires the **STATISTICS** security role in order to retrieve *views* and *downloads* statistics data in the response, using the `stats` parameter.","tags":["Media ID"],"security":[{"permanentToken":["","STATISTICS"]},{"OAuth2":["","STATISTICS"]}],"parameters":[{"in":"header","name":"Authorization","required":true,"schema":{"type":"string"},"description":"OAuth 2.0 Bearer access token."},{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Asset id."},{"in":"query","name":"versions","schema":{"type":"boolean","default":false},"description":"Include information about the different asset media items including versions."},{"in":"query","name":"stats","schema":{"type":"boolean","default":false},"description":"Include information about *views* and *downloads*."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"dateModified":{"type":"string","format":"date-time"},"propertyOptions":{"type":"array","items":{"type":"string"}},"type":{"type":"string"},"brandId":{"type":"string","format":"uuid"},"fileSize":{"type":"integer"},"id":{"type":"string","format":"uuid"},"height":{"type":"integer"},"description":{"type":"string"},"idHash":{"type":"string"},"name":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"orientation":{"type":"string"},"width":{"type":"integer"},"datePublished":{"type":"string","format":"date-time"},"copyright":{"type":"string"},"extension":{"type":"array","items":{"type":"string"}},"userCreated":{"type":"string"},"dateCreated":{"type":"string","format":"date-time"},"archive":{"type":"boolean"},"property_assettype":{"type":"array","items":{"type":"string"}},"watermarked":{"type":"boolean"},"limited":{"type":"boolean"},"videoPreviewURLs":{"type":"array","items":{"type":"string"}},"thumbnails":{"type":"object","properties":{"mini":{"type":"string"},"webimage":{"type":"string"},"thul":{"type":"string"}}},"views":{"type":"integer"},"downloads":{"type":"integer"},"isPublic":{"type":"boolean"},"original":{"type":"string"},"relatedAssets":{"type":"array","items":{"type":"object","properties":{"metaPropertyId":{"type":"string"},"assets":{"type":"array","items":{"type":"string"}},"metaPropertyName":{"type":"string"}}}},"activeOriginalFocusPoint":{"type":"object","properties":{"y":{"type":"integer"},"x":{"type":"integer"}}},"transformBaseUrl":{"type":"string"}}}}}},"404":{"description":"File not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"statuscode":{"type":"string"}}}}}}}},"post":{"summary":"Modify asset","description":"Requires the **MEDIAEDIT** security role. Requires the **MARKPUBLIC** security role in order to change an asset's isPublic state.","tags":["Media ID"],"security":[{"permanentToken":["","MEDIAEDIT","MARKPUBLIC"]},{"OAuth2":["","MEDIAEDIT","MARKPUBLIC"]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Asset id."}],"requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Asset id."},"name":{"type":"string","description":"Name of the asset, beware the asset will have no name when this is empty."},"description":{"type":"string","description":"Asset description."},"copyright":{"type":"string","description":"Copyright information of the asset."},"brandId":{"type":"string","description":"Id of the brand to save the asset to."},"tags":{"type":"string","description":"Comma-separated tags. Tags will overwrite the current tags list."},"metaproperty":{"type":"object","additionalProperties":{"type":"string"},"description":"Dictionary with (metaproperty) options to set on the asset."},"datePublished":{"type":"string","format":"date-time","description":"Publication datetime. ISO8601 format: yyyy-mm-ddThh:mm:ssZ.\n"},"archive":{"type":"boolean","description":"Indicating the archived state of the asset."},"archiveDate":{"type":"string","format":"date-time","description":"Archive datetime. ISO8601 format: yyyy-mm-ddThh:mm:ssZ.\n"},"limited":{"type":"boolean","description":"Indicating the limit state of the asset."},"limitedDate":{"type":"string","format":"date-time","description":"Limit datetime. ISO8601 format: yyyy-mm-ddThh:mm:ssZ.\n"},"watermarkDate":{"type":"string","format":"date-time","description":"Watermark datetime. ISO8601 format: yyyy-mm-ddThh:mm:ssZ.\n"},"isPublic":{"type":"boolean","description":"Indicating the public state of the asset. Warning irreversible, once changed to true it cannot be changed back."}}}}}},"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"statuscode":{"type":"integer"}}}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"statuscode":{"type":"string"}}}}}},"404":{"description":"Media not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"statuscode":{"type":"string"}}}}}}}},"delete":{"summary":"Delete asset","description":"Requires the **MEDIAREMOVE** security role.","tags":["Media ID"],"security":[{"permanentToken":["","MEDIAREMOVE"]},{"OAuth2":["","MEDIAREMOVE"]}],"parameters":[{"in":"header","name":"Authorization","required":true,"schema":{"type":"string"},"description":"OAuth 2.0 Bearer access token."},{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Asset id."}],"responses":{"204":{"description":"No Content"},"403":{"description":"Access denied","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"statuscode":{"type":"string"}}}}}},"404":{"description":"Media not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"statuscode":{"type":"string"}}}}}}}}},"/api/media/options":{"post":{"summary":"Add metaproperty options","description":"These calls allow you to change the metaproperty options attached to an asset.","tags":["Media options"],"security":[{"permanentToken":["MEDIAEDIT"]},{"OAuth2":["MEDIAEDIT"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"asset_id":{"type":"string","example":"00000000-0000-0000-0000000000000000"},"metaproperty_id":{"type":"string","example":"00000000-0000-0000-0000000000000000"},"metaproperty_option_ids":{"type":"array","items":{"type":"string","example":"00000000-0000-0000-0000000000000000"}}}},"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"]}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Created"},"statuscode":{"type":"integer","example":201}}}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Access denied"},"statuscode":{"type":"integer","example":403}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Not Found"},"statuscode":{"type":"integer","example":404}}}}}}}},"delete":{"summary":"Delete metaproperty options","tags":["Media options"],"security":[{"permanentToken":["MEDIAEDIT"]},{"OAuth2":["MEDIAEDIT"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"asset_id":{"type":"string","example":"00000000-0000-0000-0000000000000000"},"metaproperty_id":{"type":"string","example":"00000000-0000-0000-0000000000000000"},"metaproperty_option_ids":{"type":"array","items":{"type":"string","example":"00000000-0000-0000-0000000000000000"}}}}}}},"responses":{"204":{"description":"No Content","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"No Content"},"statuscode":{"type":"integer","example":204}}}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Access denied"},"statuscode":{"type":"integer","example":403}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Not Found"},"statuscode":{"type":"integer","example":404}}}}}}}}}},"components":{"securitySchemes":{"permanentToken":{"type":"apiKey","in":"header","name":"Authorization"},"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://{your-bynder-domain}/v6/authentication/oauth2/token","scopes":{"ARCHIVEMEDIA":"","ARCHIVEDOWNLOAD":"","EMARGOMEDIA":"","KEYVISUALDOWNLOAD":"","STATISTICS":"","MEDIAEDIT":"","MARKPUBLIC":"","MEDIAREMOVE":""}},"authorizationCode":{"authorizationUrl":"https://{your-auth-url}","tokenUrl":"https://{your-bynder-domain}/v6/authentication/oauth2/token","scopes":{"ARCHIVEMEDIA":"","ARCHIVEDOWNLOAD":"","EMARGOMEDIA":"","KEYVISUALDOWNLOAD":"","STATISTICS":"","MEDIAEDIT":"","MARKPUBLIC":"","MEDIAREMOVE":""}}}}}}}