---
title: "Create a Folder in the specified Engagement"
method: POST
path: "/v1/engagements/{uuid}/folders"
tags: ["engagements", "files"]
---

# Create a Folder in the specified Engagement

`POST /v1/engagements/{uuid}/folders`

## Request

- Base URL: `https://api.fieldguide.io`
- URL: `https://api.fieldguide.io/v1/engagements/{uuid}/folders`
- Auth: HTTP bearer

## Path parameters

- `uuid` string, uuid, required

## Request body

- EngagementFolderCreate
  - `name` string, required: The Folder name. Slashes are not allowed.
  - `parent_folder_uuid` string, uuid, nullable: Parent Folder UUID. Omit or set to null for a root Folder.

## Response `201`

The newly created Engagement Folder

- object
  - `data` EngagementFolderRead, required
    - `uuid` string, uuid, required: The unique identifier for the resource
    - `parent_folder_uuid` string, uuid, nullable, required: The folder that contains this one
    - `engagement_uuid` string, uuid, required: The Engagement this Folder belongs to
    - `name` string, required: The name of the Folder
    - `path` string, required: The path to the Folder from the Engagement root
    - `created_at` string, date-time, required: Timestamp of when the Folder was created
    - `_links` EngagementFolderReadLinks, required
      - `fieldguide` HalLink, required
        - `href` string, uri, required
        - `title` string: A human-readable title for the link
        - `type` string, required: The content-type

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden Forbidden (requires scopes `engagements.files:write`)
- `404`: Resource not found
- `422`: Unprocessable Entity
- `429`: Too many requests

## Changes

- **2026-10-06** `df6a95217619`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/fieldguide/apis/fieldguide-api/changes/v1/engagements/:uuid/folders/post.md)

---

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