Bynder Upload Assets API

{"openapi":"3.1.0","info":{"title":"Upload Assets API","version":"1.0.0"},"servers":[{"url":"https://{your-bynder-domain}/"}],"paths":{"/api/upload/endpoint":{"get":{"summary":"Get closest AmazonS3 upload endpoint","description":"Get the closest AmazonS3 upload endpoint.","security":[{"OAuth2":["MEDIAUPLOAD","MEDIAUPLOADFORAPPROVAL"]},{"permanentToken":["MEDIAUPLOAD","MEDIAUPLOADFORAPPROVAL"]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"string","example":"https://bynder-public-eu-central-1.s3.amazonaws.com/"}}}}}}},"/api/upload/init":{"post":{"summary":"Initialise upload","description":"Initialise an upload.","security":[{"OAuth2":["MEDIAUPLOAD","MEDIAUPLOADFORAPPROVAL"]},{"permanentToken":["MEDIAUPLOAD","MEDIAUPLOADFORAPPROVAL"]}],"requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"filename":{"type":"string","example":"image.jpeg"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"s3file":{"type":"object","properties":{"uploadid":{"type":"string","example":"UPLOAD_ID"},"targetid":{"type":"string","example":"final/00000000-0000-0000-0000-000000000000/image.jpeg"}}},"s3_filename":{"type":"string","example":"pluploads/api/00000000-0000-0000-0000-000000000000/image.jpeg"},"target_key":{"type":"string","example":"pluploads/api/00000000-0000-0000-0000-000000000000/image.jpeg"},"multipart_params":{"type":"object","properties":{"acl":{"type":"string","example":"private"},"success_action_status":{"type":"string","example":"201"},"Content-Type":{"type":"string","example":"image/*"},"key":{"type":"string","example":"pluploads/api/00000000-0000-0000-0000-000000000000/image.jpeg"},"Policy":{"type":"string","example":"AWS_S3_POLICY"},"X-Amz-Signature":{"type":"string","example":"AWS_S3_SIGNATURE"},"x-amz-credential":{"type":"string","example":"AWS_S3_AUTH"},"x-amz-algorithm":{"type":"string","example":"AWS4-HMAC-SHA256"},"x-amz-date":{"type":"string","example":"20160216T100755Z"}}}}}}}},"400":{"description":"Invalid input","content":{"text/plain":{"schema":{"type":"string","example":{"filename":"'image' is not a valid filename"}}}}}}}},"/api/v4/upload/{id}":{"post":{"summary":"Register uploaded chunk","description":"Register the completion of an uploaded chunk.","security":[{"OAuth2":["MEDIAUPLOAD","MEDIAUPLOADFORAPPROVAL"]},{"permanentToken":["MEDIAUPLOAD","MEDIAUPLOADFORAPPROVAL"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"T3.fS5.5HPhtYFtm2b_.e7wVe910tL5XQutKw1jkMqlP5cPQVyZkOZxZ9lJiGUk4FIw6M0CFZ3xogTWrm.GPI2p2CaglQcAS5aH37zT_vHJnbtkebYbheXIQc_.M_6hM"}}],"requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"chunkNumber":{"type":"number","description":"required for every chunk","example":5},"targetid":{"type":"string","description":"required for every chunk","example":"final/00000000-0000-0000-0000000000000000/Logo.png"},"filename":{"type":"string","description":"required for every chunk","example":"api_uploads/00000000-0000-0000-0000000000000000/00000000-0000-0000-0000000000000000/Logo.png/p5"},"s3_filename":{"type":"string","description":"required in the final call","example":"api_uploads/159D8D4B-B981-49B8-BF0569FD144CB359/A29FABF0-26B8-44BF-890920E4C09E7C11/Logo.png"},"chunks":{"type":"number","description":"required in the final call","example":5},"original_filename":{"type":"string","description":"required in the final call","example":"Logo.png"}}}}}},"responses":{"202":{"description":"Chunk registered successfully","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":"Only for chunk registration","example":"ok"},"output":{"type":"string","example":"final/2ba07d00-586a-4a44-b13c-c58598cfe828/"},"batchId":{"type":"string","example":"00000000-0000-0000-0000000000000000"},"file":{"type":"object","properties":{"bucket":{"type":"string","example":"BUCKET"},"path":{"type":"string","example":"final/2ba07d00-586a-4a44-b13c-c58598cfe828/IMG_1874.JPG"},"type":{"type":"string","example":"s3"}}},"filename":{"type":"string","example":"final/2ba07d00-586a-4a44-b13c-c58598cfe828/IMG_1874.JPG"},"importId":{"type":"string","example":"000000000-0000-0000-0000000000000000"},"locationType":{"type":"string","example":"s3"},"success":{"type":"integer","example":1}}}}}},"500":{"description":"Upload failed or not ready","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Could not complete upload"},"retry":{"type":"integer","example":1},"success":{"type":"boolean","example":false}}}}}}}}},"/api/v4/upload/poll":{"get":{"summary":"Retrieve poll state","description":"This call needs to be executed in a loop until its response returns the item(s) id(s) passed in the **items** parameter.\n","security":[{"OAuth2":["MEDIAUPLOAD","MEDIAUPLOADFORAPPROVAL"]},{"permanentToken":["MEDIAUPLOAD","MEDIAUPLOADFORAPPROVAL"]}],"parameters":[{"in":"query","name":"items","required":true,"schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000,00000000-0000-0000-0000-000000000000"},"description":"Comma-separated import id's of a finalised file, as returned by the finalise call."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"examples":{"success":{"summary":"Successful response","value":{"itemsDone":["00000000-0000-0000-0000000000000000"],"itemsFailed":[],"itemsRejected":[]}}}}}}}}},"/api/v4/media/save/{importId}":{"post":{"summary":"Save as a new asset","description":"For metaproperties that use options (Select, Select2, Autocomplete), modifying an asset's metaproperty options should be done via option UUID's for the API to work optimally, sending name or label values will be deprecated in the future. Other metaproperties (Date, Text and Longtext), values can be submitted directly.\n","security":[{"OAuth2":["MEDIAUPLOAD","MEDIAUPLOADFORAPPROVAL"]},{"permanentToken":["MEDIAUPLOAD","MEDIAUPLOADFORAPPROVAL"]}],"parameters":[{"in":"path","name":"importId","required":true,"schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"description":"Import id of a finalised and processed upload to be saved."}],"requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Brand id to save the asset to.","example":"00000000-0000-0000-0000-0000000000000000"},"name":{"type":"string","description":"Name of the asset.","example":"Asset name"},"description":{"type":"string","description":"Extended asset description.","example":"Extended asset description"},"copyright":{"type":"string","description":"Copyright information of the asset.","example":"Copyright (c) Example corp."},"tags":{"type":"string","description":"Comma-separated list of tags of the asset.","example":"scenery,grassland,Holland"},"metaproperty":{"type":"string","description":"Dictionary with (metaproperty) options to set on the asset. Send fields as `metaproperty.METAPROPERY_ID` with a string of all its (metaproperty) options ids comma-separated.\n","example":"metaproperty.00000000-0000-0000-0000000000000000=00000000-0000-0000-0000000000000000,00000000-0000-0000-0000000000000000"},"categories":{"type":"string","description":"Comma-separated category ids of the asset.","example":"00000000-0000-0000-0000000000000000,00000000-0000-0000-0000000000000000"},"audit":{"type":"boolean","description":"Flags if the asset should be sent to the waiting room.","example":true},"isPublic":{"type":"boolean","description":"Flags if the asset should be Public.","example":true},"accessRequestId":{"type":"string","description":"If audit is set to `true` you can specify an accessRequestId to batch uploads to the waiting room. The accessRequestId is retrieved in the response of this endpoint, after you save the first asset of your batch.\n","example":"00000000-0000-0000-0000000000000000"},"requestorId":{"type":"string","description":"If audit is set to `true` you can specify a requestor ID (user ID) to identify the user uploading the asset to the waiting room.\n","example":"00000000-0000-0000-0000000000000000"},"accessType":{"type":"string","description":"If audit is set to `true` you can specify an access type to define to which waiting room location the asset is uploaded to. The available locations are: Upload, Edit, Workflow approval (export), Shutterstock and Stock.\n","enum":["upload","edit","export","shutterstock","stock"],"example":"upload"},"ISOPublicationDate":{"type":"string","format":"date-time","description":"Date/time of publication in ISO08601-format.","example":"2014-06-12T14:53:21-04:00"},"publicationDate":{"type":"string","description":"*DEPRECATED* Date/time of publication in linked API user selected locale-format.\n","example":"05-31-2010"},"archiveDate":{"type":"string","format":"date-time","description":"Archive date/time of the asset in ISO8601-format.","example":"2014-12-25T10:30:00Z"},"watermarkDate":{"type":"string","format":"date-time","description":"Watermark datetime. ISO8601 format: yyyy-mm-ddThh:mm:ssZ.\n","example":"2014-12-25T10:30:00Z"},"crc32":{"type":"integer","description":"CRC32 checksum of the original file, used for verification.","example":79764919}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"examples":{"success":{"summary":"Successful response","value":{"accessRequestId":"00000000-0000-0000-0000000000000000","mediaid":"00000000-0000-0000-0000000000000000","batchId":"00000000-0000-0000-0000000000000000","success":true,"mediaitems":[{"original":"final/00000000-0000-0000-0000000000000000/image.jpg","destination":"___URL_TO_BYNDER_CDN___"},{"original":"final/00000000-0000-0000-0000000000000000/thul-image.jpg","destination":"___URL_TO_BYNDER_CDN___"},{"original":"final/00000000-0000-0000-0000000000000000/mini-image.jpg","destination":"___URL_TO_BYNDER_CDN___"}]}}}}}},"303":{"description":"Import not converted yet, please poll","content":{"application/json":{"examples":{"poll":{"summary":"Poll response","value":{"message":"Import not converted yet, please poll","statuscode":"303"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"examples":{"noImportId":{"summary":"No importId provided","value":{"message":"No importid provided","statuscode":"400"}},"noBrandId":{"summary":"No brandId provided","value":{"message":"No brandid provided","statuscode":"400"}},"invalidCrc32":{"summary":"Invalid unsigned integer for CRC32","value":{"message":"Invalid unsigned integer for CRC32","statuscode":"400"}},"invalidCrc32Type":{"summary":"Invalid argument type for CRC32","value":{"message":"Invalid argument type for CRC32","statuscode":"400"}},"invalidDateFormat":{"summary":"Date format not ISO8601-compliant","value":{"message":"Date format not ISO8601-compliant","statuscode":"400"}}}}}},"403":{"description":"Access denied","content":{"application/json":{"examples":{"accessDenied":{"summary":"Access denied response","value":{"message":"Access denied","statuscode":"403"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"examples":{"importIdNotFound":{"summary":"Import ID not found","value":{"message":"Import ID not found","statuscode":"404"}},"uploadNotExist":{"summary":"Upload doesn't exist","value":{"message":"Upload doesn't exist","statuscode":"404"}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"examples":{"uploadFailed":{"summary":"Upload failed or not ready","value":{"message":"Upload failed or not ready","statuscode":"500"}}}}}}}}},"/api/v4/media/{id}/save/{importId}":{"post":{"summary":"Save as a new asset version","security":[{"OAuth2":["MEDIAUPLOAD","MEDIAUPLOADFORAPPROVAL"]},{"permanentToken":["MEDIAUPLOAD","MEDIAUPLOADFORAPPROVAL"]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","example":"00000000-0000-0000-0000000000000000"},"description":"Asset id for which to save the new version."},{"in":"path","name":"importId","required":true,"schema":{"type":"string","example":"00000000-0000-0000-0000000000000000"},"description":"Import id of a finalised and processed upload to be saved."}],"requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"examples":{"success":{"summary":"Successful response","value":{"mediaid":"00000000-0000-0000-0000000000000000","batchId":"00000000-0000-0000-0000000000000000","success":true,"mediaitems":[{"original":"final/00000000-0000-0000-0000000000000000/image.jpg","destination":"___URL_TO_BYNDER_CDN___"},{"original":"final/00000000-0000-0000-0000000000000000/thul-image.jpg","destination":"___URL_TO_BYNDER_CDN___"},{"original":"final/00000000-0000-0000-0000000000000000/mini-image.jpg","destination":"___URL_TO_BYNDER_CDN___"}]}}}}}}}}}},"components":{"securitySchemes":{"permanentToken":{"type":"apiKey","in":"header","name":"Authorization"},"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://{your-bynder-domain}/v6/authentication/oauth2/token","scopes":{"MEDIAUPLOAD":"","MEDIAUPLOADFORAPPROVAL":""}},"authorizationCode":{"authorizationUrl":"https://{your-auth-url}","tokenUrl":"https://{your-bynder-domain}/v6/authentication/oauth2/token","scopes":{"MEDIAUPLOAD":"","MEDIAUPLOADFORAPPROVAL":""}}}}}}}