# APIs

```
Click the button below to test in Postman:
```

[![Run in Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/30505873-527be40b-f8d9-4ec8-b0d6-be848dd5ca0c?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D30505873-527be40b-f8d9-4ec8-b0d6-be848dd5ca0c%26entityType%3Dcollection%26workspaceId%3Dc5dd2f9d-7fd9-4b9b-91e0-9fe3b8e1be7d)

### Authorization

To interact with the Luvre API, all requests must include a JWT access token for authentication and authorization. This ensures secure access control, allowing the system to verify user identity, roles, domain and permissions.

**How the Token Works**

The access token is generated using **JSON Web Token (JWT)** and includes the following payload:

```php
$payload = [ 
    'uid'    => $uid,        // User ID
    'uname'  => $uname,      // Username
    'uroles' => $uroles,     // User roles (e.g., admin, editor)
    'dom'    => $dom,        // Token domain (must match site domain)
    'iat'    => $iat,        // Issued at timestamp
    'exp'    => $exp,        // Expiration timestamp
];
```

**Key Features of the Token**

✅ **User Identification** – The token contains the **user ID** and **username** to authenticate the requester.\
✅ **Role-Based Access** – The **uroles** field defines user permissions, ensuring API access is restricted based on roles.\
✅ **Domain Validation** – The **dom** field ensures the token is only valid on the intended domain, preventing misuse.\
✅ **Expiration Control** – The **exp** field sets a time limit for token validity, improving security.

**Managing Access Tokens**

* Tokens must be sent in the **Authorization** header as a **Bearer token** in API requests:\
  `Authorization: Bearer YOUR_ACCESS_TOKEN`
* If the token is missing, expired, or invalid, the API will reject the request with an appropriate error response.
* Administrators can manage token expiration, role-based access, and domain restrictions easily.

This approach ensures a **secure and flexible authentication system**, making it easier to manage user access, roles, and permissions across the API. 🚀

<figure><img src="/files/g5TbUPH02qNskLVNggoO" alt=""><figcaption><p>Luvre Token Generator</p></figcaption></figure>

## Get All Folders

<mark style="color:blue;">`GET`</mark>`https://yoursite.com/wp-json/luvre/public/v1/folder/folders`

Retrieves a list of folders based on various filter parameters such as order, owner, and inclusion of attachment data.

**Headers**

| Name          | Type     | Value            |
| ------------- | -------- | ---------------- |
| Authorization | `string` | `Bearer <token>` |

**Parameters**

| Name             | Type      | Description                                           | Required |
| ---------------- | --------- | ----------------------------------------------------- | -------- |
| order            | `string`  | Sorting order: ASC or DESC                            | No       |
| orderby          | `string`  | Sorting field: ord, name, created                     | No       |
| owner-id         | `int`     | Get folders owned by a specific user (Admin-only)     | No       |
| all-folders      | `boolean` | If 1, retrieves all folders across users (Admin-only) | No       |
| attachments-data | `boolean` | If 1, includes attachment details                     | No       |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "success": true,
    "data": {
        "folders": [{
            "id": 4,
            "name": "Products",
            "color": "#07C4B3",
            "parent": 0,
            "post_type": "attachment",
            "ord": 0,
            "created_by": 1,
            "created": "2025-03-25 15:37:18",
            "attachments_count": 1,
            "attachment_ids": [12249],
            "children": [{
                "id": 9,
                "name": "Polo",
                "color": "#03A9F4",
                "parent": 4,
                "post_type": "attachment",
                "ord": 0,
                "created_by": 1,
                "created": "2025-03-25 15:46:22",
                "attachments_count": 0,
                "attachment_ids": [],
                "children": []
            }]
        }, {
            "id": 1,
            "name": "My Posts",
            "color": "#2196F3",
            "parent": 0,
            "post_type": "post",
            "ord": 1,
            "created_by": 1,
            "created": "2025-03-04 18:11:44",
            "attachments_count": 1,
            "attachment_ids": [12337],
            "children": []
        }]
    }
}
```

{% endtab %}

{% tab title="401" %}

```json
{
  "errors": [
    {
      "code": "invalid_token",
      "message": "Invalid token",
      "status": 401
    },
    {
      "code": "token_expired",
      "message": "The token has expired",
      "status": 401
    },
    {
      "code": "invalid_user",
      "message": "Invalid user credentials",
      "status": 401
    },
    {
      "code": "user_mismatch",
      "message": "User ID mismatch",
      "status": 401
    }
  ]
}
```

{% endtab %}

{% tab title="403" %}

```json
{
  "errors": [
    {
      "code": "invalid_domain",
      "message": "The token domain does not match the site domain",
      "status": 403
    },
    {
      "code": "invalid_role",
      "message": "User does not have the required role(s)",
      "status": 403
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## Get Folder by ID

<mark style="color:blue;">`GET`</mark>`https://yoursite.com/wp-json/luvre/public/v1/folder/get/:folder_id`

Fetches a specific folder by ID, with an option to include attachment data.

**Headers**

| Name          | Type     | Value            |
| ------------- | -------- | ---------------- |
| Authorization | `string` | `Bearer <token>` |

**Parameters**

| Name             | Type      | Description                       | Required |
| ---------------- | --------- | --------------------------------- | -------- |
| id               | `int`     | The folder ID to retrieve         | ✅ Yes    |
| attachments-data | `boolean` | If 1, includes attachment details | No       |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "success": true,
    "data": {
        "folders": [{
            "id": 4,
            "name": "Parent",
            "color": "#07C4B3",
            "parent": 0,
            "post_type": "attachment",
            "ord": 0,
            "created_by": 1,
            "created": "2025-03-25 15:37:18",
            "attachments_count": 1,
            "attachment_ids": [12249],
            "children": []
        }]
    }
}
```

{% endtab %}

{% tab title="401" %}

```json
{
  "errors": [
    {
      "code": "invalid_token",
      "message": "Invalid token",
      "status": 401
    },
    {
      "code": "token_expired",
      "message": "The token has expired",
      "status": 401
    },
    {
      "code": "invalid_user",
      "message": "Invalid user credentials",
      "status": 401
    },
    {
      "code": "user_mismatch",
      "message": "User ID mismatch",
      "status": 401
    }
  ]
}
```

{% endtab %}

{% tab title="403" %}

```json
{
  "errors": [
    {
      "code": "invalid_domain",
      "message": "The token domain does not match the site domain",
      "status": 403
    },
    {
      "code": "invalid_role",
      "message": "User does not have the required role(s)",
      "status": 403
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## Create a New Folder

<mark style="color:green;">`POST`</mark>`https://yoursite.com/wp-json/luvre/public/v1/folder/create`

Creates a new folder with a specified parent, name, and post type.

**Headers**

| Name          | Type     | Value            |
| ------------- | -------- | ---------------- |
| Authorization | `string` | `Bearer <token>` |

**Request Body**

| Name       | Type     | Description                                           | Required |
| ---------- | -------- | ----------------------------------------------------- | -------- |
| parent\_id | `int`    | ID of the parent folder. Set 0 to make as root folder | ✅ Yes    |
| name       | `string` | Name of the folder                                    | ✅ Yes    |
| post\_type | `string` | Post type (e.g., attachment)                          | ✅ Yes    |

**Example** Request **Body (json)**

```json
{
    "parent_id": 100,
    "name": "New Folder via Api",
    "post_type": "attachment"
}
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "success": true,
    "data": {
        "name": "New Folder via Api",
        "id": 107,
        "parent": 100
    }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "errors": [
    {
      "code": "folder_name_exist",
      "message": "A folder with this name already exists. Please choose another one",
      "status": 400
    },
    {
      "code": "parent_not_exist",
      "message": "Parent folder not found",
      "status": 400
    }
  ]
}
```

{% endtab %}

{% tab title="401" %}

```json
{
  "errors": [
    {
      "code": "invalid_token",
      "message": "Invalid token",
      "status": 401
    },
    {
      "code": "token_expired",
      "message": "The token has expired",
      "status": 401
    },
    {
      "code": "invalid_user",
      "message": "Invalid user credentials",
      "status": 401
    },
    {
      "code": "user_mismatch",
      "message": "User ID mismatch",
      "status": 401
    }
  ]
}
```

{% endtab %}

{% tab title="403" %}

```json
{
  "errors": [
    {
      "code": "invalid_domain",
      "message": "The token domain does not match the site domain",
      "status": 403
    },
    {
      "code": "invalid_role",
      "message": "User does not have the required role(s)",
      "status": 403
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## Assign Attachments to a Folder

<mark style="color:green;">`POST`</mark>`https://yoursite.com/wp-json/luvre/public/v1/attachment/add`&#x20;

Assigns attachments to a specific folder.

**Headers**

| Name          | Type     | Value            |
| ------------- | -------- | ---------------- |
| Authorization | `string` | `Bearer <token>` |

**Request Body**

| Name       | Type           | Description                         | Required |
| ---------- | -------------- | ----------------------------------- | -------- |
| folder\_id | `int`          | The folder ID to add attachments to | ✅ Yes    |
| ids        | `array or int` | Attachment ID(s)                    | ✅ Yes    |

**Example** Request **Body (json)**

***Single id***

```json
{
  "folder_id": 75,
  "ids": 12243
}
```

*Multiple ids*

```json
{
  "folder_id": 75,
  "ids": [12243, 12181, 11326, 11328]
}
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "success": true,
    "data": {
        "message": "insert_success",
        "folder_data": {
            "id": "75",
            "name": "New Folder",
            "color": "#03A9F4",
            "parent": "0",
            "post_type": "attachment",
            "ord": "1",
            "created_by": "1",
            "created": "2025-03-25 15:37:22",
            "attachments_count": "4",
            "attachment_ids": ["11326", "11328", "12181", "12243"]
        }
    }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "errors": [
    {
      "code": "empty_ids",
      "message": "ids parameter cannot be empty",
      "status": 400
    },
    {
      "code": "folder_not_exist",
      "message": "The requested folder does not exist",
      "status": 400
    },
    {
      "code": "attachment_exists",
      "message": "Some attachment already exist in this folder",
      "status": 400
    }
  ]
}
```

{% endtab %}

{% tab title="401" %}

```json
{
  "errors": [
    {
      "code": "invalid_token",
      "message": "Invalid token",
      "status": 401
    },
    {
      "code": "token_expired",
      "message": "The token has expired",
      "status": 401
    },
    {
      "code": "invalid_user",
      "message": "Invalid user credentials",
      "status": 401
    },
    {
      "code": "user_mismatch",
      "message": "User ID mismatch",
      "status": 401
    }
  ]
}
```

{% endtab %}

{% tab title="403" %}

```json
{
  "errors": [
    {
      "code": "invalid_domain",
      "message": "The token domain does not match the site domain",
      "status": 403
    },
    {
      "code": "invalid_role",
      "message": "User does not have the required role(s)",
      "status": 403
    }
  ]
}
```

{% endtab %}
{% endtabs %}

### 🚫 Authentication Failed (403 Error) Even with Correct Token

If you're seeing an error like this when making a request to the REST API:

```json
{
  "code": "rest_forbidden",
  "message": "Authentication failed",
  "data": {
    "status": 403
  }
}
```

Even though your **Bearer Token** is correctly set in Postman (or any API client), this typically means that the token is not reaching WordPress due to how your server handles HTTP headers—especially the `Authorization` header.

#### 🛠️ Fix for Apache Servers

If you're using **Apache**, it's likely that the `Authorization` header is being stripped or not passed correctly to WordPress.

To fix this, you need to add the following line to your site’s `.htaccess` file:

```apacheconf
SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1
```

* Open your `.htaccess` file (usually located in your WordPress root directory).
* Add the line above just before the WordPress rules section.
* Save the file and try your API request again.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ghozylab.gitbook.io/plugins/details/luvre/developer/restapi.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.