> For the complete documentation index, see [llms.txt](https://ninjateam.gitbook.io/filebird/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ninjateam.gitbook.io/filebird/integrations/developer-zone/post-type-folders-api.md).

# Post Type Folders API

These endpoints manage FileBird folders for **custom post types**, as opposed to the media/attachment folders. They are authenticated with the same Bearer Token as the other public endpoints.

{% hint style="info" %}
The `post_type` must be enabled in **FileBird → Settings → Folders for post types**. Requests for a post type that is not enabled return a `post_type_not_enable` error.
{% endhint %}

### Get Post Type Folders

GET `https://your-site.com/wp-json/filebird/public/v1/post-type-folders/?post_type=`

Get the folder tree of a given post type.

**Query Parameters**

| Name       | Type   | Description                                            |
| ---------- | ------ | ------------------------------------------------------ |
| post\_type | string | **Required.** The post type slug (e.g. `post`, `page`) |
| order      | string | Optional. Sort by name: `asc` or `desc`                |

**Headers**

| Name          | Type   | Description  |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer Token |

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

```json
{
  "success": true,
  "data": {
    "folders": [
      {
        "id": 12,
        "key": 12,
        "title": "My Folder",
        "text": "My Folder",
        "data-id": 12,
        "data-count": 0,
        "color": "",
        "parent": 0,
        "children": []
      }
    ]
  }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "success": false,
  "data": {
    "mess": "Post Type not enabled."
  }
}
```

{% endtab %}
{% endtabs %}

### Get Posts in a Folder

GET `https://your-site.com/wp-json/filebird/public/v1/post-type-folder/posts/?post_type=&folder_id=`

Get the list of post IDs that belong to a folder of a given post type. This is the post-type equivalent of filtering media by folder. Supports pagination.

{% hint style="info" %}
`folder_id` follows the same convention as the media API:

* `-1` → all posts, regardless of folder
* `0` → uncategorized (posts not in any folder)
* `> 0` → posts inside that folder
  {% endhint %}

**Query Parameters**

| Name       | Type    | Description                                                       |
| ---------- | ------- | ----------------------------------------------------------------- |
| post\_type | string  | **Required.** The post type slug (e.g. `post`, `page`)            |
| folder\_id | integer | **Required.** `-1` = all, `0` = uncategorized, `>0` = that folder |
| per\_page  | integer | Optional. Items per page (default `50`, `-1` = all)               |
| page       | integer | Optional. Page number (default `1`)                               |

**Headers**

| Name          | Type   | Description  |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer Token |

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

```json
{
  "success": true,
  "data": {
    "post_ids": [ 128, 126, 119, 87 ],
    "total": 4,
    "total_pages": 1,
    "page": 1,
    "per_page": 50
  }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "success": false,
  "data": {
    "mess": "Post Type not enabled."
  }
}
```

{% endtab %}
{% endtabs %}

### Create Post Type Folder

POST `https://your-site.com/wp-json/filebird/public/v1/post-type-folders`

Create a new folder in a post type's taxonomy.

**Body Parameters**

| Name       | Type    | Description                              |
| ---------- | ------- | ---------------------------------------- |
| post\_type | string  | **Required.** The post type slug         |
| title      | string  | **Required.** Folder name                |
| parent     | integer | Optional. Parent folder id (default `0`) |

**Headers**

| Name          | Type   | Description  |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer Token |

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

```json
[
  {
    "id": 34,
    "key": 34,
    "data-id": 34,
    "parent": 0,
    "data-count": 0,
    "children": [],
    "title": "New Folder"
  }
]
```

{% endtab %}

{% tab title="error" %}

```json
{
  "code": "folder_name_exist",
  "message": "A folder with this name already exists. Please choose another one.",
  "data": { "status": 500 }
}
```

{% endtab %}
{% endtabs %}

### Update Post Type Folder

POST `https://your-site.com/wp-json/filebird/public/v1/post-type-folder/update`

Rename a folder and/or move it to another parent.

**Body Parameters**

| Name       | Type    | Description                           |
| ---------- | ------- | ------------------------------------- |
| post\_type | string  | **Required.** The post type slug      |
| id         | integer | **Required.** The folder id to update |
| title      | string  | **Required.** New folder name         |
| parent     | integer | Optional. New parent folder id        |

**Headers**

| Name          | Type   | Description  |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer Token |

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

```json
true
```

{% endtab %}

{% tab title="error" %}

```json
{
  "code": "folder_update_fail",
  "message": "Could not edit this folder",
  "data": { "status": 500 }
}
```

{% endtab %}
{% endtabs %}

### Delete Post Type Folder

POST `https://your-site.com/wp-json/filebird/public/v1/post-type-folder/delete`

Delete one or more folders (and their sub-folders) of a post type. Returns the updated folder counters.

**Body Parameters**

| Name       | Type       | Description                                        |
| ---------- | ---------- | -------------------------------------------------- |
| post\_type | string     | **Required.** The post type slug                   |
| ids        | integer\[] | **Required.** Folder id, or an array of folder ids |

**Headers**

| Name          | Type   | Description  |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer Token |

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

```json
{
  "display": {
    "12": 3,
    "15": 0
  },
  "actual": {
    "12": 3,
    "15": 0
  }
}
```

{% endtab %}

{% tab title="error" %}

```json
{
  "code": "delete_fail",
  "message": "Can't delete folder, please try again later",
  "data": { "status": 500 }
}
```

{% endtab %}
{% endtabs %}

### Assign Posts to Folder

POST `https://your-site.com/wp-json/filebird/public/v1/post-type-folder/set-posts`

Move one or more posts into a folder. Use `folderId = 0` to remove the posts from their current folder. Returns the updated folder counters.

**Body Parameters**

| Name       | Type       | Description                                                    |
| ---------- | ---------- | -------------------------------------------------------------- |
| post\_type | string     | **Required.** The post type slug                               |
| folderId   | integer    | **Required.** Target folder id (`0` to move out of any folder) |
| ids        | integer\[] | **Required.** Array of post ids to assign                      |

**Headers**

| Name          | Type   | Description  |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer Token |

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

```json
{
  "display": {
    "12": 5
  },
  "actual": {
    "12": 5
  }
}
```

{% endtab %}

{% tab title="error" %}

```json
{
  "code": "validation_failed",
  "message": "Validation failed",
  "data": { "status": 500 }
}
```

{% endtab %}
{% endtabs %}