# Folders

## List folders

`GET /folders`

```json
{
  "tags": [
    "Folders"
  ],
  "summary": "List folders",
  "description": "Distinct, non-empty folder tags across persistent profiles.",
  "responses": {
    "200": {
      "description": "Folder names.",
      "content": {
        "application/json": {
          "schema": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "work",
              "scrapers"
            ]
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    }
  }
}
```

## Rename a folder

`PATCH /folders/{folder}`

```json
{
  "tags": [
    "Folders"
  ],
  "summary": "Rename a folder",
  "description": "Retags every profile in the folder. Returns the count.",
  "parameters": [
    {
      "name": "folder",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "name"
          ],
          "properties": {
            "name": {
              "type": "string",
              "description": "New folder name."
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Renamed.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "renamed_to": {
                "type": "string"
              },
              "profiles": {
                "type": "integer",
                "description": "Profiles retagged."
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    }
  }
}
```

## Delete a folder

`DELETE /folders/{folder}`

```json
{
  "tags": [
    "Folders"
  ],
  "summary": "Delete a folder",
  "description": "Deletes the folder tag. With `delete_profiles=true` the profiles in it are deleted too; otherwise they're unfiled (moved to \"All\").",
  "parameters": [
    {
      "name": "folder",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "delete_profiles",
      "in": "query",
      "required": false,
      "description": "Delete the profiles in the folder (default false = unfile).",
      "schema": {
        "type": "boolean",
        "default": false
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Deleted.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "deleted_folder": {
                "type": "string"
              },
              "delete_profiles": {
                "type": "boolean"
              },
              "profiles": {
                "type": "integer",
                "description": "Profiles affected."
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    }
  }
}
```

## Create a profile in a folder

`POST /folders/{folder}/profiles`

```json
{
  "tags": [
    "Folders"
  ],
  "summary": "Create a profile in a folder",
  "description": "Same as `POST /profiles`, but the folder comes from the path (overriding any `folder` in the body).",
  "parameters": [
    {
      "name": "folder",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateProfileRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Created profile metadata.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ProfileMeta"
          }
        }
      }
    },
    "400": {
      "description": "Missing/!object `fingerprint`, or an unparseable proxy string.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    }
  }
}
```