Sharing

Library access control and sharing with users and teams.

A share grants a principal (a user or a team) read access to a library. Shares are addressed by principal: a username for a user, or a team id for a team.

GET /api/libraries/{id}/shares

List all shares for a library.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Library id or natural id

Response:

A flat array (not a paginated collection). Each entry is the share joined with the principal's display details: a user carries username, email, initials, and avatarColor; a team carries name/icon and type: "Team". Rows are ordered by principal name.

List sharesGET /api/libraries/admin:engineering-docs/shares

A flat array of every share, each enriched with the principal’s display details (a user carries username/email/initials/avatarColor; a team carries name/icon and type "Team"). Ordered by principal name.

Response · 200

[
  {
    "libraryId": "00000000-0000-4000-8000-000000000001",
    "principalId": "annie.larson",
    "accessLevel": 1,
    "id": "annie.larson",
    "teamId": null,
    "name": "Annie Larson",
    "materialIcon": null,
    "icon": null,
    "color": null,
    "username": "annie.larson",
    "displayName": "Annie Larson",
    "email": "annie.larson@example.com",
    "avatarUpdatedAt": null,
    "type": "User",
    "avatarColor": {
      "background": "#81C784",
      "text": "#1B5E20"
    },
    "colorIndex": 4,
    "initials": "AL"
  },
  {
    "libraryId": "00000000-0000-4000-8000-000000000001",
    "principalId": "00000000-0000-4000-8000-000000000002",
    "accessLevel": 1,
    "id": "00000000-0000-4000-8000-000000000002",
    "teamId": "00000000-0000-4000-8000-000000000002",
    "name": "Engineering",
    "materialIcon": null,
    "icon": null,
    "color": null,
    "username": null,
    "displayName": null,
    "email": null,
    "avatarUpdatedAt": null,
    "type": "Team"
  }
]

Captured from the API examples test suite; ids and timestamps are normalized.

Access Levels:

Level	Name	Description
0	NONE	No access (represented by the absence of a share)
1	READ	Read-only access to indexed files

---

GET /api/libraries/{id}/shares/{principalId}

Get a specific principal's share.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Library id or natural id
principalId	string	A username (user) or a team id

Response:

The raw LibraryShare row.

Get a single shareGET /api/libraries/admin:engineering-docs/shares/annie.larson

The raw LibraryShare row for one principal.

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/libraries/admin%3Aengineering-docs/shares/annie.larson"
    }
  },
  "id": "00000000-0000-4000-8000-000000000001",
  "tenant": "acme",
  "libraryId": "00000000-0000-4000-8000-000000000002",
  "principalId": "annie.larson",
  "accessLevel": 1,
  "createdAt": "2026-01-15T16:20:00.000Z",
  "updatedAt": "2026-01-15T16:20:00.000Z"
}

Captured from the API examples test suite; ids and timestamps are normalized.

---

PUT /api/libraries/{id}/shares/{principalId}

Create or update a principal's share.

Authentication: Required

Permissions: Requires library:share

Path Parameters:

Parameter	Type	Description
id	string	Library id or natural id
principalId	string	A username (user) or a team id

Request Body:

Field	Type	Required	Description
accessLevel	integer	No	Access level, must be > 0. Defaults to 1 (READ). To revoke, use DELETE, not accessLevel: 0

Example:

{ "accessLevel": 1 }

Response:

This route upserts, so repeating it changes the existing share. Responds 200 with the LibraryShare.

Share with a user or teamPUT /api/libraries/admin:engineering-docs/shares/annie.larson

principalId is a username (user) or a team id. accessLevel must be > 0 (1 = READ). PUT upserts: repeat it to change the level. To revoke, use DELETE rather than accessLevel 0.

Request body

{
  "accessLevel": 1
}

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/libraries/admin%3Aengineering-docs/shares/annie.larson"
    }
  },
  "tenant": "acme",
  "id": "00000000-0000-4000-8000-000000000001",
  "libraryId": "00000000-0000-4000-8000-000000000002",
  "principalId": "annie.larson",
  "accessLevel": 1,
  "updatedAt": "2026-01-15T16:20:00.000Z",
  "createdAt": "2026-01-15T16:20:00.000Z"
}

Captured from the API examples test suite; ids and timestamps are normalized.

---

DELETE /api/libraries/{id}/shares/{principalId}

Revoke a principal's share.

Authentication: Required

Permissions: Requires library:share

Path Parameters:

Parameter	Type	Description
id	string	Library id or natural id
principalId	string	A username (user) or a team id

Response:

Responds 200 with an empty body.

Remove a shareDELETE /api/libraries/admin:engineering-docs/shares/annie.larson

Revokes the principal’s access. Responds 200 with an empty body.

Response · 200 · no body

Captured from the API examples test suite; ids and timestamps are normalized.