The paged document comments resource returns a keyset-paged list of comments for a document. It is implemented in the Files API; public URLs are under /files/documents/{documentId}/pagedcomments.

Comments are ordered by created date. The default page is the first 50 comments with sort=descending (newest first), direction=forwards, and no fromCommentId (first page). Paging next / prev links are included in the collection when applicable.

Keyset pagination avoids unbounded reads: each response includes a window of comments plus first, next, and sometimes prev links so the client can walk the list.

If there are no comments, the collection typically still has first, but next is not added (nothing to page from). prev is only present when you are not on the implicit first page (i.e. when paging was anchored with fromCommentId).

Example (relative paths; prefix with your gateway /apigateway/files/ as usual):

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

JSON clients can use e.g. Accept: application/vnd.huddle.data+json (or the v2 media types your gateway exposes); the payload shape mirrors the XML elements.

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

<documentComments xmlns="http://schema.huddle.net/2011/02/">
  <link rel="self" href="files/documents/123/pagedcomments?size=50&amp;direction=forwards&amp;sort=descending" />
  <link rel="parent" href="files/documents/123" />
  <link rel="create" href="files/documents/123/comments" />

  <collection>
    <links>
      <link rel="first" href="files/documents/123/pagedcomments?size=50&amp;direction=forwards&amp;sort=descending" />
      <link rel="next" href="..." />
      <link rel="prev" href="..." />
    </links>
    <items>
      <comment>
        <link rel="self" href="files/documents/123/comments/987" />
        <link rel="delete" href="files/documents/123/comments/987" />
        <content>Hey Everyone and John Smith could you help Team Comments and Jim Taylor with their work</content>
        <created>2007-10-10T09:02:17Z</created>
        <version>12</version>
        <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>
      </comment>

      <comment>
        <link rel="self" href="files/documents/123/comments/986" />
        <content>This is another comment for the document</content>
        <created>2007-10-10T09:02:17Z</created>
        <version>12</version>
        <actor name="Jimmy Snake" email="[email protected]" rel="owner">
          <link rel="self" href="..." />
          <link rel="avatar" href="..." type="image/jpg" />
          <link rel="alternate" href="..." type="text/html" />
        </actor>
      </comment>
    </items>
  </collection>

  <queries>
    <query>
      <link href="files/documents/123/pagedcomments" rel="paging" />
      <prompt>Enter paging choices</prompt>
      <data>
        <parameter name="size" value="50" />
        <parameter name="direction" value="forwards" />
        <parameter name="sort" value="descending" />
        <parameter name="fromCommentId" value="147" />
      </data>
    </query>
  </queries>
</documentComments>

• link rel="delete" on a comment is emitted only when the current user is allowed to delete that comment; otherwise only self (and the body fields) are present for that item.
• self and delete for a comment both target the single-comment resource: /files/documents/{documentId}/comments/{commentId} (not under pagedcomments/...).
• version is derived from the document version associated with the comment (server-calculated; not necessarily the raw stored comment version field).
• queries is a sibling of collection under documentComments, not nested inside collection.

The OpenRasta configuration for PagedCommentsView does not register a projection query parameter, and PagedCommentView has no contentsubstitutions / mention metadata block. Clients should treat content as the string produced for the API (plain display-oriented text), not rely on a ?projection=mentions enrichment on this URL.

For creating comments and mention syntax, see the document comments collection on /files/documents/{documentId}/comments.