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.
201 Created
fileRefResponse
{
"file": {
"createdAt": "2024-11-07T20:32:32.492Z",
"createdBy": {
"delete": true,
"id": 0,
"meta": {
"additionalProp": "Unknown Type: any"
},
"type": 0
},
"customer": {
"delete": true,
"id": 0,
"meta": {
"additionalProp": "Unknown Type: any"
},
"type": 0
},
"deletedAt": "2024-11-07T20:32:32.492Z",
"deletedBy": {
"delete": true,
"id": 0,
"meta": {
"additionalProp": "Unknown Type: any"
},
"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-11-07T20:32:32.492Z",
"updatedBy": {
"delete": true,
"id": 0,
"meta": {
"additionalProp": "Unknown Type: any"
},
"type": 0
}
},
"params": {
"additionalProp": "string"
},
"url": "string"
}