POST/desk/api/v2/files/ref.json

POST_v2_files_ref.json

Uploading files to Desk is a 3-step process

First, you need to create an authorization using /v2/files/ref.json It expects a full disclosure of what's intended to be uploaded

Request:


	{
	    "type": "attachment",
	    "filename": "the_file_name.jpeg",
	    "mimeType": "image/jpeg",
	    "disposition": "attachment"
	}

We will return an URL and a list of parameters that need to be sent along with the file

Response:


	{
	   "url": "http://url/",
	   "params": {
	       "Content-Type": "image/jpeg",
	       "bucket": "A_NAME",
	       "key": "A_VALUE_FOR_LATER",
	       "policy": "A_LONG_STRING",
	       "success_action_status": "201",
	       "x-amz-algorithm": "AWS4-HMAC-SHA256",
	       "x-amz-credential": "A_VALUE",
	       "x-amz-date": "ANOTHER_VALUE",
	       "x-amz-signature": "ANOTHER_LONG_STRING"
	   },
	   "file": {
	       "id": FILE_ID,
	       "mimeType": "image/jpeg",
	       "fileName": "the_file_name.jpeg",
	       "size": 0,
	       "disposition": "attachment",
	       "type": "attachment",
	       "createdAt": "2019-03-14T11:53:38.103518Z",
	       "updatedAt": "2019-03-14T11:53:38.103518Z",
	       "createdBy": {
	           "id": 1,
	           "type": "users"
	       },
	       "updatedBy": {
	           "id": 1,
	           "type": "users"
	       },
	       "state": "temp"
	   }
	}

Any tampering will cause the upload request to fail

Uploading the file with curl


	curl -X POST \
	  http://url/ \
	  -H ': ' \
	  -H 'cache-control: no-cache' \
	  -F Content-Type=image/jpeg \
	  -F key=A_VALUE_FOR_LATER \
	  -F policy=A_LONG_STRING \
	  -F success_action_status=201 \
	  -F x-amz-algorithm=AWS4-HMAC-SHA256 \
	  -F x-amz-credential=A_VALUE \
	  -F x-amz-date=ANOTHER_VALUE \
	  -F x-amz-signature=ANOTHER_LONG_STRING \
	  -F file=@YOUR_FILE_PATH \
	  -F bucket=A_NAME

Response:

<?xml version="1.0" encoding="UTF-8"?>
<PostResponse>

	<Bucket>A_NAME</Bucket>
	<Key>A_VALUE_FOR_LATER</Key>
	<ETag>SOME_STRING</ETag>
	<Location>/A_NAME/A_VALUE_FOR_LATER</Location>

</PostResponse>

Finally, you need to tell desk that the file has been uploaded

PATCH /v2/files/{FILE_ID}.json

Response:

	{
	    "file": {
	        "id": FILE_ID,
	        "mimeType": "image/jpeg",
	        "fileName": "the_file_name.jpeg",
	        "size": 14358,
	        "disposition": "attachment",
	        "type": "attachment",
	        "URL": "",
	        "createdAt": "2019-03-12T13:40:25.135843Z",
	        "updatedAt": "2019-03-12T13:40:25.135843Z",
	        "createdBy": {
	            "id": 1,
	            "type": "users"
	        },
	        "updatedBy": {
	            "id": 1,
	            "type": "users"
	        },
	        "state": "active"
	    }
	}

Body Params

File represents a File.

    • Name
      createdAt
      Type
      string
      Description
      CreatedAt is a read-only date marking the creation time.
    • Name
      createdBy
      Type
      object
    • Name
      customer
      Type
      object
    • Name
      deletedAt
      Type
      string
      Description
      DeletedAt is a read-only date marking the time of deletion. Is only returned when the object is marked as deleted.
    • Name
      deletedBy
      Type
      object
    • Name
      disposition
      Type
      string
      Description
      Determine where the attachment was added: attachment or attachment-inline
    • Name
      downloadURL
      Type
      string
      Description
      The URL from where the file can be downloaded
    • Name
      filename
      Type
      string
      Description
      The file name as originally submitted
    • Name
      filter_args
      Type
      object
      Description
      RequestCommons allows specifying paging and sorting options. All API endpoints should embed the RequestOrder for consistency.
    • Name
      id
      Type
      integer
    • Name
      mimeType
      Type
      string
      Description
      Standard mime type of the file
    • Name
      pixelHeight
      Type
      integer
    • Name
      pixelWidth
      Type
      integer
    • Name
      proxyKey
      Type
      string
      Description
      Proxy key is a required key passed in to ensure that the user has permission to view the file
    • Name
      s3Path
      Type
      string
    • Name
      size
      Type
      integer
      Description
      The file size in byes
    • Name
      state
      Type
      string
      Description
      State is the status of the object. Typically this will be either active or deleted. When deleted the `deletedAt` and `deletedBy` relationship will be returned.
    • Name
      type
      Type
      object
      Description
      FileType uploaded file type
    • Name
      updatedAt
      Type
      string
      Description
      UpdatedAt is a read-only date marking the last updated time. This field is not updated when the object is deleted.
    • Name
      updatedBy
      Type
      object

    Responses

    • Code
      201
      Type
      object
      Schema
      Description
      201 Created
    • Code
      400
      Type
      object
      Schema
      Description
      400 Bad Request
      Validator hold the validation errors. Typically you shouldn't create this directly but use the New() function.

    Examples

    201 Created

    fileRefResponse
    {
      "file": {
        "createdAt": "2024-04-16T16:34:31.508Z",
        "createdBy": {
          "delete": true,
          "id": 0,
          "meta": {},
          "type": 0
        },
        "customer": {
          "delete": true,
          "id": 0,
          "meta": {},
          "type": 0
        },
        "deletedAt": "2024-04-16T16:34:31.508Z",
        "deletedBy": {
          "delete": true,
          "id": 0,
          "meta": {},
          "type": 0
        },
        "disposition": "string",
        "downloadURL": "string",
        "filename": "string",
        "filter_args": {
          "aggregate": {
            "Distinct": true,
            "Field": "string",
            "Operation": "string"
          },
          "bulkDryExecute": true,
          "fields": [
            "string"
          ],
          "filter": [
            "string"
          ],
          "id": 0,
          "ids": [
            0
          ],
          "includes": [
            "string"
          ],
          "orderBy": "string",
          "orderMode": "asc",
          "page": 0,
          "pageOffset": 0,
          "pageSize": 0,
          "skipAggregation": true
        },
        "id": 0,
        "mimeType": "string",
        "pixelHeight": 0,
        "pixelWidth": 0,
        "proxyKey": "string",
        "s3Path": "string",
        "size": 0,
        "state": "string",
        "type": {
          "ContentTypes": [
            "string"
          ],
          "MaxSize": 0,
          "Name": "string"
        },
        "updatedAt": "2024-04-16T16:34:31.508Z",
        "updatedBy": {
          "delete": true,
          "id": 0,
          "meta": {},
          "type": 0
        }
      },
      "params": {
        "additionalProp": "string"
      },
      "url": "string"
    }