The Webdam API is the underlying interface for building apps using the power of Webdam. The API allows developers to securely read and write from Webdam so your users can push and pull their important files and metadata. You’ll also have access to powerful Webdam features such as file sharing, upload, search and more.
In order to use the API, you'll need to create and use an admin account within the system. Please ask your DAM admin to assist you with an account if you don't already have one.
If API usage/analytics is important to your organization, consider using a unique admin seat for the API.
More information on the Search 2.0 API can be found here and the Workstream API can be found here.
Webdam REST API v2
Authorization
Accessing the API
Resources
Folders
Assets
- Asset JSON Format
- Get asset information
- Get multiple asset information
- Edit an asset
- Delete an asset
- Upload an asset (optimized)
- Download an asset
- Queue asset download (BETA)
- Download from queue (BETA)
- View versions of an asset
- Get an asset version
- Delete an asset version
- Restore an asset version
- Download an asset version
- Get related assets for an asset
- Send asset download
- Set download expiration
- Get embeddable links
Metadata
Metadata Templates
Metadata Schema
Download Presets
Lightboxes
- Lightbox JSON Format
- Get current users lightboxes
- Get a lightbox
- Create a lightbox
- Edit a lightbox
- Delete a lightbox
- List assets for a lightbox
- Add asset to a lightbox
- Remove asset from a lightbox
- Empty a lightbox
- List collaborators for a lightbox
- Add collaborator to a lightbox
- Remove a collaborator from a lightbox
- Send lightbox download
Lightboxes Comments
Search
Groups
Users
Account
Notifications
API Reference
Workstream
Brand Connect
Embeddables
Accessing the API
Key |
---|
CLIENT_ID - Please contact your Customer Success Manager, Implementation Consultant, orfile a ticket with our support team for the CLIENT_ID. |
CLIENT_SECRET - Please contact your Customer Success Manager, Implementation Consultant, or file a ticket with our support team for the CLIENT_Secret. |
REDIRECT_URI -This is the client url to redirect back to after successfully logging in. |
ACCESS_CODE - This is used to request an access_token. Lifetime of 30 seconds. |
ACCESS_TOKEN - This is used to make API calls on behalf of a user. Lifetime of 1 hour. |
REFRESH_TOKEN - This is used for refreshing the access token. |
The user will login with their Webdam credentials, and then they will be required to authenticate your application to use their data.
Once the user makes the authorization, Webdam will redirect back to your application and also send a temporary authorization_code in the GET of the redirect URL. An example of the redirect path is:
Your application will then use this authorization_code to fetch an access_token and refresh_token. The access_token will allow your application to perform subsequent service calls on behalf of the user. The state variable will also be forwarded to the redirect URL to help validate the request.
This will return a response which contains keys that will be used to refresh your API session or to get data from Webdam:
{ "access_token":"ACCESS_TOKEN", "expires_in":3600, "token_type":"bearer", "refresh_token":"REFRESH_TOKEN" }
Key (Grant Type: password) |
---|
CLIENT_ID |
CLIENT_SECRET |
USERNAME |
PASSWORD |
ACCESS_TOKEN - This is used to make API calls on behalf of a user. Lifetime of 1 hour. |
REFRESH_TOKEN - This is used for refreshing the access token. |
This will return a response which contains keys that will be used to refresh your API session or to get data from Webdam:
{ "access_token":"ACCESS_TOKEN", "expires_in":3600, "token_type":"bearer", "refresh_token":"REFRESH_TOKEN" }
This may return a response as shown:
[ { "type":"folder", "id":"182378912893", "parent":"0", "name":"Movies", "status":"active", "datecreated":"2013-07-18 07:03:00", "passwordprotected":"false", "user":{ "type":"user", "id":"32326", "email":"testing@yourdomain.com", "name":"John Smith", "username":"jsmith" }, "numassets":"2", "numchildren":1, "permissions":{ "folders":[ "create", "move", "delete", "edit" ], "assets":[ "download", "upload", "move", "edit", "delete" ] }, "thumbnailurls":[ { "size": "100", "url": "https://subdomain.webdamdb.com/s/100th_sm_DSF3243S.jpg" }, { "size": "150", "url": "https://subdomain.webdamdb.com/s/150th_sm_DSF3243S.jpg" }, { "size": "220", "url": "https://subdomain.webdamdb.com/s/220th_sm_DSF3243S.jpg" }, { "size": "310", "url": "https://subdomain.webdamdb.com/s/310th_sm_DSF3243S.jpg" } ] } ]
This is done using the refresh call as shown below:
Note: The refresh_token required above is received using the access_token request, see ‘Getting the access_token’ above.
Folders
Attribute | Type | Description |
---|---|---|
type | string | This is equal to "folder". |
id | long | The unique id of the folder. |
metadatatemplateid | long | The associated metadata template id for a folder, if available. Default value is null. |
parent | string | The id of the folder the folder is located in. Value of 0 means its at the root. |
name | string | The name of the folder. |
status | string | The current state of the folder, either active or inactive. |
user | Mini user | The mini user JSON of the owner of the asset. |
datecreated | string | The date the folder was created. |
passwordprotected | boolean | |
numassets | integer | How many assets are in the folder. |
numchildren | integer | How many nested folders are in the folder. |
clientfolderid | string | An optional identifier guaranteed to be unique. This must be unique across all folders a customer. |
permissions | array | Actions available on folder and it's assets. assets: (view, upload, download, edit, move, delete) folders: (view, create, download, edit, move, delete) |
properties | array | Folder properties |
Properties | Description |
---|---|
ALBWATERMARKPHOTOS | Watermark assets in this folder |
ALBDISPLAYOWNERIMA | Display asset owner |
ALBEMAILHIRESDOWNLOAD | Allow email high res downloads |
ALBENABLE_REQUESTRECIPIENT | Download request recipient |
ALBENABLE_REQUESTDOWNLOAD | Allow download requests |
ALBENABLE_DOWNLOADUSAGE | Require completion of download form |
GET /folders
or
GET /folders/0
Parameters
Curl curl https://apiv2.webdamdb.com/folders
Example Response Status: 200 OK
Note:returns top level children.
|
GET /folders/:folderid
Parameters
Curl curl https://apiv2.webdamdb.com/folders/90672
Example Response Status: 200 OK
Note:returns top level children.
|
GET /folders/list?ids={ids}
Parameters
Curl curl https://apiv2.webdamdb.com/folders/list?ids=192498,192517
Example Response Status: 200 OK
Note: does not return top level children. |
POST /folders
Parameters
Curl curl https://apiv2.webdamdb.com/folders -d '{"parent":"90784","clientfolderid":null, "name":"Marketing","status":"active"}' -X POST
The clientfolderid is an OPTIONAL unique attribute on a folder that enforces uniqueness across all folders. If there is a conflict on uniqueness, a 403 HTTP response code will be issued. Example Response Status: 201 Created
|
PUT /folders/:folderid
Parameters
Curl curl https://apiv2.webdamdb.com/folders/
90123 -d '{"name":"Marketing Asia","status":"active"}' -X PUT
Example Response Status: 200 OK
|
DELETE /folders/:folderid
Curl curl https://apiv2.webdamdb.com/folders/808232 -X DELETE
Example Response Status: 204 OK
|
GET /folders/:folderid/assets
Curl curl https://apiv2.webdamdb.com/folders/808232/assets?sortby=filename&sortdir=desc&limit=20&offset=0
Parameters
Example Response Status: 200 OK
|
Assets
Attribute | Type | Description |
---|---|---|
type | string | This is equal to "asset". |
id | long | The unique id of the asset. |
status | string | The current state of the asset, either active or inactive. |
filename | string | The filename of the asset. |
version | string | The version number of the file. Default is 1. |
name | string | The name of the asset. |
filesize | string | The size of the asset in bytes. |
width | long | The width in pixels of the asset. The width attribute only applies to certain types of assets such as image or videos. |
height | long | The height in pixels of the asset. The height attribute only applies to certain types of assets such as image or videos. |
filetype | string | The type of file. |
colorspace | string | The colorspace of the asset. This attribute only applies to certain types of assets such as image. |
thumbnailurls | array | The link to thumbnail of the asset. Available max dimension are 100px, 150px, 220px, 310px and 550px. This attribute only applies to certain types of assets such as image or videos. |
datecreated | string | The unix timestamp of the date the asset was created or uploaded. |
datemodified | string | The unix timestamp of the date the asset was last modified. |
datecaptured | string | The unix timestamp of the date the asset was captured. This usually only applies to files generated by a camera or scanned in. |
numComments | integer | The number of comments on this asset. |
user | Mini user | The mini user JSON of the owner of the asset. |
folder | Mini folder | The mini folder JSON the asset is located in. |
GET /assets/:assetid
Parameters
Curl curl https://apiv2.webdamdb.com/assets/23422
Example Response Status: 200 OK
|
GET /assets/list?ids={ids}
Parameters
Curl curl https://apiv2.webdamdb.com/assets/list?ids=5992827,5992826
Status: 200 OK
|
PUT /assets/:assetid
If an asset is uploaded and its required fields are not filled in, the asset is in onhold status and cannot be activated until all required fields are supplied. Any attempt to change the status to 'active' for assets that still require metadata will return back 409. Parameters
Curl curl https://apiv2.webdamdb.com/assets/23422 -d '{"status": "active", "filename": "newfilename.jpg", "description": "Nice", "folder": { "id": "90751" }}'
Example Response Status: 200 OK
API endpoint to support custom conversions for image asset downloads in Webdam.
This is a 2 step process: 1. Queue assets (BETA) 2. Download From Queue (BETA) This step will allow users to queue an asset for download by specifying an AssetID and a Preset ID or custom conversion parameters. If a valid PresetID is defined, the other conversions parameters will be ignored (format, resolution, size, orientation, colorspace).
This step will allow users to download the queued asset using the download key returned from step1 (Queue asset process). The output of this step will be a download URL to the asset or the download status, if the asset is not ready for download.
Set Download Link Expiration
Metadata
Metadata Templates
Metadata Schema
Download PresetsGet Download Presets from your Webdam account.
Lightboxes
Lightbox Comments
SearchNote:
- You may only search one Search Field at a time using the Search API.
- Only the parameters listed below are supported.
Groups
Users
|
GET /users
Allowed For Curl curl https://apiv2.webdamdb.com/users?offset=0&limit=1&sortby=username&sortdir=asc
Parameters
Example Response Status: 200 OK
|
GET /users/me
Curl curl https://apiv2.webdamdb.com/users/me
Example Response Status: 200 OK
|
GET /users/9769
Allowed For Curl curl https://apiv2.webdamdb.com/users/9769
Example Response Status: 200 OK
|
GET /users/9769/groups
Allowed For Curl curl https://apiv2.webdamdb.com/users/9769/groups
Example Response Status: 200 OK
|
POST /users
Allowed For Curl curl https://apiv2.webdamdb.com/users -d '{"username":"90784","password1":"password@12","password2":"password@12","first":"John","last":"smith","email":contrib@webdamdb.com","country": "United States","zip": "94402,"sendemail": true,"status":"active"}' -X POST
Example Response Status: 201 Created
|
PUT /users/:userid
or PUT /users/me
Curl curl https://apiv2.webdamdb.com/users/me -d '{"id":12321","email":"contrib2@webdamdb.com", "status":"inactive", "zip":"94065"}' -X PUT
Example Response Status: 200 OK
|
DELETE /users/:userid
Allowed For Curl curl https://apiv2.webdamdb.com/users/9769 -X DELETE
Example Response Status: 204 OK
|
Account
GET /subscription
Curl curl https://apiv2.webdamdb.com/subscription
Example Response Status: 200 OK
|
Notifications
Action | Description |
---|---|
asset_created | A user uploaded asset(s) to a folder |
asset_deleted | A user deleted asset(s) from a folder |
asset_version | A user uploaded a new asset version |
asset_property | A user edited metadata of asset(s) |
asset_add_lightbox | A user added asset(s) to a lightbox |
asset_remove_lightbox | A user removed asset(s) from a lightbox |
lightbox_share | A user shared a lightbox with you |
lightbox_sharedelete | A user removed a shared lightbox |
comment | A user commented on a lightbox |
message | Site admin sent a message |
user_registered | A new user registered |
download_request | A user/visitor is requesting to download an asset |
GET /notifications?limit=20&offset=0
Curl curl https://apiv2.webdamdb.com/notifications?limit=20&offset=0
Example Response Status: 200 OK
|
API Reference
Field | Description |
---|---|
artist | Artist |
bitspersample | Bits Per Sample |
colorspace | Color Space |
componentsconfiguration | Components Configuration |
compressedbitsperpixel | Compressed Bits Per Pixel |
compression | Compression |
contrast | Contrast |
copyright | Copyright |
customrendered | Custom Rendered |
datetime | Date Time |
datetimedigitized | Date Time Digitized |
datetimeoriginal | Date Time Original |
digitalzoomratio | Digital Zoom Ratio |
exifimageheight | Exif Image Length |
exifimagewidth | Exif Image Width |
exifoffset | Exif Offset |
exifversion | Exif Version |
exposurebiasvalue | Exposure Bias Value |
exposuremode | Exposure Mode |
exposureprogram | Exposure Program |
exposuretime | Exposure Time |
filesource | File Source |
flash | Flash |
flashpixversion | Flashpix Version |
fnumber | F Number |
focallength | Focal Length |
gaincontrol | Gain Control |
imagedescription | Image Description |
imagelength | Image Length |
imageniqueid | Image Unique ID |
imagewidth | Image Width |
interoperabilityindex | Interoperability Index |
interoperabilityoffset | Interoperability Offset |
interoperabilityversion | Interoperability Version |
isospeedratings | ISO Speed Ratings |
jpeginterchangeformat | JPEG Interchange Format |
jpeginterchangeformatlength | JPEG Interchange Format Length |
lightsource | Light Source |
make | Make |
makernote | Maker Note |
maxaperturevalue | Max Aperture Value |
meteringmode | Metering Mode |
model | Model |
orientation | Orientation |
photometricinterpretation | Photometric Interpretation |
pixelxdimension | Pixel X Dimension |
pixelydimension | Pixel Y Dimension |
planarconfiguration | Planar Configuration |
primarychromaticities | Primary Chromaticities |
printimagematching | Print Image Matching |
referenceblackwhite | Reference Black White |
relatedsoundfile | Related SoundFile |
resolutionunit | Resolution Unit |
rowsperstrip | Rows Per Strip |
samplesperpixel | Samples Per Pixel |
saturation | Saturation |
scenecapturetype | Scene Capture Type |
sharpness | Sharpness |
software | Software |
stripbytecounts | Strip Byte Counts |
stripoffsets | Strip Offsets |
subsectime | Sub Sec Time |
subsectimedigitized | Sub Sec Time Digitized |
subsectimeoriginal | Sub Sec Time Original |
tainted | Tainted |
transferfunction | Transfer Function |
usercomment | User Comment |
whitebalance | White Balance |
whitepoint | White Point |
winxp-author | WinXP-Author |
winxp-comments | WinXP-Comments |
winxp-keywords | WinXP-Keywords |
winxp-subject | WinXP-Subject |
winxp-title | WinXP-Title |
xresolution | X Resolution |
ycbcrcoefficients | YCbCr Coefficients |
ycbcrpositioning | YCbCr Positioning |
ycbcrsubsampling | YCbCr SubSampling |
yresolution | Y Resolution |
Field | Description |
---|---|
byline | By-line |
bytitle | By-line title |
caption | Caption/Abstract |
captionwriter | Writer/Editor |
category | Category |
city | City |
contact | Contact |
copyright | Copyright notice |
countrycode | Country/Primary location |
countryname | Country name |
creatoradrext | Creator address |
creatoradrpcode | Creator postal code |
creatorcity | Creator city |
creatorcountry | Creator country |
creatoremailwrk | Creator email |
creatorregion | Creator state |
creatortelwrk | Creator phone |
creatorurlwrk | Creator website |
credate | Date created |
credit | Credit |
cretime | Time created |
customfield1 | Custom field 1 |
customfield2 | Custom field 2 |
customfield3 | Custom field 3 |
customfield4 | Custom field 4 |
customfield5 | Custom field 5 |
customfield6 | Custom field 6 |
customfield7 | Custom field 7 |
customfield8 | Custom field 8 |
customfield9 | Custom field 9 |
customfield10 | Custom field 10 |
customfield11 | Custom field 11 |
customfield12 | Custom field 12 |
customfield13 | Custom field 13 |
customfield14 | Custom field 14 |
customfield15 | Custom field 15 |
customfield16 | Custom field 16 |
customfield17 | Custom field 17 |
customfield18 | Custom field 18 |
customfield19 | Custom field 19 |
customfield20 | Custom field 20 |
datesent | Date sent |
editstatus | edit status |
fixture | Fixture identifier |
headline | Headline |
imagetype | Image type |
intelgenre | Intellectual genre |
isocountrycode | ISO country code |
keyword | Keywords |
label | label |
language | Language identifier |
marked | Marked |
objectname | Object name |
orgprg | Originating program |
orgtransref | Original transmission reference |
orientation | Image orientation |
prgver | Program version |
rating | Rating |
reldate | Release date |
reltime | Release time |
rightsusageterms | Rights usage terms |
scene | Scene |
source | Source |
specinstr | Special instructions |
state | Province/State |
subcategory | Supplemental category |
subfile | Subfile |
subjectcode | Subject code |
sublocation | Sublocation |
timesent | Time sent |
urgency | Urgency |
usageterms | Usage terms |
webstatement | Copyright info URL |
Brand Connect
GET /brandconnect/brandportals
Curl curl https://apiv2.webdamdb.com/brandconnect/brandportals
Example Response Status: 200 OK
|
GET /brandconnect/brandportals/:brandportal_id/assets
Curl curl https://apiv2.webdamdb.com/brandconnect/brandportals/8765/assets?offset=0&limit=1000
Parameters
Example Response Status: 200 OK
|
GET /brandconnect/brandportals/:brandportal_id/folders/:folder_id/assets
Curl curl https://apiv2.webdamdb.com/brandconnect/brandportals/8765/folders/1366711/assets?offset=0&limit=1000
Parameters
Example Response Status: 200 OK
|
PUT /brandconnect/brandportals/:brandportal_id/assets/:asset_id
Curl curl https://apiv2.webdamdb.com/brandconnect/brandportals/8765/assets/37721161 -X PUT
curl https://apiv2.webdamdb.com/brandconnect/brandportals/8765/assets -d '{"asset_ids": ["37721161", "37721162", "37721163"]}' -X PUT
Status: 200 OK
Status: 400 Bad Request
|
DELETE /brandconnect/brandportals/:brandportal_id/assets/:asset_id
Curl curl https://apiv2.webdamdb.com/brandconnect/brandportals/8765/assets/37721161 -X DELETE
curl https://apiv2.webdamdb.com/brandconnect/brandportals/8765/assets -d '{"asset_ids": ["37721161", "37721162", "37721163"]}' -X DELETE
Status: 200 OK
Status: 400 Bad Request
|
Embeddables
Attribute | Type | Description |
---|---|---|
type | string | This is equal to "embeddables" |
id | long | The unique id of the embeddable. |
asset_id | long | The asset id for the embeddable. |
name | string | Name of the embeddable. |
status | string | Status of the embeddable. |
datecreated | long | The unix timestamp of the date the embeddable was created. |
GET /embeddables/downloads/links
Curl curl https://apiv2.webdamdb.com/embeddables/downloads/links?user_filter=currentuser&offset=0&limit=50
Parameters
Example Response Status: 200 OK
|
GET /embeddables/downloads/links/37759664
Curl curl https://apiv2.webdamdb.com/embeddables/downloads/links/37759664
Example Response Status: 200 OK
|
Updated
Comments
7 comments
Is there a method to retrieve an assets in a given format and size or download an asset based on a given preset?
Hi Lee- Thank you so much for reaching out. Your customer success manager, Scott, will be reaching out to you directly about this. Thanks!
Bump. Was there ever a solution provided for the above question?
Hi Keith,
Currently, the Original file is the only file type that may be retrieved using the Rest API.
Thanks for the feature idea! I'm passing it on to our product team.
I also recommend that you add your idea to our customer community so other users can vote on it. You can add the idea at: Ideas & Suggestions. We monitor all the suggestions and ideas very closely.
Does anyone have a successful example of the file upload in PHP? When I get to Step 2, I keep getting a "SignatureDoesNotMatch" response from AWS. My variable dump looks like they match, but clearly I'm missing something.
Hi Kevin,
In order to further assist you, I'd like to verify that all of the necessary parameters are being entered correctly.
1. Verify that the request being made is a 'PUT' request
2. Make sure you're getting the exact Presigned URL from step 1, and making the PUT request in step 2 exactly to that URL
3. Verify that whatever value you've put for content type in step 1 is sent in step 2
The content type is sent as a header in step 2 and matches exactly what is in step 1.
If you still receive this response. Please submit a support ticket and we will be happy to further assist you with this process!
Best,
Are there any pitfalls with "Notifications" REST API endpoint?
I'm trying to get the notifications but no luck.
The endpoint returning empty notification list, such that
(
[last_read] => 2019-07-30 06:44:02
[offset] => 0
[limit] => 20
[total] => 0
[notifications] => Array
(
)
)
Tried different actions such as uploading/approving an asset, updating an asset to a new version, deleting an asset.
Can anyone help me with that?
Thanks!
Article is closed for comments.