---
title: "Query Folders"
method: POST
path: "/folders/query"
tags: ["Folders"]
---

# Query Folders

`POST /folders/query`

Filter folders inside the caller's project.

Follows the general response envelope described in the
[Query Pattern](/reference/api-guide/query-pattern) guide, but
does not accept `windowing` or `include_archived` — folders are
hard-deleted and the response always returns the full filtered
set. Filters include `id`/`ids`, `slug`/`slugs`, `kind`/`kinds`,
`parent_id`/`parent_ids` (use `parent_id: null` for root folders),
`path`/`paths`, and `prefix`/`prefixes` for subtree lookup.

## Request body

- FolderQueryRequest
  - `folder` FolderQuery, required
    - `flags` object, nullable
    - `tags` object, nullable
    - `meta` object, nullable
    - `name` string, nullable
    - `description` string, nullable
    - `id` string, uuid, nullable — Match a single folder id.
    - `ids` string[], nullable — Match any of the given folder ids.
    - `slug` string, nullable — Match a folder by slug, regardless of its position in the tree.
    - `slugs` string[], nullable — Match folders whose slug is in the given list.
    - `kind` 'applications'
    - `kinds` union — Filter by presence of a kind. `false` returns folders with no kind, `true` returns folders where `kind` is set, and an array restricts to the given kinds.
      - boolean
      - FolderKind[]
    - `parent_id` string, uuid, nullable — Match folders whose parent is this id. Send `null` to return only root folders.
    - `parent_ids` string[], nullable — Match folders whose parent is any of the given ids.
    - `path` string, nullable — Exact match on the materialized `path` (e.g. `support.prod`).
    - `paths` string[], nullable — Exact match on any of the given paths.
    - `prefix` string, nullable — Subtree lookup: returns the folder at this path and every descendant.
    - `prefixes` string[], nullable — Subtree lookup across multiple prefixes, OR-ed together.

## Response `200`

Successful Response

- FoldersResponse
  - `count` integer — Number of folders in `folders`.
  - `folders` Folder[] — Matching folders for the query. Ordering is not guaranteed.
    - `flags` object, nullable
    - `tags` object, nullable
    - `meta` object, nullable
    - `name` string, nullable
    - `description` string, nullable
    - `created_at` string, date-time, nullable
    - `updated_at` string, date-time, nullable
    - `deleted_at` string, date-time, nullable
    - `created_by_id` string, uuid, nullable
    - `updated_by_id` string, uuid, nullable
    - `deleted_by_id` string, uuid, nullable
    - `slug` string, nullable
    - `id` string, uuid, nullable
    - `kind` 'applications'
    - `path` string, nullable — Dot-separated materialized path built from the folder's slug and its ancestors' slugs. Read-only; derived by the server.
    - `parent_id` string, uuid, nullable — Id of the parent folder, or `null` for a root folder.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/agenta-ai/apis/agenta-api.md) · [All operations](https://skmtc.net/agenta-ai/apis/agenta-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/agenta-ai/agenta-api/versions/ea6421d829f1/schema)