> For the complete documentation index, see [llms.txt](https://docs.zus.network/zus-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zus.network/zus-docs/http-apis/obox-api/file-sharing-and-share-requests.md).

# File Sharing and Share Requests

### **File Sharing**

These endpoints supports secure data sharing using auth tickets, share links, and metadata across user wallets.

#### **Insert Share Info**

* **Path:** `/v2/shareinfo`
* **Method:** `POST`
* **Access:** Signature API
* **Description:**\
  Creates a new share record using an auth\_ticket, which encapsulates access rights.
* **Headers Required:** `AuthHeader`
* **Form Data (multipart/form-data):**
  * `auth_ticket` (string, required)
  * `message` (string, optional)
  * `share_info_type` (string, optional, e.g. `public` or `private`)
  * `link` (string, optional)
* **Response:**

```json
{
  "message": "shareinfo added successfully",
  "data": {
    "auth_ticket": "base64ticket...",
    "message": "Here is your file",
    "share_info_type": "private",
    "client_id": "sender_client_id",
    "receiver": "receiver_client_id",
    "lookup_hash": "lookuphash123",
    "sender_name": "Alice",
    "link": "https://share.link",
    "receiver_name": "Bob"
  }
}
```

#### **Get Shared Files (Sent)**

* **Path:** `/v2/shareinfo/shared`
* **Method:** `GET`
* **Access:** Signature API
* **Description:**\
  Retrieves files the user has shared with others.
* **Query Parameters:**
  * `limit` (optional)
  * `offset` (optional)
  * `lookup_hash` (optional)
  * `shareInfoType` (required: e.g. `public`, `private`)
  * `exclude_ai` (optional): `"true"` to exclude AI-related shares
* **Response:**

```json
{
  "message": "Data is present for the given details",
  "data": [
    {
      "id": 1,
      "auth_ticket": "base64ticket...",
      "message": "Shared with you",
      "share_info_type": "private",
      "receiver_client_id": "receiver_client_id",
      "link": "https://share.link",
      "receiver_name": "Bob",
      "lookup_hash": "lookuphash123",
      "created_at": "2025-06-04T12:00:00",
      "updated_at": "2025-06-04T12:00:00"
    }
  ]
}
```

#### **Get Shared Files (Received)**

* **Path:** `/v2/shareinfo/received`
* **Method:** `GET`
* **Access:** Signature API
* **Description:**\
  Retrieves files that others have shared with the user.
* **Query Parameters:**
  * `limit`, `offset`, `lookup_hash` (optional)
  * `shareInfoType` (required)
* **Response:**

```json
{
  "message": "Data is present for the given details",
  "data": [
    {
      "auth_ticket": "base64ticket...",
      "message": "Here is your file",
      "share_info_type": "private",
      "client_id": "sender_client_id",
      "receiver_client_id": "receiver_client_id",
      "lookup_hash": "lookuphash123",
      "sender_name": "Alice",
      "created_at": "2025-06-04T12:00:00",
      "updated_at": "2025-06-04T12:00:00"
    }
  ]
}
```

#### **Delete Share Info**

* **Path:** `/v2/shareinfo`
* **Method:** `DELETE`
* **Access:** Signature API
* **Query Parameters (at least one required):**
  * `auth_ticket` (string)
  * `lookup_hash` (string)
* **Response (Success):**

```json
{
  "message": "deleting shareinfo successful"
}
```

* **If nothing was deleted:**

```json
{
  "message": "no shareinfo was deleted for these details"
}
```

***

### **Share Requests**

These endpoints handles inbound and outbound requests for accessing shared files or permissions.

#### **Create Share Request**

* **Path:** `/v2/sharereq`
* **Method:** `POST`
* **Access:** Signature API
* **Description:**\
  Used to request access to someone else's file. Allows one-time re-request if previously declined.
* **Body:**

```json
{
  "owner_id": "ownerid",
  "auth_ticket": "base64ticket...",
  "lookup_hash": "lookuphash",
  "message": "Please share this file"
}
```

* **Response:**

```json
{
  "message": "New Share Request is created"
}
```

#### **Get Received Share Requests**

* **Path:** `/v2/sharereq/received`
* **Method:** `GET`
* **Access:** Signature API
* **Description:**\
  Lists all incoming share requests for the user.
* **Query Parameters (optional):**\
  `client_id`, `lookup_hash`, `status`, `all`, `offset`, `limit`
* **Response:**

```json
{
  "message": "Data is present for the given details",
  "data": [
    {
      "id": "reqid1",
      "owner_id": "ownerid",
      "client_id": "clientid",
      "lookup_hash": "lookuphash",
      "status": "pending",
      "message": "Please share this file",
      "created_at": "2025-06-04T12:00:00"
    }
  ]
}
```

#### **Get Sent Share Requests**

* **Path:** `/v2/sharereq/requested`
* **Method:** `GET`
* **Access:** Signature API
* **Description:**\
  Lists all share requests sent by the user.
* **Query Parameters (optional):**\
  `owner_id`, `lookup_hash`, `status`, `all`, `offset`, `limit`
* **Response:**{

```json
  "message": "Data is present for the given details",
  "data": [
    {
      "id": "reqid2",
      "owner_id": "ownerid",
      "client_id": "clientid",
      "lookup_hash": "lookuphash",
      "status": "approved",
      "message": "Requesting access",
      "created_at": "2025-06-04T12:00:00"
    }
  ]
}
```

#### **Update Share Request**

* **Path:** `/v2/sharereq`
* **Method:** `PUT`
* **Access:** Signature API
* **Description:**\
  Updates a share request (usually to approve it). Also writes to `ShareInfo` table using the `auth_ticket`.
* **Body:**

```json
{
  "id": "reqid1",
  "status": "approved",
  "link": "https://share.link",
  "auth_ticket": "base64ticket..."
}
```

* **Response:**

```json
{
  "message": "share request updated successfully"
}
```

#### **Delete Share Request**

* **Path:** `/v2/sharereq`
* **Method:** `DELETE`
* **Access:** Signature API
* **Query Parameters:**
  * `id` (string, required)
* **Response:**

```json
{
  "message": "share request deleted successfully"
}
```