Documents represent files stored within Huddle, such as spreadsheets or images. Documents also have metadata for version history and commenting.

Documents have a locking mechanism which prevents others from modifying them. See lock.

You can can create a new document within a folder by using the advertised link with the @rel value create-document. For more information, see Create a document.

When retrieving a folder, the response will contain the list of documents within the folder. Each document will advertise a self link, which you can use to GET the full document. This endpoint also supports HEAD requests.

An If-Modified-Since header can be specified in the Request header to indicate that only if there are changes to the Document resource since the specified time should they be sent.

Additionally, Last-Modified is included in the response to indicate the last time the Document resource was generated.

If a document has restricted permissions then the links with the following rel attributes will not be returned:

• make-offline
• content
• copy

Additionally the previews link will return a boolean value indicating if the document is restricted

GET .../files/documents/123 HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+xml
Last-Modified: Thu, 04 Dec 1986 12:45:26 GMT

<document itemType="Document" title="TPS report May 2010" description="relentlessly mundane and enervating.">
  <link rel="self" href="..." />
  <link rel="parent" href="..." title="..."/>
  <link rel="edit" href="..." />
  <link rel="move" href="..." />
  <link rel="delete" href="..." />
  <link rel="tags" href="..." />
  <link rel="content" href="..." title="..." type="..." />
  <link rel="lock" href="..." />
  <link rel="version-history" href="..." />
  <link rel="create-version" href="..." />
  <link rel="comments" href="..." count="2" />
  <link rel="approvals" href="..." />
  <link rel="permissions" href="..." />
  <link rel="share" href="..." />
  <link rel="previews" href="..." restricted="false" />
  <link rel="alternate" href="..." />
  <link rel="alternate" href="..." type="text/html" />
  <link rel="shortlink" href="..." type="text/html" />
  <link rel="copy" href="..." />
  <link rel="audittrail" href="..." />
  <link rel="current-lock" href="..." />
  <link rel="printed" href="..." />
  <link rel="viewed" href="..." />
  <link rel="make-offline" href="..." />
  <link rel="publish" href="..." />
  <link rel="publications" href="..." />
  <link rel="last-viewed" href="..." />
  <link rel="unpin" href="..." />
  <actor name="Peter Gibson" email="[email protected]" rel="owner">
    <link rel="self" href="..." />
    <link rel="avatar" href="..." type="image/jpg" />
    <link rel="alternate" href="..." type="text/html" />
  </actor>
  <actor name="Barry Potter" email="[email protected]" rel="updated-by">
    <link rel="self" href="..." />
    <link rel="avatar" href="..." type="image/jpg" />
    <link rel="alternate" href="..." type="text/html" />
  </actor>
  <size>19475</size>
  <version>98</version>
  <created>2007-10-10T09:02:17Z</created>
  <updated>2011-10-10T09:02:17Z</updated>
  <processingStatus>Complete</processingStatus>
  <views>-1</views>
  <mimeType>application/...</mimeType>
  <extension>doc</extension>
  <workspace title="My workspace">
    <link rel="self" href="..." />
	<link rel="alternate" href="..." type="text/html" />
  </workspace>
  <thumbnails>
    <thumbnail type=”medium”>
      <link rel="content" href="..." />
    </thumbnail>
  </thumbnails>
  <publication>
    <link rel="bookmark" href="..." />
    <publishedDate>2014-06-15T09:43:17Z</publishedDate>
    <documentVersion title="My amazing document is amazing">
       <link rel="self" href="..." />
       <version>2</version>
       <contentType>application/pdf</contentType>
    </documentVersion>
    <scope>Public</scope>
  </publication>
  <approval>
     <status>Complete</status>
  </approval>
  <tags>
     <tag>documentation</tag>
     <tag>api</tag>
  <tags>
  <pin>
    <links>
     <link rel="self" href="..."/>
     <link rel="delete" href="..."/>
    </links>
    <actor name="Barry Potter" email="[email protected]" rel="pinned-by">
     <link rel="self" href="..." />
     <link rel="avatar" href="..." type="image/jpg" />
     <link rel="alternate" href="..." type="text/html" />
    </actor>
    <pinnedDate>2018-05-10T09:02:17Z</pinnedDate>
  </pin>
</document>

See Document Content

If the authenticated user is authorized to edit a document, it will advertise a link with a @rel value of edit. To update document metadata submit a PUT request to this URI with the editable fields of the document. For an overview of editing resource in Huddle see editing resources.

In this example we update the document's title and description using the URI advertised in the document resource.

First, they retrieve the edit uri of the document they wish to edit.

GET .../files/documents/1/edit HTTP/1.1
Accept: application/vnd.huddle.data+xml

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+xml

<document title="old title" description="old description">
  <link rel="parent" href="..." />
</document>

The user then updates the @title and @description attributes in the editable document resource and PUTs it back to the server.

If a document with the same title and the same extension already exists within the folder, you will receive a 409 Conflict.

PUT .../files/documents/123/edit HTTP/1.1
Content-Type: application/vnd.huddle.data+xml
Content-Length: 102
Authorization: Bearer frootymcnooty/vonbootycherooty

<document xmlns="http://schema.huddle.net/2011/02/" title="new title" description="new description" >
   <link rel="parent" href="..." />
</document>

If successful, this operation will return a 204 No content, with a link header giving the location of the updated document.

This response uses the standard error codes and returns standard response headers.

HTTP/1.1 204 No Content
Link <.../files/documents/123>;rel="parent"

This resource supports moving a document to a new location. If the authenticated user can move a document, the document resource will advertise a link with a @rel of move. Note that the @href of this link is the same as the @href for editing a document, since a move is actually an edit operation. To move a document, PUT a new link to this move uri, with a @rel value of parent, and an @href value pointing to the new parent folder.

In this example, the user wishes to move a document which has a self uri of .../files/documents/1, and a parent uri of .../files/folders/2.

The user wishes to move their document to a new parent with a self uri of .../files/folders/3. First, they retrieve the move uri of the document they wish to move.

GET .../files/documents/1/edit HTTP/1.1
Accept: application/vnd.huddle.data+xml

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+xml

<document title="my document" description="">
  <link rel="parent" href=".../files/folders/2" />
</document>

The user then updates the parent link in the editable document resource, setting the @href to the URI of the new parent folder, and PUTs it back to the server.

If a document with the same title and the same extension already exists within the folder, you will receive a 409 Conflict.

PUT .../files/documents/1/edit HTTP/1.1
Content-Type: application/vnd.huddle.data+xml

<document itemType="Document" title="my document" description="">
  <link rel="parent" href=".../files/folders/3" />
</document>

The server responds with a 202 Accepted, and provides a link header with a @rel value of parent pointing to the document being moved, where the client can monitor the value of the 'processingStatus' element.

HTTP/1.1 202 Accepted
Content-Type: application/vnd.huddle.data+xml
Link: <.../files/documents/123>;rel="parent"

The client should follow the link header and perform a GET. When the 'processingStatus' element is equal to 'Moving' it means that the operation is still ongoing. When the operation is completed the 'processingStatus' element assumes the value 'Complete'. While the document is moving it's not possible to download its content, and a 409 Conflict will be returned if a client attempts to do so.

Example of a moving document:

<document itemType="Document" title="My Document">
  <link rel="self" href=".../files/documents/123" />

  ... other document elements ...

  <processingStatus>Moving</processingStatus>
</document>

This resource supports creating a new version of a document.

If the authenticated user can create a new version, the document resource will advertise a link with a @rel value of create-version.

To create a new version POST to the create-version URI with either an empty body or a document version representation (see example below). The document version consists of optional title and description attributes. Note that if these attributes are omitted, the previous version's title and description values are used. The initial POST request must include the mime type and the size in bytes of the document content in the X-Upload-Content-Type and X-Upload-Content-Length, respectively.

If the document is locked by someone else, then this operation will fail with a 409 Conflict response that contains information about the lock.

If you want to be sure that no one else creates a new version or change the content of the document while you are creating a new version you should lock the document before performing the operation as described in the lock section.

Note, the type of lock (either 'Exclusive or 'CoAuthoring') has an impact on how these versions are managed against the document. When you have an 'Exclusive' lock, each time you create a version (and upload some associated content), the document is immediately affected (i.e. the version is added and visible to all permitted users). If you have a 'CoAuthoring' lock, the versions are stored privately and do not affect the document until a 'Promotion' (see Version Promotion) is invoked. In this scenario, members of the CoAuthoring lock are able retrieve download these versions (providing the requests come from the same client that took the lock), but not generate previews.

POST .../files/documents/12345/version HTTP/1.1
Content-Type: application/vnd.huddle.data+xml
Content-Length: 102
Authorization: Bearer frootymcnooty/vonbootycherooty
X-Upload-Content-Type: application/msword
X-Upload-Content-Length: 54126

<documentVersion xmlns="http://schema.huddle.net/2011/02/" title="document title" description="document description" versionNote="document note" extension=".doc" />

If the response is successful, it will advertise a link for uploading the content of the document. For information on uploading a document see Uploading Documents.

Until new binary content is uploaded, the document resource will not advertise a content link. Earlier versions of document content will still be accessible through the VersionHistory resource.

If @extension is supplied and a document with the same title and the same extension already exists within the folder, you will receive a 409 Conflict.

If the document is locked by someone else, then this operation will fail with a 409 Conflict.

If a document with the same title already exists within the folder, you will receive a 409 Conflict stating that you cannot create a document with a duplicate title. If "extension" was provided on request this will only look for duplicates in the folder for the same extension type. Without "extension" is not provided, it will look for duplicates in the folder despite what extension type.

This response uses the standard error codes and returns standard response headers.

HTTP/1.1 201 Created
Content-Type: application/vnd.huddle.data+xml

<document itemType="Document" title="document title" description="document description">
  <link rel="self" href="..." />
  ... other document elements ...
  <size>0</size>
  <version>2</version>
  <created>2011-10-10T09:02:17Z</created>
  <updated>2011-11-11T10:02:17Z</updated>
  <processingStatus>Complete</processingStatus>
</document>

When versions are created for a document that is currently locked for 'CoAuthoring', they are not automatically applied to the document - meaning they are not visible unless the user is a member of the lock, and the request comes from the same client that the lock was taken in.

For these versions to be applied to the document, they must be "Promoted". It is only currently possible to promote the most recent save made during a particular 'CoAuthoring' lock.

If the authenticated user can promote a version, the document resource will advertise a link with a @rel value of promote-latest. A POST to this URI (with an empty request body) will take the most recent version uploaded since the 'CoAuthoring' lock was taken, and make that the Latest Version for the document.

POST .../files/documents/12345/promote/latest HTTP/1.1
Content-Type: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

If the operation is successful, it will return a respresentation of the updated document resource, along with a 'Location' header pointing to the document resource.

If no promotion occurred (i.e. there wasn't a version created during the lifetime of the 'CoAuthoring' lock that required promotion), a 204 No Content response will be returned.

This response uses the standard error codes and returns standard response headers.

HTTP/1.1 201 Created
Content-Type: application/vnd.huddle.data+json
Location: .../files/documents/12345/

{
  "title": "document title",
  "description": "document description",
  "links": [
    {
      "rel": "self",
      "href": "..."
    }
    ... other links ...
  ]
  ... other document elements ...
}

This resource supports deleting a document. If the authenticated user can delete a document, the document resource will advertise a link with @rel value of delete. To delete the document, issue a DELETE request to the delete URI.

DELETE .../files/documents/123 HTTP/1.1
Authorization: Bearer frootymcnooty/vonbootycherooty

If successful, this method will return an empty response with an OK status code and a link header to the parent folder.

HTTP/1.1 200 OK
Link: <.../files/folders/123>;rel="parent"

This resource supports restoring a document. If the authenticated user can restore a document, /restore can be appended to the document resource URI to restore URI. To restore the document, issue a PUT request to the restore URI.

PUT .../files/documents/123/restore HTTP/1.1
Authorization: Bearer frootymcnooty/vonbootycherooty

If successful, this operation will return a 204 No content, with a link header giving the location of the restored document.

This response uses the standard error codes and returns standard response headers.

HTTP/1.1 204 No Content
Location: .../files/documents/123

** Note that there is a restore window on comment, any comments deleted within the 30 seconds from when the document was deleted will be restored. Any comments deleted beforehand will remain as deleted.

The copy document resource supports making a copy of a document.

To copy a document, first retrieve the document to get its copy link, then POST to the document's copy URI.

If the copy operation is successful, the copy document endpoint will return a 201 Created response, along with the URI of the new document copy in the Location header.

Documents can be copied to the same folder, to another folder in the same workspace, or to a folder in another workspace. When POSTing to the Copy Document endpoint, clients should include a link to the target folder in the POST body of the request (see Example below).

When a document is copied, the copy will have the same title as the original. However, if a document with the same title and description already exists in the target folder, then the copied document will be suffixed with a number. For example, a copy of the document "My document.doc" would be named "My document (1).doc".

It is important to note that the copy document operation copies the content of the document's most recent version. It does not copy previous document versions, comments, activity history, and approvals.

In this example, we will copy document 123 to folder 456.

GET .../files/documents/123 HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+xml

<document>
  <link rel="self" href=".../files/documents/123" />
  <link rel="copy" href=".../files/documents/123/copy" />
</document>

Please note that only the relevant parts of the GET Document response are included in the above example. For the full GET Document response, please refer to Retrieving a document.

POST .../files/documents/123/copy HTTP/1.1
Content-Type: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty

<copyDocument>
  <targetFolder>
    <link rel="self" href=".../files/folders/456" />  
  </targetFolder>
</copyDocument>

HTTP/1.1 201 Created
Content-Type: application/vnd.huddle.data+xml
Location: .../files/documents/789

For certain file types, a thumbnail is automatically and asynchronously created when the file is uploaded. This includes the most common image and video MIME types.

If the document version’s MIME type is supported, the Get Document response body will include a "thumbnails" element containing a "thumbnail" child element, which contains a link with a @rel value of content. A GET request to the thumbnail content URI will return the thumbnail content.

If a thumbnail is not available, a 404 will be returned.

In this example we have the thumbnail link from the document resource, and issue a GET request to it.

GET ../files/documents/versions/123/thumbnails/medium/content; HTTP/1.1
Authorization: Bearer frootymcnooty/vonbootycherooty

HTTP/1.1 200 OK
Cache-Control: private, max-age=600
Content-Type: image/jpeg
Content-Length: 930

A stream that makes up the image...

This resource supports adding and removing tags from a document. If the authenticated user can tag a document, the document resource will advertise a link with a @rel of tags.

In this example, the user wishes to tag a document which has a self uri of .../files/documents/1.

POST .../files/documents/1/tags HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty

<tag>
  <value>documentation</value>
</tag>

HTTP/1.1 201 OK
Content-Type: application/vnd.huddle.data+xml
Location: ../files/documents/1/tags/documentation

If a document already has the supplied tag you will receive a 409 Conflict.

Removing a tag from a document. If the authenticated user can remove a tag from the document, the document resource will advertise a link with a @rel of tags.

In this example, the user wishes to tag a document which has a self uri of .../files/documents/1.

DELETE .../files/documents/1/tags/documentation HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty

HTTP/1.1 204 No Content
Content-Type: application/vnd.huddle.data+xml

For information on viewing, creating, or deleting document comments, see Document Comments.

For information on publishing, see Publish Documents.

For details on viewing or creating document approvals, see Document Approvals.

For details on viewing changes made to a document, or to manually create document changes, see Audit Trail.

For details on sharing a document, see Sharing.

For details on document previews, see Previews.

For details on differences between document versions, see Document Version Difference.

The document resource will advertise a link "last-viewed". Follow this link to determine when you last viewed the document. The user is determined from the Authorization header given in the request. See Document Last Viewed.

<document xmlns="http://schema.huddle.net/2011/02/" itemType="Document" title="TPS report May 2010" description="relentlessly mundane and enervating.">

  <link rel="self" href="..." />
  <link rel="parent" href="..." title="..."/>
  <link rel="edit" href="..." />
  <link rel="move" href="..." />
  <link rel="delete" href="..." />
  <link rel="content" href="..." title="..." type="..." />
  <link rel="lock" href="..." />
  <link rel="version-history" href="..." />
  <link rel="create-version" href="..." />
  <link rel="comments" href="..." count="2" />
  <link rel="approvals" href="..." />
  <link rel="permissions" href="..." />
  <link rel="share" href="..." />
  <link rel="previews" href="..." />
  <link rel="alternate" href="..." />
  <link rel="alternate" href="..." type="text/html" />
  <link rel="shortlink" href="..." type="text/html" />
  <link rel="copy" href="..." />
  <link rel="audittrail" href="..." />
  <link rel="printed" href="..." />
  <link rel="viewed" href="..." />
  <link rel="make-offline" href="..." />
  <link rel="publish" href="..." />
  <link rel="publications" href="..." />
  <actor name="Peter Gibson" email="[email protected]" rel="owner">
    <link rel="self" href="..." />
    <link rel="avatar" href="..." type="image/jpg" />
    <link rel="alternate" href="..." type="text/html" />
  </actor>
  <actor name="Barry Potter" email="[email protected]" rel="updated-by">
    <link rel="self" href="..." />
    <link rel="avatar" href="..." type="image/jpg" />
    <link rel="alternate" href="..." type="text/html" />
  </actor>
  <thumbnails>
    <thumbnail type="medium">
      <link rel='content' href='...' />
    </thumbnail>
  </thumbnails>
  <size>1024</size>
  <version>98</version>
  <created>2007-10-10T09:02:17Z</created>
  <updated>2011-10-10T09:02:17Z</updated>
  <processingStatus>Complete</processingStatus>
  <views>-1</views>
</document>

<document itemType="Document" title="My Document">
  <link rel="self" href="..." />
  ... other document elements ...
  <lock>
    <link rel="self" href="..." />
    <link rel="delete" href="..." />
    <link rel="parent" href="..." />
    <actor name="Peter Gibson" rel="owner">
      <link rel="self" href="..." />
      <link rel="avatar" href="..." type="image/jpg" />
      <link rel="alternate" href="..." type="text/html" />
    </actor>
    <lockDate>2007-10-10T09:02:17Z</lockDate>
  </lock>
</document>

<document itemType="Document" title="My Document">
  <link rel="self" href="..." />
  ... other document elements ...
  <lock>
    <link rel="self" href="..." />
    <actor name="Peter Gibson" email="[email protected]" rel="owner">
      <link rel="self" href="..." />
      <link rel="avatar" href="..." type="image/jpg" />
      <link rel="alternate" href="..." type="text/html" />
    </actor>
    <lockDate>2007-10-10T09:02:17Z</lockDate>
  </lock>
</document>

start = document

document = element h:document {
  attribute itemType {xsd:string},
  attribute title {xsd:string},
  attribute description {xsd:string}?,
  (empty | link + |
	(
	  link+,
    actor+,
	  lock?,
    element h:size {xsd:unsignedLong},
    element h:version {xsd:unsignedInt},
    element h:created {xsd:dateTime},
    element h:updated {xsd:dateTime},
    element h:processingStatus {"Complete"|"Error"|"Moving"|"Processing"|"Uploaded"},
    element h:views {xsd:unsignedInt},
    thumbnails?
    pin?,
	))
}

lock = element h:lock {
  link+,
  actor
}

pin = element h:pin {
  link+,
  actor,
  element h:pinnedDate {xsd:dateTime},
}

thumbnails = element h:thumbnails{
  thumbnail+
}

thumbnail = element h:thumbnail{
  link+
}