Skip to main content

pages/{pageid}/files/{filename}/properties/{key} (PUT)


Update an existing attachment property

  • REST Method: PUT
  • Method Access: public

Uri Parameters

Name Type Description
key string A unique identifier for a property that is obtained through GET:files/{fileid}/properties
fileid int identifies a file by ID

Query Parameters

Name Type Description
description string? Description of property
etag string? Etag of the current version of the property. Can alternatively be provided via ETag header.
authenticate bool? Force authentication for request (default: false)
redirects int? If zero, do not follow page redirects.
abort {never, modified, exists}? Specifies condition under which to prevent the update; default is modified.

Return Codes

Name Value Description
OK 200 The request completed successfully
Bad Request 400 Invalid input parameter or request body
Forbidden 403 UPDATE access is required
Not Found 404 Requested file and/or property could not be found

Message Format

Response is the standard property XML

<property name="{text}" href="{uri}" etag="{text}">
  <contents type="{text}" href="{uri}">{text}</contents>
  <user.modified id="{int}" href="{uri}">

Implementation Notes

  • The response XML will contain the contents text only for text based mimetypes with values less than 2048 chars in length. Otherwise the contents is available at the URI pointed to by property/contents/@href.
  • UPDATE rights to the parent page of a file is necessary to create or change a file property value. READ access is required to get the properties and its metadata.

Curl Sample: Modify an Attachment Property

The following command binds the data in file "ping" to property "foo" of attachment "bar" in page "pong".

Sample Code

curl -u username:password -H "Content-Type: text/plain" -H "Etag: xxx" -T ping -i http://mindtouch.address/@api/deki/pages/=pong/files/=bar/properties/foo

Implementation notes 

curl flags

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 file
Specifies a PUT request and the file to send.
Replaces or appends an HTTP header. The "Content-Type" header specifies the MIME type of the value attached to the property.
Includes the HTTP response header in the output. Useful for debugging.


UPDATE permission is required to execute above command. Otherwise, a 403 HTTP response (Forbidden) will be returned.


Properties can contain any type of file, therefore it is important to specify the correct MIME when creating a property. For instance, a text property will require a text/plain header, xml will require application/xml header, a jpeg image will require image/jpg header, and so on.


An ETag is required to ensure the property being modified is in its most recent revision. If there is an ETag mismatch, the server will return a 409 HTTP response (Conflict). There are two ways to pass ETags to the server. The first, adding an ETag HTTP header, is shown above. ETags can also be passed via appending a parameter to the end of the path. The following is equivalent to the above sample:
curl -u username:password -H "Content-Type: text/plain" -T ping -i http://mindtouch.address/@api/deki/pages/=pong/files/=bar/properties/foo?etag=xxx


An attachment has been deemed copyrighted, thus we want to change its property, "iscopyright", to yes. The file name is fu.jpg on page FUBAR.


Content-Type: text/plain


Sample Code

curl -u admin:password -H "Content-Type: text/plain" -H "Etag: 106.r1_ts2010-01-21T19:50:41Z" -T attachprop.txt -i

HTTP Response Headers

HTTP/1.1 200 OK
Date: Thu, 21 Jan 2010 19:54:52 GMT
Server: Dream-HTTPAPI/ Microsoft-HTTPAPI/2.0
Content-Length: 675
Content-Type: application/xml; charset=utf-8
X-Data-Stats: request-time-ms=145; mysql-queries=13; mysql-time-ms=88;
X-Deki-Site: id="default"
Via: 1.1 dekiwiki

HTTP Response Body

Content-Type: application/xml

<?xml version="1.0"?>
<property name="iscopyright" href="" etag="106.r2_ts2010-01-21T19:54:52Z">
  <contents type="text/plain" size="3" href="">yes</contents>
  <user.modified id="1" href="">


  • To view a page's attachments and properties (including the property ETags), access the page attachment's raw XML data. For instance, in the above example, the XML data would be located here
  • The page path is double encoded. In the above example, spaces in "Jean Luc Picard" are replaced with %2520.
  • Was this article helpful?