Shares Reference

All share endpoints including members and invitations.

Base path: /api/v1/shares/

Share object#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  "id": "shr_01J3H",
  "tenant_id": "tnt_01J3A",
  "name": "Engineering",
  "description": "Engineering org shared drive",
  "share_type": "central",
  "owner_id": "grp_01J3L",
  "is_public": false,
  "is_deleted": false,
  "quota_bytes": 107374182400,
  "used_bytes": 42301234567,
  "settings": {},
  "created_at": "2026-01-15T08:00:00Z",
  "modified_at": "2026-04-22T14:30:00Z"
}

GET /api/v1/shares#

List shares visible to the caller.

Query:

Response: {shares: [...], total: N}.

POST /api/v1/shares#

Create a share. Returns 201.

Body:

Response: Full share object.

GET /api/v1/shares/{share_id}#

Single share.

Required permission: READ on the share.

PATCH /api/v1/shares/{share_id}#

Update share metadata.

Body: name, description.

Required permission: MANAGE_PERMISSIONS.

DELETE /api/v1/shares/{share_id}#

Soft-delete the share.

Required permission: MANAGE_PERMISSIONS.

GET /api/v1/shares/search/principals#

Search users and groups for member selection.

Query:

Response: {users: [...], groups: [...]}.

Share members#

GET /api/v1/shares/{share_id}/members#

List members of a share.

Query: limit, offset.

Required permission: READ.

Response: {members: [...], total: N}. Each member:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
  "principal_type": "user",
  "principal_id": "usr_01J4M",
  "principal_name": "Alice Cooper",
  "principal_email": "alice@example.com",
  "role": "contributor",
  "granted_by": "usr_01J3N",
  "granted_at": "2026-03-01T09:15:00Z",
  "expires_at": null
}

POST /api/v1/shares/{share_id}/members#

Add a member. Returns 201.

Body:

1
2
3
4
5
6

{
  "principal_type": "user",
  "principal_id": "usr_01J4M",
  "role": "contributor",
  "expires_at": "2026-07-01T00:00:00Z"
}

Required permission: MANAGE_PERMISSIONS.

PATCH /api/v1/shares/{share_id}/members/{principal_id}#

Change role or expiry.

Body: role, expires_at.

Required permission: MANAGE_PERMISSIONS.

DELETE /api/v1/shares/{share_id}/members/{principal_id}#

Remove member. Returns 204.

Required permission: MANAGE_PERMISSIONS.

Invitations#

GET /api/v1/shares/{share_id}/invitations#

List invitations on a share.

Query: limit, offset, status (pending, accepted, declined, expired, revoked; default pending).

Required permission: READ.

Response: {invitations: [...], total: N}. Each:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
  "id": "inv_01J5N",
  "share_id": "shr_01J3H",
  "email": "partner@external.com",
  "role": "reader",
  "status": "pending",
  "invited_by": "usr_01J3N",
  "message": "...",
  "token_expires_at": "2026-05-07T10:15:00Z"
}

POST /api/v1/shares/{share_id}/invite#

Create invitation. Returns 201.

Body:

Required permission: MANAGE_PERMISSIONS.

Email is sent via ScaiSend. The invitation token is embedded in the email link.

DELETE /api/v1/shares/{share_id}/invitations/{invitation_id}#

Revoke invitation. Returns 204.

Required permission: MANAGE_PERMISSIONS.

Error codes#

Related#

• Sharing Guide
• Shares and Ownership
• Permissions Reference