Documents can be published publicly or privately. A published document has a unique URL that can be shared with people who do not have access to the document in Huddle.

Huddle.FilesApi exposes document publication operations at /files/documents/{documentId}/publications. Starting a publish returns 202 Accepted with a Link header whose monitor relation points at the publications resource on Files and whose progress relation points at a Publishing service progress URL (not defined in the Files repo—use the href from the response).

If a document can be published, its representation advertises a link with rel publish pointing at the publications resource. Submit an empty POST to that URI to publish the latest version.

On success the API returns 202 Accepted. The response includes one Link header with two relations (order is as emitted by the server):

1. rel="monitor" — the document publications resource on Files (same path you POSTed to).
2. rel="progress" — the progress resource to poll until publication completes.

The monitor relation is retained for compatibility; clients should prefer progress for status polling.

POST /files/documents/123/publications HTTP/1.1
Authorization: Bearer {token}

HTTP/1.1 202 Accepted
Link: <https://api.example.com/files/documents/123/publications>; rel="monitor", <https://api.example.com/publishing/progress/660107d3-b06d-4972-9cfc-8c5ac1e381e5>; rel="progress"

The progress resource (URI from the progress link) describes the state of an ongoing publish. It is not implemented in the Files API project; treat the path as opaque and follow the returned URL.

When available, the representation may advertise a bookmark link and, when status is complete, a publications link back to the Files publications resource to refresh publication history.

GET /publishing/progress/660107d3-b06d-4972-9cfc-8c5ac1e381e5 HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: Bearer {token}

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

<publishingProgress xmlns="http://schema.huddle.net/2011/02/">
  <link rel="self" href="publishing/progress/660107d3-b06d-4972-9cfc-8c5ac1e381e5" />
  <link rel="bookmark" href="http://public.published.link/123" />
  <link rel="publications" href="files/documents/123/publications" />
  <status>Done</status>
</publishingProgress>

DELETE the publications resource. The document is no longer available at its published link.

The 202 Accepted response includes a Link header:

• Always rel="self" on the publications resource.
• rel="publish" on the same URI as well when policy allows immediate re-publish; otherwise only self is present.

Both relations may appear in a single comma-separated Link header value.

DELETE /files/documents/123/publications HTTP/1.1
Authorization: Bearer {token}

HTTP/1.1 202 Accepted
Link: <https://api.example.com/files/documents/123/publications>; rel="self", <https://api.example.com/files/documents/123/publications>; rel="publish"

The Document resource advertises publications when publication history applies. GET that URI to retrieve history and the public bookmark, plus publish / unpublish links when the user has those permissions.

If there is nothing to return (e.g. no bookmark), the API may respond with 204 No Content.

GET /files/documents/123/publications HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: Bearer {token}

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

<documentPublication xmlns="http://schema.huddle.net/2011/02/">
  <link rel="self" href="files/documents/123/publications" />
  <link rel="parent" href="files/documents/123" />
  <link rel="bookmark" href="http://public.published.link/123" />
  <link rel="publish" href="files/documents/123/publications" />
  <link rel="unpublish" href="files/documents/123/publications" />

  <publications>
    <publication>
      <actor name="Peter Gibson" email="[email protected]" rel="publisher">
        <link rel="self" href="..." />
        <link rel="avatar" href="..." type="image/jpeg" />
        <link rel="alternate" href="..." type="text/html" />
      </actor>

      <publishedDate>2007-10-10T09:02:17Z</publishedDate>
      <publishingState>PublishInProgress</publishingState>
      <documentVersion>
        <link rel="self" href="files/documents/123/version/543" />
        <version>2</version>
        <note>new note</note>
      </documentVersion>
    </publication>

    <publication>
      <actor name="Jimmy Snake" email="[email protected]" rel="publisher">
        <link rel="self" href="..." />
        <link rel="avatar" href="..." type="image/jpeg" />
        <link rel="alternate" href="..." type="text/html" />
      </actor>

      <publishedDate>2007-10-10T09:02:17Z</publishedDate>
      <publishingState>PublishInProgress</publishingState>
      <documentVersion>
        <link rel="self" href="files/documents/123/version/542" />
        <version>1</version>
        <note>new note</note>
      </documentVersion>
    </publication>
  </publications>
</documentPublication>

Use the PublishedDocuments endpoint.

Use the PublishedDocuments endpoint.

Use the PublishedDocuments endpoint.

• Link — Link response header format
• Document — publish, publications, unpublish link rels on the document