File Lifecycle
Endpoints:
- Create a file or placeholder
- Update file metadata
- Upload derivatives of a file
- Complete a placeholder file
- Delete a file
- Delete multiple files
For an explanation of how to attach files to other objects, read How To File.
POST /files
Token:
Scope:
Create a file placeholder or a complete file. By default, the file will be private.
If creating a file placeholder, it can be form data or a Content-Type of application/json
.
If creating a complete file the Content-Type must be multipart/form-data
, and the content
key must be the file.
POST Body Data
Name | Description |
---|---|
content |
Required (if uploading in a single step) Key of the uploaded file |
type |
Required Reverse domain name-style identifier of the file type. E.g., com.example.site . Searchable |
name |
256-character name or description (to be displayed and attached to the object; a random key will actually be assigned for the filename). If not included, name of file uploaded will be used |
kind |
One of: other , image (for JPEG, GIF, PNG), audio (for WAVE, MP3, FLAC. up to 52428800 bytes), video (for MP4, MOV, M4V, WEBM). If the file extension is known and kind=other , the file extension will override other appropriately. |
is_public |
If true, file is public. Default false |
sha256 * |
API will check the file's SHA256 checksum against this, and return an error if they do not match |
mime_type |
If the API cannot determine mime_type, it will use this |
{name} + _image_thumb_200s |
Key for custom derived thumbnail, 200 by 200 pixels, resized and cropped. If not included, API will try to create one, for images. |
{name} + _image_thumb_960r |
Key for custom derived thumbnail, within 640 width and 960 height. If an uploaded image has smaller proportions, one will not be created automatically. |
process_image_exif * |
If uploading a JPEG image with EXIF, and this is set to 0 , the API will not re-orient the image automatically. |
raw |
Embedded raw values. |
- If the API automatically rotates an image, the returned
sha256
will be different from the uploaded file.
Example
curl "https://api.pnut.io/v1/files" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d "{
\"type\":\"com.example.site\",
\"name\":\"That Thing!\",
\"kind\":\"other\"
}" \
-X POST \
-H "X-Pretty-Json: 1"
Returns the created file details
{
"meta": {
"code": 201
},
"data": {"...File Object..."}
}
PATCH /files/{file_id}
Token:
Scope:
Update a file's details.
If a file is ever made public, it could be accessed by others indefinitely using a previously-exposed file_token_read
, or for a while after via the cache. To make a public file relatively secure again, delete it and upload it again as a new file.
POST Body Data
Name | Description |
---|---|
name |
256-character name or description (to be displayed and attached to the object) |
is_public |
True or false |
raw |
Embedded raw values. Not deleted unless explicitly set to empty values for each type. |
URL Parameters
Name | Description |
---|---|
file_id |
ID of the file to update |
Example
curl "https://api.pnut.io/v1/files/73" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d "{
\"name\":\"butternut squash\"
}" \
-X PUT \
-H "X-Pretty-Json: 1"
Returns the updated file
{
"meta": {
"code": 200
},
"data": {"...File Object..."}
}
PUT /files/{file_id}/content/{derived_key}
Token:
Scope:
Upload a new derivative file. You may only do this with an existing file placeholder (an incomplete file).
This is particularly useful if you want to include alternative versions of a file, such as different sizes of images, custom thumbnails instead of auto-generated thumbnails, or different music or video formats of a file.
URL Parameters
Name | Description |
---|---|
file_id |
ID of the file placeholder to create a derivative file for |
derived_key |
Multipart key to the file. Keys starting with core_ are reserved. core_image_200s and core_image_960r can be set, but have to be 200x200 pixels and within 640x960 respectively, and the same mime type as file_id . |
Example
curl "https://api.pnut.io/v1/files/69/content/core_image_200s" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "X-Pretty-Json: 1"
Returns 204 on success
-
PUT /files/{file_id}/content
Token:
Scope:
Set a file placeholder's content. You may only do this with an incomplete file.
URL Parameters
Name | Description |
---|---|
file_id |
ID of the file to set contents for |
Example
curl "https://api.pnut.io/v1/files/75/content" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-F "content=@somethingtoupload.jpg" \
-X PUT
Returns 204 on success
DELETE /files/{file_id}
Token:
Scope:
Delete a file. This will not disassociate a file with any other objects (posts, messages...).
URL Parameters
Name | Description |
---|---|
file_id |
ID of the file to delete |
Example
curl "https://api.pnut.io/v1/files/72" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-X DELETE \
-H "X-Pretty-Json: 1"
Returns the deactivated file
{
"meta": {
"code": 200
},
"data": {"....File Object..."}
}
DELETE /files
Token:
Scope:
Delete a list of files. This will not disassociate a file from any other objects (posts, messages...).
Because deleting files can take some time, the API call will return the list of files confirmed for deletion, and an endpoint to check the status of the operation.
Look at the operation status endpoint for more info.
Query Parameters
Name | Description |
---|---|
ids |
Comma-separated list of file IDs. Up to 200 at a time. |
Example
curl "https://api.pnut.io/v1/files?ids=5,35,6426,18259,18242" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-X DELETE \
-H "X-Pretty-Json: 1"
Returns a list of files to attempt to delete, and a status endpoint to check status.
{
"meta": {
"code": 202,
"status_url": "https://api.pnut.io/v1/sys/ops/ecfd4a43-4d75-4bea-8881-7a1194bedfdc"
},
"data": [
"5",
"6426"
]
}