Community articleAdding a file to a folder or multiple folders
Added by IBM contributorIBM on November 9, 2015
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars

Add a file to a folder or multiple folders programmatically.

URL endpoints

This method requires authentication. In order to add an Item to a Collection, the currently authenticated user must be the owner of the Collection, an Administrator, or have been granted AddChild permission on the Collection. To test whether the current user can add an Item to a Collection, use the Get list of members of a specific role of a Collection to see if the user belongs to the Manager or Contributor Roles.

See Authenticating requests for information about how to authenticate the request.
 

{document-id} is the value of the <td:uuid> or <td:label> elements in the file's Atom entry document.
 

Error Codes


The following error codes could appear in a response body for an invalid request:
 

Error Code
Description
Unknown
Returned when the cause of an error is unknown
AccessDenied
Returned when the cause of an error is due to a permission restriction
ItemNotFound
Returned when the cause of an error is related to a resource not being found
ItemExists
Returned when the cause of an error is related to a conflict with an existing resource
UnsupportedOperation
Returned when the operation is not supported

 

Input
Method URI Description
POST /files/library/{library-id}/document/{document-id-or-label}/feed Add the document to collections specified by atom entry or feed.
POST /files/userlibrary/{user-id}/document/{document-id-or-label}/feed Add the document to collections specified by atom entry or feed.
POST /files/myuserlibrary/document/{document-id-or-label}/feed Add the document to collections specified by atom entry or feed.
POST /files/document/{document-id-or-label/feed Add the document to collections specified by atom entry or feed.
Content Type: application/atom+xml
Sample Request:
<?xml version="1.0" encoding="UTF-8"?>

<entry xmlns="http://www.w3.org/2005/Atom" xmlns:td="urn:ibm.com/td">

  <category term="collection" label="collection" scheme="tag:ibm.com,2006:td/type"/>

  <td:itemId>{collection-id}</td:itemId>

  <td:sharePermission>{View|Edit}</td:sharePermission> 

</entry>
Name Type Optional Description
document-id-or-label
string No {document-id-or-label} is the value of the <td:uuid> or <td:label> elements in the file's Atom entry document.
user-id
string Yes The ID of the user.
library-id
string Yes The ID of the library containing the file.
Name Type Optional Description
identifier
enumerated Yes Indicate the identifier used in the document segment of the URL.
Authorized values:
  • uuid
  • label
returnIsMultifiling
enumerated Yes Specify if return property "isMultifiling" of document after adding to the folder.
If true, response will be 200 OK with property "isMultifiling" in document entry.
If false, response will be 204 No Content, the same as other adding document action.
Default value is false.
Authorized values:
  • true
  • false
Name Type Optional Description
Content-Language
string No Used to specify the language for the content being sent to the server. All contents are handled via UTF-8 encoding on the server.
Content-Type
string Yes Used to specify the mime type for the content being sent to the server.
Output
Code Description
204
Indicates that the file was successfully added to the folder or folders. If an error occurs, this header will return an error.
400
Bad Request.
401
Unauthorized.
403
Forbidden.
404
Not Found.
409
Conflict.
500
Internal server error. The server encountered an unexpected condition that prevented it from fulfilling the request.
Examples
POST /library/1234/document/5678/feed HTTP/1.1

<?xml version="1.0" encoding="UTF-8"?>

<feed>

  <entry xmlns="http://www.w3.org/2005/Atom" xmlns:td="urn:ibm.com/td">

    <category term="collection" label="collection" scheme="tag:ibm.com,2006:td/type"/>

    <td:itemId>{collection-id1}</td:itemId>

    <td:sharePermission>{View|Edit}</td:sharePermission> 

  </entry>

  <entry xmlns="http://www.w3.org/2005/Atom" xmlns:td="urn:ibm.com/td">

    <category term="collection" label="collection" scheme="tag:ibm.com,2006:td/type"/>

    <td:itemId>{collection-id2}</td:itemId>

    <td:sharePermission>{View|Edit}</td:sharePermission> 

  </entry>

  <entry xmlns="http://www.w3.org/2005/Atom" xmlns:td="urn:ibm.com/td">

    <category term="collection" label="collection" scheme="tag:ibm.com,2006:td/type"/>

    <td:itemId>{collection-id3}</td:itemId>

    <td:sharePermission>{View|Edit}</td:sharePermission> 

 

  </entry>

</feed>


Response returned by the server
Location: https://www.example.com:9443/files/basic/collection/c85c0979-22cc-46d5-89b8-be69e0afb912/feed

Status Code: 204(no content)
POST /files/basic/api/document/e01b8235-a16e-4efe-b30b-ceda0f6cab42/feed?returnContent=true&includeVisibleCollectionCount=true HTTP/1.1 

 

<entry xmlns:td="urn:ibm.com/td" xmlns="http://www.w3.org/2005/Atom">
   <category term="collection" scheme="tag:ibm.com,2006:td/type" label="collection"></category>
   <td:itemId xmlns:td="urn:ibm.com/td">14e6f7f0-9fab-4e4f-9bbf-4b7bafc24bec</td:itemId>
</entry>

Response returned by the server
HTTP/1.1 200 OK

 
<entry xmlns:td="urn:ibm.com/td" xmlns="http://www.w3.org/2005/Atom" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:snx="http://www.ibm.com/xmlns/prod/sn" xmlns:thr="http://purl.org/syndication/thread/1.0">
   <id>urn:lsid:ibm.com:td:e01b8235-a16e-4efe-b30b-ceda0f6cab42</id>
   <td:uuid xmlns:td="urn:ibm.com/td">e01b8235-a16e-4efe-b30b-ceda0f6cab42</td:uuid>
   <td:label xmlns:td="urn:ibm.com/td">testAddFile_documentEndpoint_multifiling_personalDocument_public_1__1437121305871</td:label>
   <link href="https://filesvm004.cn.ibm.com:9443/files/basic/api/library/ff5eaa2d-c689-4f25-aba5-31e604e90a05/document/e01b8235-a16e-4efe-b30b-ceda0f6cab42/entry" rel="self"></link>
   <link href="https://filesvm004.cn.ibm.com:9443/files/app/file/e01b8235-a16e-4efe-b30b-ceda0f6cab42" rel="alternate" type="text/html"></link>
   <link href="https://filesvm004.cn.ibm.com:9443/files/basic/api/library/ff5eaa2d-c689-4f25-aba5-31e604e90a05/document/e01b8235-a16e-4efe-b30b-ceda0f6cab42/entry" rel="edit"></link>
   <link href="https://filesvm004.cn.ibm.com:9443/files/basic/api/library/ff5eaa2d-c689-4f25-aba5-31e604e90a05/document/e01b8235-a16e-4efe-b30b-ceda0f6cab42/media" rel="edit-media"></link>
   <link href="https://filesvm004.cn.ibm.com:9443/files/basic/anonymous/api/library/ff5eaa2d-c689-4f25-aba5-31e604e90a05/document/e01b8235-a16e-4efe-b30b-ceda0f6cab42/media/testAddFile_documentEndpoint_multifiling_personalDocument_public_1__1437121305871" rel="enclosure" type="text/plain" title="testAddFile_documentEndpoint_multifiling_personalDocument_public_1__1437121305871" hreflang="en" length="81"></link>
   <link href="" rel="thumbnail"></link>
   <category term="document" scheme="tag:ibm.com,2006:td/type" label="document"></category>
   <link xmlns:thr="http://purl.org/syndication/thread/1.0" href="https://filesvm004.cn.ibm.com:9443/files/basic/api/library/ff5eaa2d-c689-4f25-aba5-31e604e90a05/document/e01b8235-a16e-4efe-b30b-ceda0f6cab42/feed" rel="replies" type="application/atom+xml" thr:count="0"></link>
   <author>
      <name>Liz Schonfeld</name>
      <snx:userid xmlns:snx="http://www.ibm.com/xmlns/prod/sn">lschonfeld</snx:userid>
      <email>lschonfeld@renovations.com</email>
      <snx:userState xmlns:snx="http://www.ibm.com/xmlns/prod/sn">active</snx:userState>
   </author>
   <title type="text">testAddFile_documentEndpoint_multifiling_personalDocument_public_1__1437121305871</title>
   <published>2015-07-17T08:21:53.127Z</published>
   <updated>2015-07-17T08:21:53.408Z</updated>
   <td:created xmlns:td="urn:ibm.com/td">2015-07-17T08:21:53.127Z</td:created>
   <td:modified xmlns:td="urn:ibm.com/td">2015-07-17T08:21:53.127Z</td:modified>
   <td:lastAccessed xmlns:td="urn:ibm.com/td"></td:lastAccessed>
   <td:modifier xmlns:td="urn:ibm.com/td">
      <name>Liz Schonfeld</name>
      <snx:userid xmlns:snx="http://www.ibm.com/xmlns/prod/sn">lschonfeld</snx:userid>
      <email>lschonfeld@renovations.com</email>
      <snx:userState xmlns:snx="http://www.ibm.com/xmlns/prod/sn">active</snx:userState>
   </td:modifier>
   <td:visibility xmlns:td="urn:ibm.com/td">public</td:visibility>
   <snx:isExternal xmlns:snx="http://www.ibm.com/xmlns/prod/sn">false</snx:isExternal>
   <td:libraryId xmlns:td="urn:ibm.com/td">ff5eaa2d-c689-4f25-aba5-31e604e90a05</td:libraryId>
   <td:libraryType xmlns:td="urn:ibm.com/td">personalFiles</td:libraryType>
   <td:versionUuid xmlns:td="urn:ibm.com/td">e99f2c72-7a0c-4d6b-a933-3fe96a80f3c9</td:versionUuid>
   <td:versionLabel xmlns:td="urn:ibm.com/td">1</td:versionLabel>
   <td:propagation xmlns:td="urn:ibm.com/td">true</td:propagation>
   <snx:rank xmlns:snx="http://www.ibm.com/xmlns/prod/sn" scheme="http://www.ibm.com/xmlns/prod/sn/recommendations">0</snx:rank>
   <snx:rank xmlns:snx="http://www.ibm.com/xmlns/prod/sn" scheme="http://www.ibm.com/xmlns/prod/sn/comment">0</snx:rank>
   <snx:rank xmlns:snx="http://www.ibm.com/xmlns/prod/sn" scheme="http://www.ibm.com/xmlns/prod/sn/share">0</snx:rank>
   <snx:rank xmlns:snx="http://www.ibm.com/xmlns/prod/sn" scheme="http://www.ibm.com/xmlns/prod/sn/collections">1</snx:rank>
   <snx:rank xmlns:snx="http://www.ibm.com/xmlns/prod/sn" scheme="http://www.ibm.com/xmlns/prod/sn/attachments">0</snx:rank>
   <snx:rank xmlns:snx="http://www.ibm.com/xmlns/prod/sn" scheme="http://www.ibm.com/xmlns/prod/sn/versions">1</snx:rank>
   <snx:rank xmlns:snx="http://www.ibm.com/xmlns/prod/sn" scheme="http://www.ibm.com/xmlns/prod/sn/references">0</snx:rank>
   <td:visibleCollectionCount xmlns:td="urn:ibm.com/td">2</td:visibleCollectionCount>
   <td:totalMediaSize xmlns:td="urn:ibm.com/td">81</td:totalMediaSize>
   <summary type="text"></summary>
   <content type="text/plain" src="https://filesvm004.cn.ibm.com:9443/files/basic/api/library/ff5eaa2d-c689-4f25-aba5-31e604e90a05/document/e01b8235-a16e-4efe-b30b-ceda0f6cab42/media"></content>
   <snx:rank xmlns:snx="http://www.ibm.com/xmlns/prod/sn" scheme="http://www.ibm.com/xmlns/prod/sn/hit">0</snx:rank>
   <snx:rank xmlns:snx="http://www.ibm.com/xmlns/prod/sn" scheme="http://www.ibm.com/xmlns/prod/sn/anonymous_hit">0</snx:rank>
   <td:restrictedVisibility xmlns:td="urn:ibm.com/td">false</td:restrictedVisibility>
   <td:objectTypeName xmlns:td="urn:ibm.com/td">snx:file</td:objectTypeName>
   <td:lock xmlns:td="urn:ibm.com/td" type="NONE"></td:lock>
   <snx:isExternal xmlns:snx="http://www.ibm.com/xmlns/prod/sn">false</snx:isExternal>
</entry>