Share - Huddle/huddle-apis GitHub Wiki

Summary

A user can share a document or folder with explicit recipients (users and/or teams) and an optional message.

For documents, the request may also include an invite block: email addresses for people not yet in Huddle, plus the team URIs they should be invited into. That path requires valid emails, at least one team, a cap on email count, and permission checks on those teams (see Error and validation behaviour).

Status

Operation Status
Sharing a resource Live

Resources that support sharing

  • Document β€” POST /files/documents/{documentId}/share
  • Folder β€” POST /files/folders/{folderId}/share

Both are implemented in the Files API (paths below include the /files/ prefix used behind the gateway).

Operations

Sharing a resource

If sharing is allowed, the document or folder representation includes a link with rel="share". Issue POST to that URI. The body is a share payload: recipient links (unless you rely only on invite for documents), optional message, and optional sendToEveryone (see Payload).

X-Allow-Invalid-Recipients

Optional header: true or false ( bool.TryParse β€” typical HTTP casing such as True / true works).

  • When false or omitted: if any resolved recipient cannot be notified (e.g. cannot read the document/folder), the API returns 400 Bad Request with a shareFailure body listing failing user recipient links.
  • When true: invalid recipients are dropped and the share proceeds for the rest; response is still 202 Accepted (with Link) when processing is accepted.

Example β€” document (with message)

POST /files/documents/123/share HTTP/1.1
Content-Type: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty
XML
<share>
    <link rel="recipient" href="..." />
    <link rel="recipient" href="..." />
    <link rel="recipient" href="..." />
    <message>Hey, take a look at this exhilarating TPS report!</message>
</share>
JSON
{
    "recipients": [
        { "rel": "recipient", "href": "..." },
        { "rel": "recipient", "href": "..." },
        { "rel": "recipient", "href": "..." }
    ],
    "message": "Hey, take a look at this exhilarating TPS report!"
}

Example β€” document (without message)

POST /files/documents/123/share HTTP/1.1
Content-Type: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty
XML
<share>
    <link rel="recipient" href="..." />
    <link rel="recipient" href="..." />
    <link rel="recipient" href="..." />
</share>
JSON
{
    "recipients": [
        { "rel": "recipient", "href": "..." },
        { "rel": "recipient", "href": "..." },
        { "rel": "recipient", "href": "..." }
    ]
}

Example β€” document (invites to new users)

Recipient href values must point at user or team API resources (the server matches users / teams in the path to parse ids). Invite teams entries are link elements with team href values.

POST /files/documents/123/share HTTP/1.1
Content-Type: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty
XML
<share>
    <link rel="recipient" href="..." />
    <message>Hey, take a look at this exhilarating TPS report!</message>
    <invite>
        <teams>
            <link rel="self" href="..." />
            <link rel="self" href="..." />
        </teams>
        <emails>
            <email>[email protected]</email>
            <email>[email protected]</email>
        </emails>
    </invite>
</share>
JSON
{
    "recipients": [
        { "rel": "recipient", "href": "..." },
        { "rel": "recipient", "href": "..." }
    ],
    "invite": {
        "teams": [
            { "rel": "self", "href": "..." },
            { "rel": "self", "href": "..." }
        ],
        "emails": ["[email protected]", "[email protected]"]
    },
    "message": "Hey, take a look at this exhilarating TPS report!"
}

Example β€” optional header

POST /files/documents/123/share HTTP/1.1
Content-Type: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty
X-Allow-Invalid-Recipients: true

Example β€” folder

Folders use the same share root shape; there is no invite block in the Files API folder view (recipients only).

POST /files/folders/456/share HTTP/1.1
Content-Type: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty

Payload

Name Description
message Optional. Max length 5000 characters.
invite Documents only. Optional. emails (strings) and teams (links to team resources). Required whenever you supply invitation emails: at least one team, at most 300 emails, all emails valid, and at least one invited team must have permission to read the document.
sendToEveryone Optional boolean. When false (typical), each recipients entry must have a non-null href. When true on document share, the handler does not read user/team ids from recipients (those links are ignored); you must satisfy validation via invite emails + teams, or you will hit the empty-list error. Folders do not support invite; sendToEveryone: true with no recipients/teams fails validation.

Link relations

Name Description
recipient On request links: target user (or team β€” team links are expanded to members server-side). On shareFailure: failing user URIs.

Response

On success the handler returns 202 Accepted and adds a Link response header pointing at the share information resource (correlation id for polling status). The URI path segment is notifications/shares/{correlationId} (relative to your notifications/BFF base β€” not notification/ singular).

Successful response

HTTP/1.1 202 Accepted
Content-Type: application/vnd.huddle.data+xml
Link: </notifications/shares/5df96158-5f6c-4d7f-a716-7877ad92c560>;rel="share-information"

Failed response (invalid recipients, header not allowing partial send)

HTTP/1.1 400 Bad Request
Content-Type: application/vnd.huddle.data+xml
<shareFailure>
    <reason>These recipients could not be notified.</reason>
    <link rel="recipient" href="..." />
</shareFailure>

Error and validation behaviour

Case Typical outcome
Invalid / unreadable recipients and X-Allow-Invalid-Recipients not true 400 + shareFailure (per-user links).
message longer than 5000 characters 400 (bad request; message from server).
Document: empty recipient/team list and no invite emails 400 (β€œempty or not provided”).
Document invite: emails present but no team ids 400.
Document invite: more than 300 emails 400.
Document invite: invalid email(s) 400.
Document invite: none of the invited teams can read the document 400.
Document: href missing on a recipient link when not using sendToEveryone 400 (plain error result: missing href).
Folder: empty recipient and team lists 400.
User cannot share (policy) Error from policy layer (treat as forbidden / error as surfaced by host).

Shared documents are audited; see the audit trail.

Schema (informal)

The message element is optional; at least one of recipients (and/or document invite emails with teams) must satisfy server validation.

start = share

share = element share {
  link+,
  element message { xsd:string }?,
  element invite { ... }?,
  element sendToEveryone { xsd:boolean }?
}
⚠️ **GitHub.com Fallback** ⚠️