---
title: Shares Reference
path: reference/shares
status: published
---

All share endpoints including members and invitations.

**Base path:** `/api/v1/shares/`

## Share object

```json
{
  "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:**

| Param | Notes |
|-------|-------|
| `include_trashed` | Include soft-deleted, default false |
| `limit` | 1–100, default 50 |
| `offset` | Pagination |

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

## POST /api/v1/shares

Create a share. Returns 201.

**Body:**

| Field | Required | Notes |
|-------|----------|-------|
| `name` | Yes | Display name |
| `share_type` | Yes | `central`, `personal`, `project` |
| `owner_id` | Yes | `usr_...` or `grp_...` |
| `description` | No | |
| `quota_bytes` | No | Omit to inherit tenant quota |

**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:**

| Param | Notes |
|-------|-------|
| `q` | Min 1 character |
| `principal_type` | `user` or `group`; omit for both |
| `limit` | 1–50, default 20 |

**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:

```json
{
  "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:**

```json
{
  "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:

```json
{
  "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:**

| Field | Required | Notes |
|-------|----------|-------|
| `email` | Yes | |
| `role` | Yes | |
| `message` | No | Shown in invitation email |
| `expires_in_days` | No | Default 14, max 90 |

**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

| Code | HTTP | When |
|------|------|------|
| `SHARE_MEMBER_EXISTS` | 409 | Principal is already a member |
| `SHARE_INVITATION_EXPIRED` | 410 | Past token expiry |
| `SHARE_INVITATION_ALREADY_USED` | 409 | Accepted/declined already |
| `AUTHZ_PERMISSION_DENIED` | 403 | Missing required permission |

## Related

- [Sharing Guide](/docs/scaidrive/api-guides/sharing)
- [Shares and Ownership](/docs/scaidrive/core-concepts/shares-and-ownership)
- [Permissions Reference](/docs/scaidrive/reference/permissions)