---
title: "Create a Team Space folder"
method: POST
path: "/v1/workspaces/{workspaceId}/folders"
tags: ["Folders"]
---

# Create a Team Space folder

`POST /v1/workspaces/{workspaceId}/folders`

## Request

- Base URL: `https://shareout.site`
- URL: `https://shareout.site/v1/workspaces/{workspaceId}/folders`
- Auth: HTTP bearer

Owners/admins always; members while the workspace setting `members_can_create_folders` is on (the default), otherwise 403 ADMIN_REQUIRED.

## Request body

- object
  - `name` string, required
  - `slug` string: Auto-generated from name if omitted.
  - `description` string
  - `parent_id` string
  - `readme` string: Markdown folder guide.
  - `visibility` 'inherit' | 'public' | 'workspace' | 'private': A label for the folder, not enforced on its contents: each artifact and file keeps its own visibility.

## Response `201`

Created

- Folder
  - `id` string
  - `name` string
  - `slug` string
  - `description` string, nullable
  - `artifact_count` integer
  - `parent_id` string, nullable: Team Space folders only.
  - `visibility` 'inherit' | 'public' | 'workspace' | 'private': Team Space folders only.
  - `subfolder_count` integer: Team Space folders only.
  - `path` string: Slug path; single-folder Team Space responses only.
  - `readme` string, nullable: Single-folder Team Space responses only.
  - `effective_visibility` string: Single-folder Team Space responses only.
  - `created_at` string, date-time

## Other responses

- `400`: Invalid request
- `403`: Access denied
- `404`: parent_id not found (PARENT_NOT_FOUND)
- `409`: Slug taken or version conflict

## Changes

- **2026-10-13** `ed6fa61bd690`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/shareout/apis/shareout-rest-api/changes/v1/workspaces/:workspaceId/folders/post.md)

---

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