POST /v1/spaces/:space_id/documents

Upload a file and create a document object, returns the newly created document body and its location.

Important Note: If the file you are sending is larger than 500MB in size, you must direct your request to https://bigfiles.assembla.com instead of https://api.assembla.com in order to bypass the standard API’s 500MB filesize limit.

Note regarding timeouts: In order to ensure the performance and uptime of both the standard API and the bigfiles API, Assembla does implement a timeout setting to prevent connections from remaining open for too long. If you are reaching this timeout, please contact support for assistance.

Params

To upload a file using the API add the Content-Type multipart/form-data header to your request headers, no JSON or XML data bodies is supported during file creation. Pass folder_name parameter to upload a file to a specific folder.

All params should be sent in the document namespace, e.g.:

document[file]=_file_data&document[name]=file name&...

Examples

For example purposes we use a query string body, suppose the file is located in /home/max/myfile.

document[file]=@/home/max/myfile

Request XML, using cURL utility:

curl -i -H "Authorization: Bearer _token" -F "document[file]=@/home/max/myfile" https://bigfiles.assembla.com/v1/spaces/_space_id/documents.xml

Response

HTTP/1.1 201 Created
Server: nginx/0.8.55
Date: Fri, 20 Jul 2012 12:55:38 GMT
Content-Type: application/xml; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Status: 201
Location: http://api.assembla.com/v1/spaces/_space_id/documents/_id
...

<?xml version="1.0" encoding="UTF-8"?>
<document>
  <attachable-type nil="true"></attachable-type>
  <created-by>bgnP_qA1Gr2QjIaaaHk9wZ</created-by>
  <description nil="true"></description>
  <ticket-id nil="true"></ticket-id>
  <position type="integer">0</position>
  <filesize type="integer">3778</filesize>
  <url>https://www.assembla.com/spaces/_space_id/documents/_id/download/_id</url>
  <filename>Gemfile</filename>
  <cached-tag-list></cached-tag-list>
  <attachable-guid nil="true"></attachable-guid>
  <name>Gemfile</name>
  <version type="integer">1</version>
  <updated-by>bgnP_qA1Gr2QjIaaaHk9wZ</updated-by>
  <created-at type="datetime">2012-07-20T12:55:38Z</created-at>
  <updated-at type="datetime">2012-07-20T12:55:38Z</updated-at>
  <content-type>application/octet-stream</content-type>
  <id>a0gWEI0MOr4zI_adbNA33N</id>
  <has-thumbnail type="boolean">false</has-thumbnail>
  <space-id>b89TL8MYWr4id7adbNA33N</space-id>
  <attachable-id nil="true"></attachable-id>
</document>

Request JSON, using cURL utility:

curl -i -H "Authorization: Bearer _token" -F "document[file]=@home/max/file" https://bigfiles.assembla.com/v1/spaces/_space_id/documents.json

Response

HTTP/1.1 201 Created
Server: nginx/0.8.55
Date: Fri, 20 Jul 2012 14:03:49 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Status: 201
Location: http://api.assembla.com/v1/spaces/_space_id/documents/_id
...

{
  "attachable_type":null,
  "created_by":"bgnP_qA1Gr2QjIaaaHk9wZ",
  "description":null,
  "ticket_id":null,
  "position":0,
  "filesize":3778,
  "url":"http://www.assembla.com/spaces/_space_id/documents/_id/download/_id",
  "filename":"Gemfile",
  "cached_tag_list":"",
  "attachable_guid":null,
  "name":"Gemfile",
  "version":1,
  "updated_by":"bgnP_qA1Gr2QjIaaaHk9wZ",
  "created_at":"2012-07-20T14:03:48Z",
  "updated_at":"2012-07-20T14:03:48Z",
  "content_type":"application/octet-stream",
  "id":"c6DkHO0Nmr4zI_adbNA33N",
  "has_thumbnail":false,
  "space_id":"b89TL8MYWr4id7adbNA33N",
  "attachable_id":null
}

Uploading a file to a folder:

curl -i -H "Authorization: Bearer _token" -F "document[file]=@/home/max/myfile" -F "folder_name=some_folder" https://bigfiles.assembla.com/v1/spaces/_space_id/documents.xml

JSON is formatted here for readability, in a real response JSON body is inline with no indentation.

Note: pay attention to Location header, this is the URL where newly created resource is located, you can GET on this URL to access this resource.

Note: Extract from cURL documentation about -F flag

(HTTP) This lets curl emulate a filled-in form in which a user has pressed the submit button. This causes curl to POST data using the Content-Type multipart/form-data according to RFC 2388. This enables uploading of binary files etc. To force the ‘content’ part to be a file, prefix the file name with an @ sign. To just get the content part from a file, prefix the file name with the symbol <. The difference between @ and < is then that @ makes a file get attached in the post as a file upload, while the < makes a text field and just get the contents for that text field from a file.

Description for each field: document object fields reference