API Method: /api/photo/get-upload-token

Name: Twentythree Web Team
Price range: $

Pre-authenticate an upload, allowing your client to upload directly to TwentyThree's servers from a web browser.

This method can be used to pre-authenticated uploads to a site without proxying them through your servers and the API. The flow is described in detail in the Browser-based uploads section of the API documentation, but in general terms this method will return a token which can be included in a standard HTML form to upload photos or videos directly to TwentyThree's servers.

Parameters

Parameter	Description
`return_url`	The URL where the user is return after both upload success and failure. See the Flow section for more information. The callback is a GET request when permitted (when the return data is less than 1500 chars) and a POST in all other cases; so your callback handler needs to accept both GET and POST. If `return_url` is empty or omitted, the request will return a simple HTTP 200 OK mesage.
`background_return_p`	Return to the callback url in the background. If this parameter is set to `1` the upload request will not redirect the client directly back to `return_url`. Instead, a request is made to `return_url` from the TwentyThree servers and a plain text document in returned containing status information. This option is design for uploading through clients wuch as Adobe Flash, where a client-side redirected might not be honoured. (The background callback takes the form of a HTTP GET request with a maximum length of 1500 chars.)
`user_id`	The user's ID. If no user ID is given, the objects will be uploaded anonymously. Requires `super`, otherwise files are uploaded using the authenticated user.
`album_id`	A album (or channel) ID. Multiple values should be comma-separated.
`title`	A title for the upload. All HTML tags will be stripped away from the title.
`description`	A description of upload. The value can include save HTML tags such as <b> or <p>; however, if any disallowed tags are included, all html with be stripped from the description.
`tags`	Space-separated list of tags to attach to the uploaded file.
`publish`	Should the file be published in the site immediately? Default is `1`. Valid values: `0` or `1`
`absolute_url`	If the uploaded photo or video is to be associated with a different canonical URI from the on assigned by default, set it here.
`valid_minutes`	How many minutes should the upload token be valid for. The default is `180` minutes (or 3 hours). The minimum value is 15 minutes and the maximum is 24 hours.
`max_uploads`	How many files can be uploaded using the returned token. The default is `1` upload; the maximum is 100

In addition to the standard parameters, any custom variable configured for photo objects can be set using the variable key as a parameter.

Any extra parameters sent to this method will be repeated in the callback request to return_url (if given).

Permission level

The minimum required permission level is:

write

Example XML Response

<response status="ok" permission_level="write" 
  message="The upload token is ready to use" cached="0">
  <upload_token>022fe6e3fb42758d6147c539727c5358af3524b1</upload_token>
  <title>A title for the new upload</title>
  <description>... and a prelimiary description</description>
  <publish>1</publish>
  <tags>product:1234, testemonial</tags>
  <user_id>17488</user_id>
  <album_id></album_id>
  <max_uploads>1</max_uploads>
  <valid_minutes>180</valid_minutes>
  <valid_until>1266711372</valid_until>
  <return_url>http://www.example.com/upload/callback?theme=green</return_url>
</response>

Example JSON Response

{
  "status": "ok", 
  "message":"The upload token is ready to use",
  "permission_level":"write",
  "cached":"0",
  "uploadtoken":{
    "valid_minutes": "180", 
    "description": "... and a prelimiary description", 
    "upload_token": "022fe6e3fb42758d6147c539727c5358af3524b1", 
    "max_uploads": "1", 
    "album_id": "", 
    "return_url": "http://www.example.com/upload/callback?theme=green", 
    "title": "A title for the new upload", 
    "valid_until": "1266713254", 
    "publish": "1", 
    "tags": "product:1234, testemonial",
    "user_id": "17488"
  },
  "p": "1",
  "size": "1",
  "site": { ... },
  "endpoint": "/api/photo/get-upload-token"
}

The callback

The callback URL is defined by the return_url parameter, and the callback request will always take the form of a HTTP 301 redirect to a GET-style address.

The request will always include the upload_token and domain as a parameter. If the upload succeeded, the parameters photo_id, token, tree_id will be included. On upload failure, the callback includes an error_message parameter. See flow details.