# Profiles

## Список профілів

`GET /profiles`

```json
{
  "tags": [
    "Profiles"
  ],
  "summary": "Список профілів",
  "description": "Повертає постійні профілі (тимчасові приховані), від нових до старих,\nзакріплені; вгорі. Кожен запис доповнено актуальним станом запуску.\n",
  "responses": {
    "200": {
      "description": "Список профілів.",
      "content": {
        "application/json": {
          "schema": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProfileListItem"
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    }
  }
}
```

## Створити профіль

`POST /profiles`

```json
{
  "tags": [
    "Profiles"
  ],
  "summary": "Створити профіль",
  "description": "Зберігає профіль із переданого клієнтом об'єкта `fingerprint` **точно\nяк є** (повторна рандомізація не виконується; унікалізація вже\nвідбулася в `/fingerprint/new`). Використовуйте `folder`, щоб розмістити\nпрофіль у папці; прив'яжіть проксі за `proxy_id` зі сховища або\nінлайн через `proxy` (рядок, **не** зберігається у сховищі проксі).\n",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateProfileRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Метадані створеного профілю.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ProfileMeta"
          }
        }
      }
    },
    "400": {
      "description": "Відсутній або не є об'єктом `fingerprint`, або нерозбірлива строка проксі.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    }
  }
}
```

## Створити тимчасовий профіль

`POST /profiles/temporary`

```json
{
  "tags": [
    "Profiles"
  ],
  "summary": "Створити тимчасовий профіль",
  "description": "Створює профіль із випадкового (або вказаного) відбитка бібліотеки,\nунікалізованого як в `/fingerprint/new` і збереженого дослівно,\nз прапорцем `temporary`: прихований зі списків і **автоматично видаляється\nпісля закриття браузера** (або при наступному запуску після краша).\nВикористовуйте разом із `POST /profiles/{id}/start`.\n",
  "requestBody": {
    "required": false,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/TempProfileRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Створений тимчасовий профіль.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "name": {
                "type": "string"
              },
              "fingerprint_id": {
                "type": "string",
                "description": "Запис бібліотеки, на основі якого згенеровано профіль."
              },
              "temporary": {
                "type": "boolean",
                "example": true
              },
              "proxy_inline": {
                "type": "boolean",
                "description": "Чи був прикріплений інлайн-проксі."
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Нерозбірливий рядок проксі або невідомий вектор шуму.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "404": {
      "description": "Підходящий відбиток не знайдено / порожня бібліотека.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```

## Отримати профіль

`GET /profiles/{id}`

```json
{
  "tags": [
    "Profiles"
  ],
  "summary": "Отримати профіль",
  "description": "Повертає повний збережений профіль: оболонку `_meta` плюс\nрозгорнутий FingerprintConfig. Якщо профіль запущений; додаються\n`running` та `cdp`.\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/ProfileId"
    }
  ],
  "responses": {
    "200": {
      "description": "Збережений профіль.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/StoredProfile"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "404": {
      "description": "Профіль не знайдено.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```

## Видалити профіль

`DELETE /profiles/{id}`

```json
{
  "tags": [
    "Profiles"
  ],
  "summary": "Видалити профіль",
  "description": "Переміщує профіль до кошика, де його можна відновити протягом 7 днів. Після цього запис видаляється. До архіву входять облікові дані, cookies, логіни, вебдані, налаштування, Local Storage та IndexedDB, але не кеш. Початкові конфігурація й каталог даних користувача видаляються після створення архіву.\n\nТимчасові профілі видаляються трекером процесів після закриття браузера і до кошика не потрапляють.",
  "parameters": [
    {
      "$ref": "#/components/parameters/ProfileId"
    }
  ],
  "responses": {
    "200": {
      "description": "Профіль переміщено в кошик.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "deleted": {
                "type": "boolean",
                "example": true
              },
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "trashed": {
                "type": "boolean",
                "example": true,
                "description": "Можна відновити з кошика протягом 7 днів."
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "500": {
      "description": "Помилка при видаленні.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```

## Редагувати профіль

`PATCH /profiles/{id}`

```json
{
  "tags": [
    "Profiles"
  ],
  "summary": "Редагувати профіль",
  "description": "Оновлює лише передані поля. Якщо передано `fingerprint`; він\nЗАМІНЮЄ збережений дослівно (без перерандомізації).\n`folder: \"\"` прибирає профіль з папки; `proxy_id: \"\"` від'єднує проксі;\nрядок `proxy` зберігається (дедуплікація) + проходить повний тест,\nпотім прив'язується. Повертає оновлений профіль.\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/ProfileId"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/EditProfileRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Оновлений збережений профіль.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/StoredProfile"
          }
        }
      }
    },
    "400": {
      "description": "Невірний fingerprint (не об'єкт) або нерозбірливий проксі.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "404": {
      "description": "Профіль не знайдено.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```

## Запустити профіль (з CDP)

`POST /profiles/{id}/start`

```json
{
  "tags": [
    "Profiles"
  ],
  "summary": "Запустити профіль (з CDP)",
  "description": "Запускає ShardX-браузер для профілю з увімкненим remote-debugging,\nпідставляє часовий пояс/локаль/гео з `auto`-полів через прив'язаний\nпроксі та повертає CDP-ендпоінт після того, як Chrome записав\nDevToolsActivePort. CDP вмикається **лише** при запуску через API\n(запуски з UI не відкривають налагоджувальний порт; антидетект не страждає).\n`cdp` дорівнює `null`, якщо ендпоінт не вдалося прочитати протягом\nтаймауту. Працює для звичайних та тимчасових профілів.\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/ProfileId"
    }
  ],
  "requestBody": {
    "required": false,
    "description": "Необов'язково. Порожнє тіло запускає у графічному режимі.",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "headless": {
              "type": "boolean",
              "default": false,
              "description": "Запустити в headless-режимі (--headless=new)."
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Запущено.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "profile_id": {
                "type": "string"
              },
              "pid": {
                "type": "integer",
                "format": "int64",
                "description": "PID процесу ОС."
              },
              "headless": {
                "type": "boolean"
              },
              "cdp": {
                "nullable": true,
                "allOf": [
                  {
                    "$ref": "#/components/schemas/CdpInfo"
                  }
                ]
              },
              "cdp_error": {
                "type": "string",
                "nullable": true,
                "description": "Чому `cdp` має значення null, коли воно є. В іншому випадку відсутні."
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "500": {
      "description": "Бінарний файл не налаштований / не вдалося запустити процес.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```

## Зупинити профіль

`POST /profiles/{id}/stop`

```json
{
  "tags": [
    "Profiles"
  ],
  "summary": "Зупинити профіль",
  "description": "Відправляє браузеру сигнал graceful shutdown (SIGTERM на Unix; 5 секунд\nочікування, потім SIGKILL). Тимчасові профілі видаляються в процесі закриття.\n`stopped` дорівнює `false`, якщо профіль не був запущений.\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/ProfileId"
    }
  ],
  "responses": {
    "200": {
      "description": "Команда зупинки відправлена.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "profile_id": {
                "type": "string"
              },
              "stopped": {
                "type": "boolean"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    }
  }
}
```

## Експортувати cookies

`GET /profiles/{id}/cookies`

```json
{
  "tags": [
    "Profiles"
  ],
  "summary": "Експортувати cookies",
  "description": "Читає сховище cookies Chromium профілю та повертає всі cookies\n**у розшифрованому вигляді**. Працює як для запущеного, так і для\nзупиненого профілю. Порожній масив, якщо профіль жодного разу не запускався.\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/ProfileId"
    }
  ],
  "responses": {
    "200": {
      "description": "Печиво.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "cookies": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Cookie"
                }
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "500": {
      "description": "Помилка читання або розшифрування БД cookies.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```

## Імпортувати cookies

`POST /profiles/{id}/cookies`

```json
{
  "tags": [
    "Profiles"
  ],
  "summary": "Імпортувати cookies",
  "description": "Записує cookies у сховище профілю (повторно шифруючи за схемою\nChromium v10). Профіль **повинен бути зупинений**; запущений браузер\nперезапише сховище при виході та затре імпорт.\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/ProfileId"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "cookies"
          ],
          "properties": {
            "cookies": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/Cookie"
              }
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Імпортовано.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "imported": {
                "type": "integer",
                "description": "Кількість записаних cookies."
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "409": {
      "description": "Профіль запущений; спочатку зупиніть його.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "500": {
      "description": "Помилка запису БД cookies.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```

## Список запущених профілів

`GET /running`

```json
{
  "tags": [
    "Profiles"
  ],
  "summary": "Список запущених профілів",
  "description": "Профілі з живим процесом браузера, включаючи CDP-ендпоінт при запуску через API.",
  "responses": {
    "200": {
      "description": "Запущені профілі.",
      "content": {
        "application/json": {
          "schema": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RunningProfile"
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    }
  }
}
```