Downloading a file
Added by IBM contributorIBM | Edited by IBM contributorElizabeth Bowling on November 9, 2015
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars2 comments

Download a file from 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 (&).

Note: You will output the binary content of the file. If active content filtering is enabled, and the file is an HTML file, it is filtered.

Note: This API can return a HTTP1.1/ 302 redirect if a different download domain is configured. When a different download domain is configured, the client needs be able to follow the redirect to eventually download the file.

To download using the public endpoint, use /basic/anonymous/api.


This method does not require authentication to retrieve public resources. If authentication is provided, the user must have 'View' authority on the specified resource.

Method URI Description
GET /files/{auth}/api/myuserlibrary/document/{document-id}/media
Determine the resource address in either of the following ways:
Value of the href attribute of the <link rel="edit-media"> element in the file's Document Atom entries.
Construct the address using the following URL:/{auth}/api/myuserlibrary/document/{document-id}/ where {document-id} is the <td:uuid> or <td:label> element of the document entry.
Returns a file from your library. This request requires authentication.
Note: Use this URI to retrieve the binary data if you plan to update and return it using a PUT request.
GET /files/{auth}/api/library/{library-id}/document/{document-id-or-label}/media/{filename} Retrieve a document given its id.

A server may choose to optionally append the file label with proper URL encoding at the end of the media URL. The label is not necessary in order to retrieve the file. Files are identified by unique identifier exclusively in order to preserve addressibility after a rename.
Name Type Optional Description
string No {document-id} is the <td:uuid> or <td:label> element of the document entry.
enumerated No The authorization protocol being used by your application to access Connections Cloud.
Authorized values:
  • basic
  • oauth
Name Type Optional Description
boolean Yes Specifies whether the documents contents should be included inline in the content element. Options are true or false.
boolean Yes Specifies whether to log this file download. Options are true or false. By default, it does log the download.
Name Type Optional Description
string Yes Used to validate the local cache of the feed and entry documents retrieved previously. If the feed or entry has not been modified since the specified date, HTTP response code 304 (Not Modified) is returned.
string Yes Contains an ETag response header sent by the server in a previous request to the same URL. If the ETag is still valid for the specified resource, HTTP response code 304 (Not Modified) is returned.
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(
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: text/html
Code Description
Indicates that the file entry was successfully downloaded. If an error occurs, this header contains one of the error codes.
Not Found.
GET /files/basic/api/library/5d06ab0044ed8129bd5ebd4caeec5df1/document/5d06ab0044ed8129bd5ebd4caeec5df2/media HTTP/1.1 
User-Agent: Thingio/1.0

Response returned by the server
Binary file contents
Noam Gal commented on Nov 15, 2015

Re: Downloading a file

Sorry, the oAuth does not work. My bad.

It appears to fall back to "form" whenever I write something in the {auth} placeholder that is not "oauth" or "basic".

And I keep on getting 403 - FORBIDDEN (not unauthorized, it was a mistake), even though I am sending the proper Authorization Bearer.

Do I need to add any specific permission on my oAuth app somehow, for the download to work?

Noam Gal commented on Nov 15, 2015

Re: Downloading a file

The fileUrl field, coming from the Activities Feed JSON reply, has a "form" Authorized value, so I guess that is another option to use.

More importantly - when I tried replacing it with 'oauth', I kept getting 403 - UNAUTHORIZED. Only after changing it to oAuth (Capital 'A'), I got it to work. I'd recommend fixing the documentation to emphasize the proper value to send.