---
title: "Create a new smart folder"
method: POST
path: "/dam/folders/{folder_id}/smart-folders"
tags: ["DAM: Folders"]
---

# Create a new smart folder

`POST /dam/folders/{folder_id}/smart-folders`

## Request

- Base URL: `https://api.kontainer.com/jsonapi/v2`
- URL: `https://api.kontainer.com/jsonapi/v2/dam/folders/{folder_id}/smart-folders`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/kontainer/apis/kontainer-api-documentation/docs/dam/folders/:folder_id/smart-folders/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a smart folder: a folder holding every file that matches its filter, kept up to date in the background. Requires a client admin token and the smart folders feature.

## Path parameters

- `folder_id` string, required

## Request body

- object
  - `data` object, required
    - `type` string, required: Resource Type
    - `attributes` object, required: Attributes
      - `name` string, required: Name
      - `description` string: Description
      - `show_large_folder_name` boolean, nullable
      - `hide_folder_name` boolean, nullable
      - `thumbs_scale_to_fit` boolean, nullable
      - `apply_folder_image_hue` boolean, nullable
      - `source_folders` object[]: Regular folders the smart folder collects files from, or with `source_folder_mode` `all_except` the folders it leaves out. Every criteria row is limited by them. Empty, the criteria match the whole library.
        - `id` integer
        - `include_subfolders` boolean
      - `source_folder_mode` 'only' | 'all_except', nullable: `only` collects from `source_folders`; `all_except` collects from every folder except them, including folders created later. Defaults to `only`, except that `source_folders` sent without it to a filter stored as `all_except` are refused. Needs `source_folders`, and is `null` when there are none.
      - `filter_config` object, nullable: The criteria. `null` when the filter only has source folders. Rows are combined with `logical_operator` (`and` or `or`, default `and`); the criteria in a row must all match, and a row without criteria matches every file in the source folders. Each criterion names a `field` and keys its value by a filter operator, as file search filters do: * `field`: `{"type": "custom_field", "id": <DAM custom field id>}` or `{"type": "file", "name": <file property>}`, where the file property is `file_extension`, `consent_status`, `consent_rights`, `ai_status`, `file_created_at` or `file_name`. * `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `like`: a single value. * `in`, `notin`: a non-empty list of the field's option ids (custom fields), extensions (`file_extension`), consent status names `no_consent`, `pending`, `have_declined`, `partial_consented`, `have_expired`, `consented` (`consent_status`), consent usage right ids (`consent_rights`), or `ai_generated`/`ai_manipulated` (`ai_status`). * `exists`: `true` when the field has a value, `false` when it is empty. A criterion has one operator, except a range: `gte` and `lte` together, or either alone for a range open at the other end. Each end is a value, or `{"days": n}` counted from today (negative in the past) on dates; both ends are the same kind. Option custom fields take `in`, `notin` and `exists`; other custom fields take `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `like` and `exists`, and `gte` and `lte` together or as days only when searched as a range (days only on date fields). `file_extension`, `consent_status`, `consent_rights` and `ai_status` take `in`; `file_created_at` takes `gte` and `lte`; `file_name` takes `like`, `eq` and `ne`. A value must fit its field: a whole number for integer fields, a number for decimal fields, true/false for yes/no fields and a date for date fields and `file_created_at`. A criterion that cannot be read is refused with a 422 naming it, never dropped.

## Response `201`

created

- Folder
  - `type` 'folder', required
  - `id` string, required
  - `attributes` FolderAttributes, required
    - `name` string
    - `description` string
    - `created_at` string, date-time
    - `updated_at` string, date-time
    - `sort` integer
    - `child_count` integer
    - `files_count` integer
    - `files_size` integer
    - `path` string
    - `show_large_folder_name` boolean
    - `hide_folder_name` boolean
    - `thumbs_scale_to_fit` boolean
    - `apply_folder_image_hue` boolean
    - `is_archived` boolean
    - `is_synced_mirror` boolean, nullable: Only present on mirror folders
    - `mirror_design` boolean: Only present on mirror folders
  - `relationships` FolderRelationships
    - `folder_thumbnail_file` object, nullable
      - `data` ResourceIdentifierObject
        - `type` string
        - `id` string
  - `links` FolderLinks
    - `self` string, uri
  - `meta` FolderMeta
    - `folder_type` 'folder' | 'album' | 'smart_folder' | 'mirror_folder' | 'archive_folder'
    - `is_locked` boolean

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `422`: Unprocessable Entity

---

[API](https://skmtc.dev/kontainer/apis/kontainer-api-documentation.md) - [All operations](https://skmtc.dev/kontainer/apis/kontainer-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/kontainer/apis/kontainer-api-documentation/revisions/b80a5167e09a?raw)