> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinkfish.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# cloudinary-organization

> Cloudinary Organization — search assets, manage folders, people, and usage

**Server path:** `/cloudinary-organization` | **Type:** Application | **PCID required:** Yes

## Tools

| Tool                                                                                            | Description                                                                             |
| ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| [`cloudinary_organization_assign_folder_roles`](#cloudinary_organization_assign_folder_roles)   | Assign folder roles                                                                     |
| [`cloudinary_organization_create_folder`](#cloudinary_organization_create_folder)               | Creates a new empty folder in your Cloudinary media library                             |
| [`cloudinary_organization_destroy_folder`](#cloudinary_organization_destroy_folder)             | Deletes an existing folder from your media library                                      |
| [`cloudinary_organization_get_folder_roles`](#cloudinary_organization_get_folder_roles)         | Get folder roles                                                                        |
| [`cloudinary_organization_get_person`](#cloudinary_organization_get_person)                     | Get person details                                                                      |
| [`cloudinary_organization_get_usage`](#cloudinary_organization_get_usage)                       | Retrieves comprehensive usage metrics and account statistics                            |
| [`cloudinary_organization_list_people`](#cloudinary_organization_list_people)                   | List recognized people                                                                  |
| [`cloudinary_organization_list_root_folders`](#cloudinary_organization_list_root_folders)       | Get root folders                                                                        |
| [`cloudinary_organization_search_assets`](#cloudinary_organization_search_assets)               | Provides a powerful query interface to filter and retrieve assets and their details     |
| [`cloudinary_organization_search_folders`](#cloudinary_organization_search_folders)             | Searches for folders whose attributes match a given expression                          |
| [`cloudinary_organization_search_folders_post`](#cloudinary_organization_search_folders_post)   | Searches for folders in your product environment                                        |
| [`cloudinary_organization_show_folder`](#cloudinary_organization_show_folder)                   | List sub-folders                                                                        |
| [`cloudinary_organization_update_folder`](#cloudinary_organization_update_folder)               | Renames or moves an entire folder (along with all assets it contains) to a new location |
| [`cloudinary_organization_update_person`](#cloudinary_organization_update_person)               | Update a person                                                                         |
| [`cloudinary_organization_visual_search_assets`](#cloudinary_organization_visual_search_assets) | Finds images in your asset library based on visual similarity or content                |

***

## cloudinary\_organization\_assign\_folder\_roles

Assign folder roles

**Parameters:**

| Parameter   | Type      | Required | Default | Description                                                                                                            |
| ----------- | --------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
| `folder_id` | string    | Yes      | —       | The immutable identifier of the folder, returned by the Get root folders and Get subfolders endpoints.                 |
| `operation` | string    | Yes      | —       | The operation to perform on the principal’s role assignments. `add` grants the specified roles; `remove` revokes them. |
| `principal` | object    | Yes      | —       | The user, group, or API key whose role assignments are being modified.                                                 |
| `roles`     | string\[] | Yes      | —       | The role IDs to add or remove.                                                                                         |

<Expandable title="inputSchema">
  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "PCID": {
        "type": "string",
        "description": "Pink Connect ID for the authenticated connection"
      },
      "folder_id": {
        "type": "string",
        "description": "The immutable identifier of the folder, returned by the Get root folders and Get subfolders endpoints."
      },
      "operation": {
        "type": "string",
        "description": "The operation to perform on the principal’s role assignments. `add` grants the specified roles; `remove` revokes them.",
        "enum": [
          "add",
          "remove"
        ]
      },
      "principal": {
        "type": "object",
        "description": "The user, group, or API key whose role assignments are being modified.",
        "properties": {
          "type": {
            "type": "string",
            "description": "The type of principal.",
            "enum": [
              "user",
              "group",
              "apiKey"
            ]
          },
          "id": {
            "type": "string",
            "description": "The unique identifier of the principal. For `apiKey`, provide the API key value."
          }
        },
        "required": [
          "type",
          "id"
        ]
      },
      "roles": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "The role IDs to add or remove."
      }
    },
    "required": [
      "PCID",
      "folder_id",
      "operation",
      "principal",
      "roles"
    ]
  }
  ```
</Expandable>

***

## cloudinary\_organization\_create\_folder

Creates a new empty folder in your Cloudinary media library

**Parameters:**

| Parameter | Type   | Required | Default | Description                                                         |
| --------- | ------ | -------- | ------- | ------------------------------------------------------------------- |
| `folder`  | string | Yes      | —       | The path of the folder to operate on, including any nested folders. |

<Expandable title="inputSchema">
  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "PCID": {
        "type": "string",
        "description": "Pink Connect ID for the authenticated connection"
      },
      "folder": {
        "type": "string",
        "description": "The path of the folder to operate on, including any nested folders."
      }
    },
    "required": [
      "PCID",
      "folder"
    ]
  }
  ```
</Expandable>

***

## cloudinary\_organization\_destroy\_folder

Deletes an existing folder from your media library

**Parameters:**

| Parameter | Type   | Required | Default | Description                                                         |
| --------- | ------ | -------- | ------- | ------------------------------------------------------------------- |
| `folder`  | string | Yes      | —       | The path of the folder to operate on, including any nested folders. |

<Expandable title="inputSchema">
  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "PCID": {
        "type": "string",
        "description": "Pink Connect ID for the authenticated connection"
      },
      "folder": {
        "type": "string",
        "description": "The path of the folder to operate on, including any nested folders."
      }
    },
    "required": [
      "PCID",
      "folder"
    ]
  }
  ```
</Expandable>

***

## cloudinary\_organization\_get\_folder\_roles

Get folder roles

**Parameters:**

| Parameter         | Type    | Required | Default | Description                                                                                                                                       |
| ----------------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `folder_id`       | string  | Yes      | —       | The immutable identifier of the folder, returned by the Get root folders and Get subfolders endpoints.                                            |
| `permitted_roles` | boolean | No       | —       | Whether to include in the response the roles the authenticated user can assign on this folder, based on their permission level. Default: `false`. |

<Expandable title="inputSchema">
  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "PCID": {
        "type": "string",
        "description": "Pink Connect ID for the authenticated connection"
      },
      "folder_id": {
        "type": "string",
        "description": "The immutable identifier of the folder, returned by the Get root folders and Get subfolders endpoints."
      },
      "permitted_roles": {
        "type": "boolean",
        "description": "Whether to include in the response the roles the authenticated user can assign on this folder, based on their permission level. Default: `false`."
      }
    },
    "required": [
      "PCID",
      "folder_id"
    ]
  }
  ```
</Expandable>

***

## cloudinary\_organization\_get\_person

Get person details

**Parameters:**

| Parameter   | Type   | Required | Default | Description                          |
| ----------- | ------ | -------- | ------- | ------------------------------------ |
| `person_id` | string | Yes      | —       | The unique identifier of the person. |

<Expandable title="inputSchema">
  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "PCID": {
        "type": "string",
        "description": "Pink Connect ID for the authenticated connection"
      },
      "person_id": {
        "type": "string",
        "description": "The unique identifier of the person."
      }
    },
    "required": [
      "PCID",
      "person_id"
    ]
  }
  ```
</Expandable>

***

## cloudinary\_organization\_get\_usage

Retrieves comprehensive usage metrics and account statistics

**Parameters:**

| Parameter | Type   | Required | Default | Description                                                                                        |
| --------- | ------ | -------- | ------- | -------------------------------------------------------------------------------------------------- |
| `date`    | string | No       | —       | The date for which to retrieve usage details. If not specified, returns the current month's usage. |

<Expandable title="inputSchema">
  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "PCID": {
        "type": "string",
        "description": "Pink Connect ID for the authenticated connection"
      },
      "date": {
        "type": "string",
        "description": "The date for which to retrieve usage details. If not specified, returns the current month's usage."
      }
    },
    "required": [
      "PCID"
    ]
  }
  ```
</Expandable>

***

## cloudinary\_organization\_list\_people

List recognized people

**Parameters:**

| Parameter     | Type    | Required | Default | Description                                                                                                     |
| ------------- | ------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| `max_results` | integer | No       | —       | The maximum number of people to return. Default: 50.                                                            |
| `next_cursor` | string  | No       | —       | The cursor for pagination. Use the next\_cursor value from a previous response to get the next page of results. |
| `name_status` | string  | No       | —       | Filter by whether the person has been named. Default: all.                                                      |
| `name_prefix` | string  | No       | —       | Filter people whose names start with the given prefix (case insensitive).                                       |
| `status`      | string  | No       | —       | Filter by person status.                                                                                        |
| `sort_by`     | string  | No       | —       | The field to sort results by. Default: name (ascending).                                                        |
| `direction`   | string  | No       | —       | The sort direction for the results. Default is "desc".                                                          |

<Expandable title="inputSchema">
  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "PCID": {
        "type": "string",
        "description": "Pink Connect ID for the authenticated connection"
      },
      "max_results": {
        "type": "integer",
        "description": "The maximum number of people to return. Default: 50."
      },
      "next_cursor": {
        "type": "string",
        "description": "The cursor for pagination. Use the next_cursor value from a previous response to get the next page of results."
      },
      "name_status": {
        "type": "string",
        "description": "Filter by whether the person has been named. Default: all.",
        "enum": [
          "all",
          "named",
          "unnamed"
        ]
      },
      "name_prefix": {
        "type": "string",
        "description": "Filter people whose names start with the given prefix (case insensitive)."
      },
      "status": {
        "type": "string",
        "description": "Filter by person status.",
        "enum": [
          "active",
          "hidden"
        ]
      },
      "sort_by": {
        "type": "string",
        "description": "The field to sort results by. Default: name (ascending).",
        "enum": [
          "name",
          "created_at",
          "updated_at"
        ]
      },
      "direction": {
        "type": "string",
        "description": "The sort direction for the results. Default is \"desc\".",
        "enum": [
          "asc",
          "desc"
        ]
      }
    },
    "required": [
      "PCID"
    ]
  }
  ```
</Expandable>

***

## cloudinary\_organization\_list\_root\_folders

Get root folders

<Expandable title="inputSchema">
  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "PCID": {
        "type": "string",
        "description": "Pink Connect ID for the authenticated connection"
      }
    },
    "required": [
      "PCID"
    ]
  }
  ```
</Expandable>

***

## cloudinary\_organization\_search\_assets

Provides a powerful query interface to filter and retrieve assets and their details

**Parameters:**

| Parameter     | Type      | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------- | --------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `aggregate`   | object    | No       | —       | The aggregate value                                                                                                                                                                                                                                                                                                                                                                                                  |
| `expression`  | string    | No       | —       | The search expression. Supports exact match, wildcard match, presence, greater/less than, and range. For details on building expressions, see the Search API documentation.                                                                                                                                                                                                                                          |
| `fields`      | string    | No       | —       | A comma-separated list of fields to include in the response. Notes: - This parameter takes precedence over the with\_field parameter, so if you want any additional asset attributes returned, make sure to also include them in this list (e.g., tags or context). - The following fields are always included in the response: public\_id, asset\_id, asset\_folder, created\_at, status, type, and resource\_type. |
| `max_results` | integer   | No       | —       | The maximum number of results to return. Default - 50. Maximum - 500.                                                                                                                                                                                                                                                                                                                                                |
| `next_cursor` | string    | No       | —       | The cursor value to get the next page of results. Available when a previous search returned more results than max\_results.                                                                                                                                                                                                                                                                                          |
| `sort_by`     | object\[] | No       | —       | An array of single-key objects mapping a field to a sort direction. Each object must contain exactly one field name mapped to 'asc' or 'desc'. Default: \[\{"created\_at": "desc"}].                                                                                                                                                                                                                                 |
| `with_field`  | string\[] | No       | —       | The additional fields to include in the response. Note that the fields parameter takes precedence over this parameter.                                                                                                                                                                                                                                                                                               |

<Expandable title="inputSchema">
  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "PCID": {
        "type": "string",
        "description": "Pink Connect ID for the authenticated connection"
      },
      "aggregate": {
        "description": "The aggregate value"
      },
      "expression": {
        "type": "string",
        "description": "The search expression. Supports exact match, wildcard match, presence, greater/less than, and range. For details on building expressions, see the Search API documentation."
      },
      "fields": {
        "type": "string",
        "description": "A comma-separated list of fields to include in the response. Notes: - This parameter takes precedence over the with_field parameter, so if you want any additional asset attributes returned, make sure to also include them in this list (e.g., tags or context). - The following fields are always included in the response: public_id, asset_id, asset_folder, created_at, status, type, and resource_type."
      },
      "max_results": {
        "type": "integer",
        "description": "The maximum number of results to return. Default - 50. Maximum - 500."
      },
      "next_cursor": {
        "type": "string",
        "description": "The cursor value to get the next page of results. Available when a previous search returned more results than max_results."
      },
      "sort_by": {
        "type": "array",
        "items": {
          "type": "object"
        },
        "description": "An array of single-key objects mapping a field to a sort direction. Each object must contain exactly one field name mapped to 'asc' or 'desc'. Default: [{\"created_at\": \"desc\"}]."
      },
      "with_field": {
        "type": "array",
        "items": {
          "type": "string",
          "enum": [
            "context",
            "tags",
            "image_metadata",
            "image_analysis",
            "metadata",
            "quality_analysis",
            "accessibility_analysis"
          ]
        },
        "description": "The additional fields to include in the response. Note that the fields parameter takes precedence over this parameter."
      }
    },
    "required": [
      "PCID"
    ]
  }
  ```
</Expandable>

***

## cloudinary\_organization\_search\_folders

Searches for folders whose attributes match a given expression

**Parameters:**

| Parameter     | Type      | Required | Default | Description                                                                                                                                                  |
| ------------- | --------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `expression`  | object    | No       | —       | The (Lucene-like) string expression specifying the search query, or an object for advanced queries. If not passed, returns all folders (up to max\_results). |
| `sort_by`     | string\[] | No       | —       | An array of key-value pairs for sorting. Each value is a key and direction (asc/desc).                                                                       |
| `max_results` | integer   | No       | —       | Maximum number of folders to return (max 500, default 50).                                                                                                   |
| `next_cursor` | string    | No       | —       | The cursor for pagination. Use the next\_cursor value from a previous response to get the next page of results.                                              |

<Expandable title="inputSchema">
  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "PCID": {
        "type": "string",
        "description": "Pink Connect ID for the authenticated connection"
      },
      "expression": {
        "description": "The (Lucene-like) string expression specifying the search query, or an object for advanced queries. If not passed, returns all folders (up to max_results)."
      },
      "sort_by": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "An array of key-value pairs for sorting. Each value is a key and direction (asc/desc)."
      },
      "max_results": {
        "type": "integer",
        "description": "Maximum number of folders to return (max 500, default 50)."
      },
      "next_cursor": {
        "type": "string",
        "description": "The cursor for pagination. Use the next_cursor value from a previous response to get the next page of results."
      }
    },
    "required": [
      "PCID"
    ]
  }
  ```
</Expandable>

***

## cloudinary\_organization\_search\_folders\_post

Searches for folders in your product environment

**Parameters:**

| Parameter     | Type      | Required | Default | Description                                                                             |
| ------------- | --------- | -------- | ------- | --------------------------------------------------------------------------------------- |
| `expression`  | string    | No       | —       | The (Lucene-like) string expression specifying the search query.                        |
| `max_results` | integer   | No       | —       | Maximum number of folders to return (max 500, default 50).                              |
| `next_cursor` | string    | No       | —       | When more results are available, use the next\_cursor value from the previous response. |
| `sort_by`     | string\[] | No       | —       | An array of key-value pairs for sorting. Each value is a key and direction (asc/desc).  |

<Expandable title="inputSchema">
  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "PCID": {
        "type": "string",
        "description": "Pink Connect ID for the authenticated connection"
      },
      "expression": {
        "type": "string",
        "description": "The (Lucene-like) string expression specifying the search query."
      },
      "max_results": {
        "type": "integer",
        "description": "Maximum number of folders to return (max 500, default 50)."
      },
      "next_cursor": {
        "type": "string",
        "description": "When more results are available, use the next_cursor value from the previous response."
      },
      "sort_by": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "An array of key-value pairs for sorting. Each value is a key and direction (asc/desc)."
      }
    },
    "required": [
      "PCID"
    ]
  }
  ```
</Expandable>

***

## cloudinary\_organization\_show\_folder

List sub-folders

**Parameters:**

| Parameter | Type   | Required | Default | Description                                                         |
| --------- | ------ | -------- | ------- | ------------------------------------------------------------------- |
| `folder`  | string | Yes      | —       | The path of the folder to operate on, including any nested folders. |

<Expandable title="inputSchema">
  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "PCID": {
        "type": "string",
        "description": "Pink Connect ID for the authenticated connection"
      },
      "folder": {
        "type": "string",
        "description": "The path of the folder to operate on, including any nested folders."
      }
    },
    "required": [
      "PCID",
      "folder"
    ]
  }
  ```
</Expandable>

***

## cloudinary\_organization\_update\_folder

Renames or moves an entire folder (along with all assets it contains) to a new location

**Parameters:**

| Parameter   | Type   | Required | Default | Description                                                         |
| ----------- | ------ | -------- | ------- | ------------------------------------------------------------------- |
| `folder`    | string | Yes      | —       | The path of the folder to operate on, including any nested folders. |
| `to_folder` | string | Yes      | —       | The new path for the folder.                                        |

<Expandable title="inputSchema">
  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "PCID": {
        "type": "string",
        "description": "Pink Connect ID for the authenticated connection"
      },
      "folder": {
        "type": "string",
        "description": "The path of the folder to operate on, including any nested folders."
      },
      "to_folder": {
        "type": "string",
        "description": "The new path for the folder."
      }
    },
    "required": [
      "PCID",
      "folder",
      "to_folder"
    ]
  }
  ```
</Expandable>

***

## cloudinary\_organization\_update\_person

Update a person

**Parameters:**

| Parameter            | Type   | Required | Default | Description                                                                        |
| -------------------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------- |
| `person_id`          | string | Yes      | —       | The unique identifier of the person.                                               |
| `name`               | string | No       | —       | The display name for the person. Maximum 255 characters.                           |
| `status`             | string | No       | —       | The status of a person.                                                            |
| `thumbnail_asset_id` | string | No       | —       | The external ID of an asset containing this person's face to use as the thumbnail. |

<Expandable title="inputSchema">
  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "PCID": {
        "type": "string",
        "description": "Pink Connect ID for the authenticated connection"
      },
      "person_id": {
        "type": "string",
        "description": "The unique identifier of the person."
      },
      "name": {
        "type": "string",
        "description": "The display name for the person. Maximum 255 characters."
      },
      "status": {
        "type": "string",
        "description": "The status of a person.",
        "enum": [
          "active",
          "hidden"
        ]
      },
      "thumbnail_asset_id": {
        "type": "string",
        "description": "The external ID of an asset containing this person's face to use as the thumbnail."
      }
    },
    "required": [
      "PCID",
      "person_id"
    ]
  }
  ```
</Expandable>

***

## cloudinary\_organization\_visual\_search\_assets

Finds images in your asset library based on visual similarity or content

**Parameters:**

| Parameter | Type   | Required | Default | Description                             |
| --------- | ------ | -------- | ------- | --------------------------------------- |
| `body`    | object | Yes      | —       | Parameters for visual search operations |

<Expandable title="inputSchema">
  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "PCID": {
        "type": "string",
        "description": "Pink Connect ID for the authenticated connection"
      },
      "body": {
        "description": "Parameters for visual search operations"
      }
    },
    "required": [
      "PCID",
      "body"
    ]
  }
  ```
</Expandable>