Uploading files

Uploading a file to your Skyfish account is a multi-step operation.

Register the upload

POST /upload/register with the folder the file should be placed in and, optionally, a URL to redirect to when the upload is done:

{
  "folder": 1337,
  "redirectURL": "http://www.myservice.com/upload-done"
}

The API returns everything needed to upload the file: the endpoint to post it to, the encoding type and the fields to post along with it. The document is a direct representation of an HTML form (some values truncated):

{
  "action": "https://colourbox-upload.s3-eu-west-1.amazonaws.com",
  "enctype": "multipart/form-data",
  "method": "POST",
  "fields": [
    { "name": "success_action_redirect", "value": "http://api.colourbox.com/upload/done?redirect=http%3A%2F%2Fwww.myservice.com%2Fupload-done", "type": "hidden" },
    { "name": "key", "value": "upload/777/33/${filename}", "type": "hidden" },
    { "name": "X-Amz-Storage-Class", "value": "REDUCED_REDUNDANCY", "type": "hidden" },
    { "name": "X-Amz-Credential", "value": "AKIAJFHN67ZGNWA...", "type": "hidden" },
    { "name": "X-Amz-Algorithm", "value": "AWS4-HMAC-SHA256", "type": "hidden" },
    { "name": "X-Amz-Date", "value": "20170601T080641Z", "type": "hidden" },
    { "name": "Policy", "value": "eyJleHBpcmF0aW9uI...", "type": "hidden" },
    { "name": "X-Amz-Signature", "value": "cb56a851d7321e8fa90f...", "type": "hidden" },
    { "name": "file", "type": "file" }
  ]
}

Upload the file

Make a multipart POST to the action URL. Post all fields, in the received order. The file goes in the file field, which must be the last field – everything after it is ignored.

The structure is optimized for HTML form generation. If you are not a browser and don’t set the filename in the Content-Disposition of the file field, substitute ${filename} in the field values with the filename yourself.
Finalize the upload

The upload POST redirects to a URL that finalizes the upload. If your client follows redirects, this happens automatically. Otherwise make a GET request to the Location header of the upload response.
- If you registered a redirectURL, the API redirects there with the media ID in the query string as media_id.
- Otherwise the API returns the media ID as JSON:
```
{ "media_id": 456756 }
```
Follow the import

After finalizing, the media is sent to Colourbox’ import service, which extracts information from it and creates thumbnails, previews, etc. Follow the progress with GET /media/:media_id: you get 202 with the progress in percent while the media is being imported, and 200 with a representation of the media when it is done.

Extracted metadata

The API extracts information from the uploaded media’s EXIF data and makes it searchable. Only the first matching field is used.

Field	Extracted from
`title`	XMP:title, IPTC:Headline, IPTC:ObjectName, IPTC:Caption-Abstract
`description`	XMP:Description, EXIF:ImageDescription, IPTC:Caption-Abstract
`keywords`	IPTC:Keywords
`copyright`	IPTC:CopyrightNotice
`photographer`	IPTC:ByLine, IPTC:ByLineTitle

Some of the metadata can be changed afterwards with POST /media/:id/metadata.