Adding a file
Added by IBM contributorIBM | Edited by Melissa M Mahoney on August 21, 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 your library.
You can use one or more of these headers.

You can use one or more of these input parameters. Separate multiple parameters with an ampersand (&).

A file consists of both the information about the file, which is also known as metadata, and the binary data that the file contains. You can provide either of the following inputs:

  • Binary data and no Atom entry document to define the metadata. Metadata is created automatically and sets all values to the default values, except for the value of the title element, which it takes from the SLUG header.
  • Atom entry document that defines the metadata of the file and no binary data.

Authentication

This method requires authentication. To create a document, the current user must be the owner of the library or an administrator. To see if the current user may create a document in a library, use the Retrieve a library API with the "acls" parameter equal to "true", and check the element for the "AddChild" flag.

For external user, it can not create public files in Connetions.

POST a media resource

Note: You may need to set a header or send a request parameter to bypass CSRF protection if the file you are uploading has the "text/plain" mime type.

Input
Method URI Description
POST /files/{auth}/api/myuserlibrary/feed Adds a file to your library.
POST /files/{auth}/api//library/{library-id}/feed Create a document in the root of the library.
POST /files/{auth}/api//communitylibrary/{community-id}/feed Create a document in the root of the community library
Content Type: text/plain
Name Type Optional Description
auth
enumerated No the authorization protocol which is being used
Authorized values:
  • basic
  • oauth
Name Type Optional Description
commentNotification
enumerated Yes String. Specifies whether you want to get a notification when someone adds or updates a comment on a file. Options are on or off. The default value is on.
Authorized values:
  • on
  • off
created
number Yes Date to use as the creation date of the file. Specify the time in the number of milliseconds since January 1, 1970, 00:00:00 GMT time. This value can be set by the user, and defaults to the current system time on the server.
includePath
boolean Yes Boolean. Specifies whether you want to show the file path to the file. if true , adds an entry extension <td:path> element that specifies the file path to the object. Options are true or false.
mediaNotification
string Yes String. Specifies whether the person updating the file wants to get a notification when someone subsequently updates the file. Options are on or off. The default value is off.
modified
number Yes Date to use as the last modified date of the file. Specify the time in the number of milliseconds since January 1, 1970, 00:00:00 GMT time. This value can be set by the user, and defaults to the current system time on the server.
propagate
boolean Yes Indicates if users that are shared with can share this document.
When a file is private, and if you specify true, then other users can \share this file. If you specify false, then only the owner can share this file with others. If the file is public, this flag is considered to be true until the file is made private again.
The default value is false.
sharePermission
enumerated Yes Defines the level of permission that the people listed in the sharedWith parameter have to the file. Only applicable if the sharedWith parameter is passed. Permission level options are Edit or View. The default value is View.
Authorized values:
  • Edit
  • View
shareSummary
string Yes Text. Explanation of the share
shareWith
string Yes User ID of the user to share the content with. This parameter can be applied multiple times. Supports multivalue.
tag
string Yes String. Keyword that helps to classify the file. This parameter can be applied multiple times if multiple tags are passed. Supports multivalue.
visibility
enumerated Yes Specifies who can see the file. Options are private or public. A public file is visible to all users and can be shared by all users. The default value is private.
Authorized values:
  • private
  • public
draft
enumerated Yes String. Indicates whether the resource is persisted as a Draft instead of a Document.
Default value is false.
Authorized values:
  • true
  • false
doctype
string No String. Specifies the document type to be applied to the resource. This will take precedence over the documenttype included in the ATOM entry if specified. You can specify the UUID of the document type or it will default to the type identified by the system.
includePropertySheets
enumerated Yes String. When set to true, <snx:field> elements will be included in the entry for propertysheet properties on the documenttype.
Default value is false.
Authorized values:
  • true
  • false
replace
enumerated Yes String. Indicates if the resource should be overwritten if already exists on the server.
Default value is false.
Authorized values:
  • true
  • false
submit
enumerated Yes String. Indicates if the resource should be submitted for approval if approval is enabled on server.
Default value is false.
Authorized values:
  • true
  • false
lock
enumerated Yes String. Indicates if the resource needs to be locked on the server prior to update.
Default value is false.
Authorized values:
  • true
  • false
sendEmail
boolean Yes String. Only take effect when shareWith is not null and indicates if an email notification will be sent when sharing to the specified user.
Default value is true.
includeLocked
boolean Yes Boolean. If true, adds an entry extension <td:locked> showing if document is locked. This parameter takes a boolean value of either true or false.
Default value is false.
includeLockOwner
boolean Yes Boolean. If true, adds an entry extension <td:lockOwner> showing who holds the lock. This parameter takes a boolean value of true or false, and the default value is false.
createVersion
boolean Yes Boolean. Indicates whether to create a version of the document as it is saved (many implementations will choose to only respect this param if the file content has changed).
Default value is false.
label
string Yes String. The label of the file to be created.
Note: The label parameter takes precedence over the Slug header if both are specified.
restrictedVisibility
enumerated Yes String. Indicates if this document's visibility is restricted to private only. A value of 'true' means the document can only be private. False means the value can be any valid visibility value. No change if not passed.
The default value is false.
Authorized values:
  • true
  • false
  • null
favorite
enumerated Yes String. Specify if this document will be added into favorite.
The default value is false.
Authorized values:
  • true
  • false
primaryCollection
string Yes String. Create a document in a folder.
addToCollection
string Yes String. Share the document to the folder with read access. Supports multivalue.
shareWithCommunity
string Yes String. Share the document to the specified community with read access. Supports multivalue.
addToCollectionWithEdit
string No String. Share the document to a folder with edit access. Supports multivalue.
shareWithCommunityWithEdit
string Yes String. Share the document to the specified community with edit access. Supports multivalue.
encrypt
enumerated Yes String. Specify whether to encrypt the file when uploading.
Default value is false.
Authorized values:
  • true
  • false
externalResourceType
enumerated Yes String. Type of resource that is related to this document.
Authorized values:
  • microblog
  • ibmdoc
externalResourceUrl
string Yes String. URL of the external resource.
externalResourceId
string Yes String. ID of external resource.
updatedVia
enumerated Yes String. Indicates which channel the document is created in. If not specified, files would be taken as default value, which means it is created via Connections Files.
Authorized values:
  • files
  • verse
  • docs.auto
  • docs.manual
  • filesync
sync
boolean Yes Boolean. When a document is created and sync=true then add the document to file sync. This is not done for community files.
Default value is false.
Name Type Optional Description
Content-Language
string Yes Specifies the language of the content being sent to the server. All contents are handled using UTF-8 encoding on the server.
Content-Length
string Yes Specifies the content length when sending media content.
Slug
string No Contains the file path and label of the resource to be added to the collection. You can include non-ASCII characters in this header, but they must be properly encoded according to the RFC 2047.
X-Update-Nonce
string Yes String. Represents a unique data string generated by the server upon request that you can provide to secure the request. See Getting a nonce key for information about how to request the data string.
Authorization
enumerated No The authentication mechanism selected by your application to access the API.
Basic is the Base64 encoding of the IBM Connections Cloud username and password: Base64(username:password). For example, Base64(twatson@us.ibm.com:password).
Bearer is the oauth 2.0 access token that is generated when the user grants your application access to IBM Connections Cloud services.
See the reference topic "OAuth 2.0 APIs for web server flow" for more information.
Authorized values:
  • bearer
  • basic
Content-Type
string Yes Used to specify the Mime type for the content being sent to the server. If the collection does not support the specified content type, the server will return HTTP response code 415 (Unsupported media type). When a media resource is POSTed the mime-type of the resource will be set to this value if it is provided. Otherwise, the mime-type of the extension of the Slug/document label will be returned. A Content-Type that is an empty string, whitespace only, or equal to "unknown/unknown" is considered to be not-specified.
Output
Content Type: application/atom+xml
Code Description
201
Indicates that the file entry was successfully created. If an error occurs, this header contains one of the error codes.
401
Unauthorized.
403
Forbidden.
404
Not Found.
409
Conflict.
415
Unsupported Media Type.
References
Examples
Example request to create a document in a collection

POST /files/basic/api/library/46ebf3b4-d0a1-4ca3-ac47-113589b801ee/feed?title=testCreateDocument_sameName_personalDocument_public_1__14386706895801111&label=testCreateDocument_sameName_personalDocument_public_1__14386706895801111&visibility=public&primaryCollection=bafcfc47-77af-486f-9263-96f88436d6c9

 

<entry xmlns="http://www.w3.org/2005/Atom">
   <content type="text">testCreateDocument_sameName_personalDocument_public_1__14386706895801111</content>
</entry>

Response returned by the server
HTTP/1.1 201 Created

 

<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:d0cc10d0-c302-4099-aa88-dc25bea55b77</id>
   <td:uuid xmlns:td="urn:ibm.com/td">d0cc10d0-c302-4099-aa88-dc25bea55b77</td:uuid>
   <td:label xmlns:td="urn:ibm.com/td">testCreateDocument_sameName_personalDocument_public_1__14386706895801111</td:label>
   <link href="https://filesvm005.cn.ibm.com:9443/files/basic/api/library/46ebf3b4-d0a1-4ca3-ac47-113589b801ee/document/d0cc10d0-c302-4099-aa88-dc25bea55b77/entry" rel="self"></link>
   <link href="https://filesvm005.cn.ibm.com:9443/files/app/file/d0cc10d0-c302-4099-aa88-dc25bea55b77" rel="alternate" type="text/html"></link>
   <link href="https://filesvm005.cn.ibm.com:9443/files/basic/api/library/46ebf3b4-d0a1-4ca3-ac47-113589b801ee/document/d0cc10d0-c302-4099-aa88-dc25bea55b77/entry" rel="edit"></link>
   <link href="https://filesvm005.cn.ibm.com:9443/files/basic/api/library/46ebf3b4-d0a1-4ca3-ac47-113589b801ee/document/d0cc10d0-c302-4099-aa88-dc25bea55b77/media" rel="edit-media"></link>
   <link href="https://filesvm005.cn.ibm.com:9443/files/basic/anonymous/api/library/46ebf3b4-d0a1-4ca3-ac47-113589b801ee/document/d0cc10d0-c302-4099-aa88-dc25bea55b77/media/testCreateDocument_sameName_personalDocument_public_1__14386706895801111" rel="enclosure" type="text/plain" title="testCreateDocument_sameName_personalDocument_public_1__14386706895801111" hreflang="en" length="36"></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://filesvm005.cn.ibm.com:9443/files/basic/api/library/46ebf3b4-d0a1-4ca3-ac47-113589b801ee/document/d0cc10d0-c302-4099-aa88-dc25bea55b77/feed" rel="replies" type="application/atom+xml" thr:count="0"></link>
   <td:notifications xmlns:td="urn:ibm.com/td">
      <td:media xmlns:td="urn:ibm.com/td">on</td:media>
      <td:comment xmlns:td="urn:ibm.com/td">on</td:comment>
   </td:notifications>
   <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">testCreateDocument_sameName_personalDocument_public_1__14386706895801111</title>
   <published>2015-08-04T06:45:56.954Z</published>
   <updated>2015-08-04T06:45:56.954Z</updated>
   <td:created xmlns:td="urn:ibm.com/td">2015-08-04T06:45:56.954Z</td:created>
   <td:modified xmlns:td="urn:ibm.com/td">2015-08-04T06:45:56.954Z</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">46ebf3b4-d0a1-4ca3-ac47-113589b801ee</td:libraryId>
   <td:libraryType xmlns:td="urn:ibm.com/td">personalFiles</td:libraryType>
   <td:isSyncable xmlns:td="urn:ibm.com/td">false</td:isSyncable>
   <td:versionUuid xmlns:td="urn:ibm.com/td">f31472e9-c789-4b30-accf-15c9ce486faf</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:totalMediaSize xmlns:td="urn:ibm.com/td">36</td:totalMediaSize>
   <summary type="text"></summary>
   <content type="text/plain" src="https://filesvm005.cn.ibm.com:9443/files/basic/api/library/46ebf3b4-d0a1-4ca3-ac47-113589b801ee/document/d0cc10d0-c302-4099-aa88-dc25bea55b77/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>