Shares API

Overview

The Shares API manages persistent file access grants. Shares allow file owners to grant read or write access to specific users or via links.

Shares vs References vs FSHR Actions
  • Shares are persistent access grants stored on the file (managed here)
  • References are shareable tokens/links (see References API)
  • FSHR actions are federation-level file sharing events (see Actions API)

When you create a user share, the system automatically creates an FSHR action for federation.

Share Entry Fields

Field Type Description
id number Share entry ID
resourceType string Resource type (F for file)
resourceId string ID of the shared resource
subjectType string Subject type: U (user), L (link), F (file)
subjectId string ID of the recipient/subject
permission string Permission level: R (read), W (write), A (admin)
expiresAt string Expiration timestamp (ISO 8601) or null
createdBy string Identity that created the share
createdAt string Creation timestamp (ISO 8601)

Endpoints

List Shares by Subject

GET /api/shares

List all shares where a given identity is the subject (recipient).

Authentication: Required

Query Parameters:

  • subjectId (required) - The subject identity to search for
  • subjectType (optional) - Subject type filter: U (user), L (link), F (file)

Response:

{
  "data": [
    {
      "id": 1,
      "resourceType": "F",
      "resourceId": "b1~abc123",
      "subjectType": "U",
      "subjectId": "bob.cloudillo.net",
      "permission": "R",
      "expiresAt": null,
      "createdBy": "alice.cloudillo.net",
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ],
  "time": "2025-01-15T10:30:00Z"
}

List File Shares

GET /api/files/{file_id}/shares

List all shares for a specific file.

Authentication: Required (must have write access to file)

Path Parameters:

  • file_id - The file ID

Response:

{
  "data": [
    {
      "id": 1,
      "resourceType": "F",
      "resourceId": "b1~abc123",
      "subjectType": "U",
      "subjectId": "bob.cloudillo.net",
      "permission": "W",
      "expiresAt": "2025-06-01T00:00:00Z",
      "createdBy": "alice.cloudillo.net",
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ],
  "time": "2025-01-15T10:30:00Z"
}

Create Share

POST /api/files/{file_id}/shares

Grant access to a file by creating a share entry.

Authentication: Required (must have write access to file)

Path Parameters:

  • file_id - The file ID to share

Request Body:

{
  "subjectType": "U",
  "subjectId": "bob.cloudillo.net",
  "permission": "R",
  "expiresAt": "2025-06-01T00:00:00Z"
}
Field Type Required Description
subjectType string Yes U (user), L (link), or F (file)
subjectId string Yes Non-empty ID of the recipient
permission string Yes R (read), W (write), or A (admin)
expiresAt string No Expiration timestamp (ISO 8601)

Response (201 Created):

{
  "data": {
    "id": 2,
    "resourceType": "F",
    "resourceId": "b1~abc123",
    "subjectType": "U",
    "subjectId": "bob.cloudillo.net",
    "permission": "R",
    "expiresAt": "2025-06-01T00:00:00Z",
    "createdBy": "alice.cloudillo.net",
    "createdAt": "2025-01-15T10:30:00Z"
  },
  "time": "2025-01-15T10:30:00Z"
}
Info

When creating a user share (subjectType: "U"), the system automatically creates an FSHR action for federation delivery.

Example:

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"subjectType":"U","subjectId":"bob.cloudillo.net","permission":"R"}' \
  "https://cl-o.alice.cloudillo.net/api/files/b1~abc123/shares"

Delete Share

DELETE /api/files/{file_id}/shares/{share_id}

Revoke a file share.

Authentication: Required (must have write access to file)

Path Parameters:

  • file_id - The file ID
  • share_id - The share entry ID to delete

Response:

{
  "data": null,
  "time": "2025-01-15T10:30:00Z"
}
Info

When deleting a user share, the system automatically creates an FSHR action with subType: "DEL" for federation.

See Also