Purging an object and using privileged purge

You can use the HTTP DELETE method to purge all versions of an object from a namespace. You can also use the DELETE method to purge an object that is under retention (privileged purge) if the namespace is configured to allow privileged operations and you have the necessary permissions.

If versioning has never been enabled for the namespace, a purge request deletes the object. If versioning was enabled in the past but is no longer enabled, the purge request deletes all existing versions of the object.

TipIf an object is not under retention, you can use a privileged purge operation to specify a reason for the purge. Although the object is not under retention, the namespace must still support privileged operations, and you need the privileged permission.

Access permission

To purge objects you need both delete and purge permissions.

To perform a privileged purge operation, even if the object is not under retention, you also need privileged permission.

Request header

DELETE /rest/directory/file?purge=true HTTP/1.1
ParameterRequiredDescription
directoryYesFolder name.
fileYesName of the file, including file extension.
purgeYesUse the value true to purge the object.
privilegedNo

To perform a privileged delete, the request must specify both privileged and reason URL query parameters

For example:

?privileged=true&reason=reason-text
reasonYes, if privileged is usedUse percent-encode characters in the reason parameter that have special meanings in URLs.

Response header

This operation does not return any request-specific response headers.

Response body

Not applicable.

Return codes

CodeMeaningDescription
200OKHCP successfully purged all versions of the object.
400Bad Request

The request specified a conditional header, such as If-Match.

If more information about the error is available, the HTTP response headers include the HCP-specific X‑HCP-ErrorMessage header.

403Forbidden

One of:

  • The Authorization header or hcp-ns-auth cookie specifies invalid credentials.
  • The namespace requires client authentication, and the request does not have an Authorization header or hcp-ns-auth cookie.
  • The object is under retention, and you do not have the privileged permission.
  • The user doesn’t have permission to perform the requested operation.
  • The namespace does not exist.
  • The access method (HTTP or HTTPS) is disabled.

If more information about the error is available, the response headers include the HCP-specific X‑HCP-ErrorMessage header.

404Not Found

One of:

  • HCP could not find a directory, object, or version at the specified URL. The specified object or version does not exist, or the request specified the current version of an object that has been deleted.
  • Any component of the URL except for the last component in the path is a symbolic link to a directory.
409ConflictHCP could not purge the specified object because it is currently being written to the namespace.

Example: Purging an object

Here’s a sample HTTP DELETE request that purges all versions of the object named Q1_2012.ppt from the quarterly_rpts directory. This example uses a URL query string to pass the operation parameters.

Request with curl command line

curl -k -iX DELETE
    -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    -k "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2012.ppt
    ?purge=true"

Request in Python using PycURL

import pycurl
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com \
  /rest/quarterly_rpts/Q1_2012.ppt?purge=true")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.CUSTOMREQUEST, "DELETE")
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()

Request headers

DELETE /rest/quarterly_rpts/Q1_2012.ppt?purge=true HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
X-HCP-ServicedBySystem: hcp.example.com
X-HCP-Time: 1334425187
Content-Length: 0

Example: Performing a privileged purge

Here’s a sample HTTP DELETE request that purges the object named

Q1_2012.ppt, which is under retention, from the quarterly_rpts directory. This example uses form-encoded data to pass the operation parameters and percent-encodes the reason because it contains an ampersand.

Request with curl command line

curl -k -iX DELETE
    -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    -k -d "purge=true" -d "privileged=true"
    -d "reason=Purged%20per%20Compliance%20Dept.%20order%20AD%26943"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2012.ppt"

Request in Python using PycURL

import pycurl
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.URL, "https://finance.europe.example.hcp.com \
  /rest/quarterly_rpts/Q1_2012.ppt")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.CUSTOMREQUEST, "DELETE")

args = {'privileged':'true', 'purge':'true',
  'reason':'Purged per Compliance Dept. order AD&943'}
params = urllib.urlencode(args)
curl.setopt(pycurl.POSTFIELDS, params)

curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()

Request headers

DELETE /rest/quarterly_rpts/Q1_2012.ppt HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d
Content-Length: 90
Content-Type: application/x-www-form-urlencoded

Response headers

HTTP/1.1 200 OK
X-HCP-ServicedBySystem: hcp.example.com
X-HCP-Time: 1334425187
Content-Length: 0