Summary

'Pinned' items are a list of either Documents or Folders, curated by Workspace Managers, but visible to all members of the workspace. Folder permissions are respected, so when a call is made for a particular user, only items the user is permitted to see will be returned.

Status

Operation	Status
Retrieving the pins for a workspace	Live
Pinning a document	Live
Unpinning a document	Live
Pinning a folder	Draft
Unpinning a folder	Live

---

Retrieving the pins for a workspace

If pinning is enabled for the workspace, a workspace element will contain a link with a @rel value of pinneditems.

To get a list of pinned items for a workspace (either Documents or Folders), make a GET request to that URI.

Example

Request

GET /files/workspaces/27/pinneditems HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Response

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

{
  "links": [
    { "rel": "self", "href": "https://api.example.com/files/workspaces/27/pinneditems" }
  ],
  "items": [
    {
      "type": "folder",
      "title": "sub folder",
      "description": "my subfolder",
      "links": [
        { "rel": "self", "href": "https://api.example.com/files/folders/10" },
        { "rel": "unpin", "href": "https://api.example.com/files/folders/10/pin" },
        { "rel": "alternate", "href": "https://my.huddle.example/...", "type": "text/html" },
        { "rel": "paged-folder", "href": "https://api.example.com/files/folders/10/contents" }
      ]
    },
    {
      "type": "document",
      "title": "document title",
      "description": "document description",
      "mimeType": "application/pdf",
      "extension": "pdf",
      "thumbnails": [
        {
          "links": [{ "rel": "content", "href": "https://api.example.com/files/documents/5/thumbnails/medium" }],
          "type": "medium"
        }
      ],
      "links": [
        { "rel": "self", "href": "https://api.example.com/files/documents/5" },
        { "rel": "unpin", "href": "https://api.example.com/files/documents/5/pin" },
        { "rel": "alternate", "href": "https://my.huddle.example/...", "type": "text/html" },
        { "rel": "content", "href": "https://api.example.com/files/documents/5/content" }
      ]
    }
  ]
}

---

Pinning a document

(Workspace Managers only)

If it is possible to pin this document, the document resource will advertise a link with a @rel of pin.

Example

In this example, the user pins a document whose self URI is /files/documents/1.

Request

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

Response

HTTP/1.1 200 OK

Status Code	Reason
200	OK
401	Invalid authorization token
403	Insufficient permissions, or Too Many Pins
404	Specified document not found
409	Already pinned
410	Specified document is deleted

Unpinning a document

(Workspace Managers only)

If pinned, the document resource will have a Pin element. A DELETE request to the advertised URI for the pin removes it.

Alternatively, each item in the workspace pins list includes a link with @rel of unpin — the same URI as the pin resource — which can be used to unpin.

Example

In this example, the user unpins a document at /files/documents/1/pin.

Request

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

Response

Status Code	Reason
200	OK
401	Invalid authorization token
403	Insufficient permissions
404	Specified document not found, or not pinned
410	Specified document is deleted

---

Pinning a folder

(Workspace Managers only)

It is possible to add a folder to the list of 'pinned' items for the workspace.

If it is possible to pin this folder, the folder resource will advertise a link with a @rel of pin.

Example

In this example, the user pins a folder whose self URI is /files/folders/1.

Request

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

Response

HTTP/1.1 200 OK

Status Code	Reason
200	OK
401	Invalid authorization token
403	Insufficient permissions, or Too Many Pins
404	Specified folder not found
409	Already pinned
410	Specified folder is deleted

Unpinning a folder

(Workspace Managers only)

If pinned, and it is possible to unpin this folder, the folder resource will contain a Pin element. A DELETE request to the advertised pin URI removes the pin.

Alternatively, each item in the workspace pins list includes a link with @rel of unpin — the same URI — which can be used to unpin.

Example

In this example, the user unpins a folder at /files/folders/1/pin.

Request

DELETE /files/folders/1/pin HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty

Response

Status Code	Reason
200	OK
401	Invalid authorization token
403	Insufficient permissions
404	Specified folder not found, or not pinned
410	Specified folder is deleted