Skip to Content

TwentyThree™ API

API Method: /api/photo/upload

Upload a new file to the site using a POST request.


file (required for non-placeholder video)The file to upload. (Note that this parameter − neither the filename nor the file content − shouldn't be included in the api signature).
user_idThe 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_idA album (or channel) ID.
titleA title for the upload. All HTML tags will be stripped away from the title.
descriptionA 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.
tagsSpace-separated list of tags to attach to the uploaded file.
publishShould the file be published in the site immediately? Default is 1 (0 or 1)
publish_dateSpecific publish date of the photo or video, either past or future. Expected format is - "YYYY-MM-DD HH:MM:SS". The video will be auto-published if the published_p is 0 and the publish_date is in the future.
absolute_urlIf the uploaded photo or video is to be associated with a different canonical URI from the on assigned by default, set it here.
placeholder_pAdd a placeholder video object. Default is 0 and valid options are 0 or 1.

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

Permission level

The minimum required permission level is:


Example XML Response

<pre><code><?xml version="1.0" encoding="UTF-8"?><response status="ok" permission_level="write" message="The file was successfully uploaded" cached="0"> <photo_id>60432</photo_id> <tree_id>7340</tree_id> <token>7aguzmVuqpwjshwprfegm2swfdcnaWrj</token></response></code></pre>

Example JSON Response

{  "status": "ok",   "message":"The file was successfully uploaded",  "permission_level":"write",  "cached":"0",  "upload":{"photo_id": "60433", "tree_id": "7340",     "token": "7aguzmVuqpwjshwprfegm2swfdcnaWrj"},  "p": "1",  "size": "1",  "site": { ...},  "endpoint": "/api/photo/upload"}