---
title: "Create a folder"
method: POST
path: "/v1/sites/{site_id}/folders"
tags: ["Folders"]
---

# Create a folder

`POST /v1/sites/{site_id}/folders`

## Request

- Base URL: `https://api.getsitecontrol.com`
- URL: `https://api.getsitecontrol.com/v1/sites/{site_id}/folders`
- Auth: HTTP bearer

A new folder for items of `type`, at the end of the admin's list. Names need
not be unique. Move widgets into it with `update_widgets` (`folder_id`);
other items are moved in the admin.

## Path parameters

- `site_id` integer, required

## Query parameters

- `type` 'widget' | 'segment' | 'broadcast' | 'automation', required: The items a folder holds. widget: widgets. segment: contact segments. broadcast: e-mail broadcasts. automation: automations.

## Headers

- `Idempotency-Key` string: Makes a retry of a POST safe: a repeat with the same key, body and GSC-Version returns the stored response with `Idempotency-Replayed: true` instead of running again. The key protects against repeated execution while the key store works. Saving the change and storing the response under the key are not atomic: if the process or the key store fails between them, the change is kept, the key is released after 15 minutes and a retry runs the request again. After a timeout or a 5xx, read the resource to check the result before retrying. 5xx and 429 responses and responses over 256 KB are not stored, so a repeat runs the request again. A key is kept for 24 hours. The same key with another body or version is 422; a repeat while the first request runs is 409.

## Request body

- FolderCreate
  - `name` string, required: Surrounding spaces are trimmed; names need not be unique

## Response `201`

Successful Response

- Folder
  - `id` integer, required: 0 is General, where items outside any folder are
  - `name` string, required

## Other responses

- `400`: Unsupported GSC-Version
- `401`: Missing or invalid API key or access token
- `403`: Access denied
- `404`: Not found
- `409`: Conflict
- `413`: Request body too large
- `422`: Validation failed
- `429`: Rate limited
- `503`: Temporarily unavailable; retry later

---

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