TwentyThree Developer APIAPI Method: /api/file/upload

API Method: /api/file/upload

Last updated on September 2, 2016.

Upload a design,.

Parameters

ParameterDescription
file (required)The file to upload. (Note that this parameter − neither the filename nor the file content − shouldn't be included in the api signature.)
filenameOptional file name to use when storing the file.
object_idOptional integer identifier of the object the file is related to, for example a theme or a player.
image_pBoolean indicating whether this should be rescaled as an image or not. Default is 0
Allowed values: 0 or 1
max_widthMaximum width during image rescaling.
min_widthMinimum width during image rescaling.
max_heightMaximum height during image rescaling.
min_heightMinimum height during image rescaling.

Parameters for Resumable.js

This API method support an extra set of parameters designed to work with Resumable.js, an open sourced JavaScript library for providing multiple simultaneous, stable, fault-tolerant and resumable uploads via the HTML5 File API released by TwentyThree.

To handle the state of upload chunks, a number of extra parameters are sent along with such requests:

  • resumableChunkNumber: The index of chunk in the current upload. First chunk is 1 (no base-0 counting here).
  • resumableChunkSize: The chunk size in bytes.
  • resumableTotalSize: The total file size in bytes.
  • resumableIdentifier: A unique identifier for the file contained in the request.

API methods expect all chunks of a file to be uploaded before the file is added to the archive. When the last chunk's upload completes, the messages listed in the Returns section applies. For all other chunk, HTTP status codes control the flow:

  • 200: The chunk was accepted and correct. No need to re-upload.
  • 500: The file for which the chunk was uploaded is not supported, cancel the entire upload.
  • Anything else: Something went wrong, but try reuploading the file.

Permission level

The minimum required permission level is:

write

Example XML Response

<response status="ok" permission_level="admin" message="The file was uploaded" cached="0">
  <url>/files/image.png</url>
  <filename>image.png</filename>
</response>

Example JSON Response

{
  "status": "ok", 
  "message":"The file was uploaded",
  "permission_level":"admin",
  "cached":"0",
  "file":{
    "url": "/files/image.png", 
    "filename": "image.png"
  },
  "p": "1",
  "size": "1",
  "site": {...},
  "endpoint": "/api/file/upload"
}