Skip to main content
NICE CXone Expert

We will be closed on Wednesday, December 25th in observance of Christmas

Expert Success Center

files/{fileid}/description (PUT)

  1. Last updated
  2. Save as PDF

Overview

Update attachment description

  • REST Method: PUT
  • Method Access: public

Uri Parameters

Name Type Description
filename string Double uri-encoded file name. Should be prefixed with "=" if it does not have an extension.
fileid int identifies a file by ID
pageid string either an integer page ID, "home", or "=" followed by a double uri-encoded page title

Query Parameters

Name Type Description
authenticate bool? Force authentication for request (default: false)
redirects int? If zero, do not follow page redirects (only applies when {pageid} is present).

Return Codes

Name Value Description
OK 200 Request completed successfully
Bad Request 400 Invalid input parameter or request body
Forbidden 403 Update access to the page is required
Not Found 404 Requested file could not be found

Message Format

Input:
Content-type=text/plain

Output:

<file id="{int}" href="{uri}">
    <filename>{text}</filename> 
    <description>{text}</description> 
    <contents type="{mimetyp e}" size="{int}" width="{int}" height="{int}" href="{uri}" /> 
    <contents.preview rel="thumb" type="{mimetype}" maxwidth="{int}" maxheight="{int}" href="{uri}" /> 
    <contents.preview rel="webview" type="{mimetype}" maxwidth="{int}" maxheight="{int}" href="{uri}" /> 
    <date.created>{date}</date.created> 
    <user.createdby id="{int}" href="{uri}">
        <nick>{text}</nick> 
        <username>{text}</username> 
        <email>{text}</email> 
    </user.createdby>
    <revisions count="{int}" href="{uri}" /> 
    <page.parent id="{int}" href="{uri}">
        <title>{text}</title> 
        <path>{text}</path> 
    </page.parent>
</file>

Implementation Notes

Use GET:files/{fileid}/description to retrieve the file description.

C# Sample: Set File Description

The following code example sets the description of the file with ID 456:

Sample Code

Plug p = Plug.New("http://help.mindtouch.us/@api/deki");
p.At("users", "authenticate").WithCredentials("admin", "password").Get();
DreamMessage msg = DreamMessage.Ok(MimeType.TEXT, "File description text");
p.At("files", "456", "description").Put(msg);

Sample Response from executing Code

<file id="456" href="http://help.mindtouch.us/@api/deki/files/456/info">
    <filename>myfile.jpg</filename> 
    <description>File description text</description> 
    <contents type="image/pjpeg" size="53112" width="476" height="480" href="http://help.mindtouch.us/@api/deki/files/456" /> 
    <contents.preview rel="thumb" type="image/pjpeg" maxwidth="160" maxheight="160" href="http://help.mindtouch.us/@api/deki/files/456?size=thumb" /> 
    <contents.preview rel="webview" type="image/pjpeg" maxwidth="550" maxheight="550" href="http://help.mindtouch.us/@api/deki/files/456?size=webview" /> 
    <date.created>2007-08-27T19:59:24Z</date.created> 
    <user.createdby id="1" href="http://help.mindtouch.us/@api/deki/users/1">
        <nick>Admin</nick> 
        <username>Admin</username> 
        <email>admin@mindtouch.com</email> 
    </user.createdby>
    <revisions count="2" href="http://help.mindtouch.us/@api/deki/files/456/revisions" /> 
    <page.parent id="29" href="http://help.mindtouch.us/@api/deki/pages/29">
        <title>DekiWiki (Hayes)</title> 
        <path /> 
    </page.parent>
</file>

Curl Sample: Set File Description

The following curl command will set or replace a description of a file according to its fileid (42, in the example). The description string is read out of file "description.txt".

Sample Code

curl -u username:password -T description.txt -i http://192.168.168.110/@api/deki/files/42/description

Implementation notes 

curl flags

-u
Basic HTTP authentication. Sends a username and password to server so it can verify whether a user is of privilege to perform specific operation.
-T
Sends a file using the PUT command.
-i
Includes the HTTP response header in the output. Useful for debugging.
 

Example

An image with image id 9 exists. We want to change its description to something generic, like "image 9". The file generic.txt contains the description we want to set.

generic.txt

Content-Type: text/plain

image 9

Sample Code

curl -u username:password -T generic.txt -i http://192.168.168.110/@api/deki/files/9/description

HTTP Response Headers

HTTP/1.1 200 OK
Date: Mon, 11 Jan 2010 20:26:05 GMT
Server: Dream-HTTPAPI/1.7.2.17433
X-Deki-Site: id="default"
Content-Type: application/xml; charset=utf-8
Content-Length: 2129
Via: 1.1 dekiwiki

HTTP Response Body

Content-Type: application/xml

<?xml version="1.0"?>
<file id="9" href="http://192.168.168.110/@api/deki/files/9/info">
  <filename>captain.jpg</filename>
  <description>image 9</description>
  <contents type="application/octet-stream" size="495835" width="1691" height="2343" href="http://192.168.168.110/@api/deki/files/9/=captain.jpg"/>
  <contents.preview rel="thumb" type="image/jpeg" maxwidth="160" maxheight="160" href="http://192.168.168.110/@api/deki/files/9/=captain.jpg?size=thumb"/>
  <contents.preview rel="webview" type="image/jpeg" maxwidth="550" maxheight="550" href="http://192.168.168.110/@api/deki/files/9/=captain.jpg?size=webview"/>
  <date.created>2010-01-08T23:44:16Z</date.created>
  <user.createdby id="1" href="http://192.168.168.110/@api/deki/users/1">
    <nick>Admin</nick>
    <username>Admin</username>
    <email>melder@mindtouch.com</email>
    <hash.email>637b79dca5c8ebdc4347bccca42d3487</hash.email>
    <uri.gravatar>http://www.gravatar.com/avatar/637b79dca5c8ebdc4347bccca42d3487</uri.gravatar>
  </user.createdby>
  <revisions count="3" totalcount="3" href="http://192.168.168.110/@api/deki/files/9/revisions"/>
  <page.parent id="51" href="http://192.168.168.110/@api/deki/pages/51?redirects=0">
    <uri.ui>http://192.168.168.110/Jean_Luc_Picard</uri.ui>
    <title>Jean Luc Picard</title>
    <path>Jean_Luc_Picard</path>
    <namespace>main</namespace>
  </page.parent>
  <properties count="1" href="http://192.168.168.110/@api/deki/files/9/properties">
    <property name="urn:deki.mindtouch.com#description" href="http://192.168.168.110/@api/deki/files/9/properties/urn%253adeki.mindtouch.com%2523description/info" etag="29.r1_ts2010-01-11T20:26:04Z">
      <contents type="text/plain; charset=utf-8" size="7" href="http://192.168.168.110/@api/deki/files/9/properties/urn%253adeki.mindtouch.com%2523description">image 5</contents>
      <date.modified>2010-01-11T20:26:04Z</date.modified>
      <user.modified id="1" href="http://192.168.168.110/@api/deki/users/1">
        <nick>Admin</nick>
        <username>Admin</username>
        <email>melder@mindtouch.com</email>
        <hash.email>637b79dca5c8ebdc4347bccca42d3487</hash.email>
        <uri.gravatar>http://www.gravatar.com/avatar/637b79dca5c8ebdc4347bccca42d3487</uri.gravatar>
      </user.modified>
    </property>
  </properties>
</file>

Notes

  • Running the command on an existing description will overwrite it.

 

  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Article type
    Reference
  2. Tags
    This page has no tags.