{
  "openapi": "3.1.0",
  "info": {
    "title": "Трекер: внешний API досок, списков и карточек",
    "version": "0.2.0-increment.2",
    "description": "API для ботов, CRM и других приложений: чтение, создание, редактирование, перенос и удаление досок, списков и карточек владельца. Исходящие хуки пока не реализованы.\n\n### Начать работу\n1. Выпустите ключ в настройках учётки на https://trckr.ru/. Для полного CRUD выберите права read/write; read разрешает только чтение, read/create — чтение и создание. Ключ одной доски ограничен этой доской, all даёт доступ ко всем доскам владельца.\n2. Нажмите Authorize и вставьте сам секрет trk_... без слова Bearer. Для начала вызовите GET /v1/boards с limit=1 и offset=0. Ответ покажет generation, rev и доступные ID. Пустая коллекция тоже содержит generation.\n3. Перед каждой новой изменяющей командой подготовьте свежий UUIDv7 в Idempotency-Key и передайте generation в X-Workspace-Generation. UUIDv4 не подходит. Для PATCH и DELETE сначала прочитайте объект и скопируйте ETag в If-Match вместе с двойными кавычками.\n4. В Try it out значения ID, generation и ETag переносятся между запросами вручную. Примеры названий можно отправлять как JSON; условные ID соседей замените реальными. Для DELETE тело не передавайте.\n\n### Версии и повторы\ngeneration обозначает поколение данных после восстановления сервера. rev — общая ревизия учётки: правка другой доски тоже может сделать If-Match устаревшим. При 412 перечитайте объект, оцените свою правку и создайте отдельную попытку с новым Idempotency-Key. При 409 generation_changed остановите автоматическую запись и заново согласуйте данные с владельцем.\n\nТаймаут и 503 не подтверждают отказ. Сохраните прежние метод, путь, тело, generation, If-Match и Idempotency-Key; проверьте GET /v1/requests/{requestId} или повторите ту же команду. Не создавайте новый ID при неизвестном исходе. Повтор возвращает исторический результат с replayed=true и не меняет данные ещё раз. Исторические rev и ETag нельзя принимать за текущую версию. 404 при поиске результата означает отсутствие сохранённого итога, а не доказанный откат.\n\n### Ограничения\nОбщий бюджет — 60 HTTP-запросов в минуту на учётку, всплеск до 10; новые записи — 10 в минуту, всплеск до 3, дополнительно действует общий с PWA процессный бюджет 30 записей в минуту. 429 и 503 содержат Retry-After. JSON записи ограничен 32 КиБ; снимок — 16 МиБ. История команд хранится 7 суток с пределами 1000 окончательных результатов за 24 часа, 8000 строк и 16 МиБ. Новый UUIDv7 исполняется не позднее 24 часов от его времени и не более чем на 5 минут из будущего; известный результат проверяется раньше свежести ID.\n\nПолный секрет виден только при выпуске или замене в PWA. Внешние методы используют Bearer-ключ; логин, пароль и cookie для них не нужны."
  },
  "servers": [
    {
      "url": "/",
      "description": "API текущего окружения"
    }
  ],
  "paths": {
    "/v1/boards": {
      "get": {
        "operationId": "listBoards",
        "summary": "Читать страницу заголовков разрешённых досок",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "description": "Размер страницы, от 1 до 100. По умолчанию 20."
          },
          {
            "in": "query",
            "name": "offset",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 2147483647,
              "default": 0
            },
            "description": "Число пропускаемых объектов, начиная с 0. Для продолжения используйте Link rel=\"next\"."
          },
          {
            "in": "query",
            "name": "generation",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Поколение из первой страницы. Передаётся вместе с rev; при offset>0 оба поля обязательны."
          },
          {
            "in": "query",
            "name": "rev",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 2147483647
            },
            "description": "Общая ревизия из первой страницы. При её изменении собранные страницы надо перечитать."
          }
        ],
        "responses": {
          "200": {
            "description": "Успех, полный контракт в api-access.md",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Workspace-Generation": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "Поколение ответа."
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "ID отдельного HTTP-вызова для диагностики; не Idempotency-Key."
              },
              "Link": {
                "schema": {
                  "type": "string",
                  "pattern": "^<[^>]+>; rel=\"next\"$"
                },
                "description": "Относительный URL следующей страницы с limit/offset/generation/rev, rel=\"next\". Присутствует только при hasMore=true; на последней странице отсутствует."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BoardsResult"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ExternalError401"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "409": {
            "$ref": "#/components/responses/ExternalError409",
            "description": "generation_changed: передано другое поколение; rev_conflict: данные изменились между страницами. Получить первую страницу заново, не смешивать наборы."
          },
          "413": {
            "$ref": "#/components/responses/Error413"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "description": "Порядок совпадает с порядком в приложении. limit: 1–100, по умолчанию 20; offset начинается с 0. При offset>0 обязательна пара generation и rev из первой страницы; на первой странице она необязательна, но передаётся вместе. hasMore и Link rel=\"next\" указывают продолжение. При 409 rev_conflict отбросьте собранные страницы и начните чтение заново; не смешивайте разные ревизии. Возвращает заголовки разрешённых досок без списков и карточек. При удалении доски, выбранной board-ключом, коллекция пуста.",
        "tags": [
          "Доски"
        ]
      },
      "post": {
        "operationId": "createBoard",
        "summary": "Создать доску в конце порядка",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "parameters": [
          {
            "in": "header",
            "name": "X-Workspace-Generation",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "generation из текущего чтения. При generation_changed остановите запись и заново согласуйте восстановленные данные."
          },
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/RequestId"
            },
            "description": "Свежий UUIDv7 для нового намерения. Сохраните его до отправки; после таймаута повторяйте прежний ID с тем же запросом. UUIDv4 не подходит."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateBoard"
              },
              "example": {
                "title": "План команды"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Результат по контракту api-create.md",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Workspace-Generation": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "Поколение ответа."
              },
              "Location": {
                "required": true,
                "schema": {
                  "type": "string",
                  "pattern": "^/v1/boards/"
                },
                "description": "Канонический путь существующего GET созданного объекта; не ссылка на результат команды."
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "ID отдельного HTTP-вызова для диагностики; не Idempotency-Key."
              },
              "ETag": {
                "required": true,
                "schema": {
                  "type": "string",
                  "pattern": "^\"[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}:[1-9][0-9]{0,9}\"$"
                },
                "description": "Сильный тег канонического объекта: generation:rev в двойных кавычках. Общая rev консервативно обнаруживает изменения любой доски владельца. При повторе относится к историческому результату."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BoardCreateResult"
                },
                "example": {
                  "requestId": "019d0000-0000-7000-8000-000000000001",
                  "data": {
                    "id": "MHX5BM7EPV",
                    "title": "План команды",
                    "color": "gray"
                  },
                  "generation": "83f8b814-4d88-4ce1-b68b-f21cdff1fc5e",
                  "rev": 2,
                  "replayed": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/ExternalError401"
          },
          "403": {
            "$ref": "#/components/responses/ExternalError403"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "409": {
            "$ref": "#/components/responses/ExternalError409",
            "description": "generation_changed: поколение изменилось; request_reused: ID связан с другим входом; request_expired: неизвестная команда вне срока; key_limit: заполнена история. Подтверждённый сохранённый отказ повторяется, неизвестный исход требует проверки прежней команды."
          },
          "413": {
            "$ref": "#/components/responses/Error413",
            "description": "limit: размер запроса/снимка либо reason=quota_exceeded. Предметный отказ может быть сохранён в истории команды; ошибка разбора тела до исполнения не сохраняется."
          },
          "415": {
            "$ref": "#/components/responses/Error415"
          },
          "422": {
            "$ref": "#/components/responses/ExternalError422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "description": "Создаёт доску в конце порядка владельца. Нужен ключ scope=all с create или write; color по умолчанию gray. Передайте свежий UUIDv7 в Idempotency-Key и generation из чтения в X-Workspace-Generation. Ответ 201 содержит полный публичный объект, Location его GET и ETag. Объект, rev и результат фиксируются одной транзакцией. If-Match и If-None-Match при создании запрещены и дают 422. При потере ответа или 503 сохраните ID и весь исходный запрос. Проверьте GET /v1/requests/{requestId} либо повторите тот же запрос. replayed=true обозначает исторический результат без второго изменения. ",
        "tags": [
          "Доски"
        ]
      }
    },
    "/v1/boards/{boardId}": {
      "get": {
        "operationId": "readBoard",
        "summary": "Читать заголовок разрешённой активной доски",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "boardId",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,128}$"
            },
            "description": "Короткий ID разрешённой доски из GET /v1/boards или ответа создания."
          },
          {
            "in": "header",
            "name": "If-None-Match",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Условное чтение по HTTP ETag. При совпадении текущего тега возвращается 304 без JSON. Авторизация и лимиты проверяются до условного ответа. Cache-Control остаётся no-store."
          }
        ],
        "responses": {
          "200": {
            "description": "Успех, полный контракт в api-access.md",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Workspace-Generation": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "Поколение ответа."
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "ID отдельного HTTP-вызова для диагностики; не Idempotency-Key."
              },
              "ETag": {
                "required": true,
                "schema": {
                  "type": "string",
                  "pattern": "^\"[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}:[1-9][0-9]{0,9}\"$"
                },
                "description": "Сильный тег канонического объекта: generation:rev в двойных кавычках. Общая rev консервативно обнаруживает изменения любой доски владельца. При повторе относится к историческому результату."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BoardResult"
                }
              }
            }
          },
          "304": {
            "description": "Текущее представление не изменилось по If-None-Match. Тело отсутствует. Проверки доступа и квот выполнены; no-store сохраняется.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "ETag": {
                "required": true,
                "schema": {
                  "type": "string",
                  "pattern": "^\"[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}:[1-9][0-9]{0,9}\"$"
                },
                "description": "Сильный тег канонического объекта: generation:rev в двойных кавычках. Общая rev консервативно обнаруживает изменения любой доски владельца. При повторе относится к историческому результату."
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ExternalError401"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "413": {
            "$ref": "#/components/responses/Error413"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "tags": [
          "Доски"
        ],
        "description": "Ответ содержит публичный объект, generation, rev и ETag. Для изменения или удаления скопируйте ETag в If-Match вместе с двойными кавычками. Ревизия общая для учётки. Необязательный If-None-Match позволяет получить 304 без JSON; авторизация и лимиты проверяются и в этом случае. Чужой, отсутствующий или удалённый объект даёт одинаковый 404. Ключ board видит только выбранную доску. Чтение не меняет generation или rev."
      },
      "patch": {
        "operationId": "updateBoard",
        "summary": "Изменить доску или её порядок",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "boardId",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,128}$"
            },
            "description": "Короткий ID разрешённой доски из GET /v1/boards или ответа создания."
          },
          {
            "in": "header",
            "name": "X-Workspace-Generation",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "generation из текущего чтения. При generation_changed остановите запись и заново согласуйте восстановленные данные."
          },
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/RequestId"
            },
            "description": "Свежий UUIDv7 для нового намерения. Сохраните его до отправки; после таймаута повторяйте прежний ID с тем же запросом. UUIDv4 не подходит."
          },
          {
            "in": "header",
            "name": "If-Match",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/MatchCondition"
            },
            "description": "Сильный ETag из чтения объекта, например \"83f8b814-4d88-4ce1-b68b-f21cdff1fc5e:2\". Принимается общий HTTP-список непрозрачных сильных/слабых тегов, включая запятые внутри кавычек. Совпадение сильное и чувствительно к регистру. Неизвестный корректный тег даёт 412. * отклоняется 422. Условие входит в отпечаток команды."
          }
        ],
        "responses": {
          "200": {
            "description": "Атомарный результат команды и исторические данные.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Workspace-Generation": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "Поколение ответа."
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "ID отдельного HTTP-вызова для диагностики; не Idempotency-Key."
              },
              "ETag": {
                "required": true,
                "schema": {
                  "type": "string",
                  "pattern": "^\"[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}:[1-9][0-9]{0,9}\"$"
                },
                "description": "Сильный тег канонического объекта: generation:rev в двойных кавычках. Общая rev консервативно обнаруживает изменения любой доски владельца. При повторе относится к историческому результату."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BoardMutationResult"
                },
                "example": {
                  "requestId": "019d0000-0000-7000-8000-000000000001",
                  "data": {
                    "id": "BOARD23456",
                    "title": "Обновлённый план",
                    "color": "green"
                  },
                  "generation": "83f8b814-4d88-4ce1-b68b-f21cdff1fc5e",
                  "rev": 3,
                  "replayed": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/ExternalError401"
          },
          "403": {
            "$ref": "#/components/responses/ExternalError403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "409": {
            "$ref": "#/components/responses/ExternalError409"
          },
          "412": {
            "$ref": "#/components/responses/Error412"
          },
          "413": {
            "$ref": "#/components/responses/Error413"
          },
          "415": {
            "$ref": "#/components/responses/Error415"
          },
          "422": {
            "$ref": "#/components/responses/ExternalError422"
          },
          "428": {
            "$ref": "#/components/responses/Error428"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "description": "Нужен отдельный ключ с правами read/write. Передайте X-Workspace-Generation, новый UUIDv7 в Idempotency-Key и If-Match с ETag прочитанного объекта. При 412 rev_conflict перечитайте объект и подготовьте новую попытку; не подставляйте свежий If-Match под ID уже отклонённой команды. If-None-Match при записи запрещён и даёт 422. Пропущенное поле сохраняет значение. Несколько переданных полей меняются атомарно; пустой объект и неизвестные поля дают 422. beforeId=null переносит в конец, ID соседа ставит объект перед ним. Ответ 200 содержит полный публичный объект и ETag. Доступны title, color и beforeId. Для перестановки досок нужен scope=all; ключ одной доски может менять title/color. При потере ответа или 503 сохраните ID и весь исходный запрос. Проверьте GET /v1/requests/{requestId} либо повторите тот же запрос. replayed=true обозначает исторический результат без второго изменения. ",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PatchBoard"
              },
              "examples": {
                "rename": {
                  "summary": "Переименовать доску",
                  "value": {
                    "title": "План на неделю"
                  }
                },
                "color": {
                  "summary": "Изменить цвет",
                  "value": {
                    "color": "green"
                  }
                },
                "end": {
                  "summary": "Перенести доску в конец",
                  "value": {
                    "beforeId": null
                  }
                },
                "before": {
                  "summary": "Поставить перед другой доской — замените ID",
                  "value": {
                    "beforeId": "BOARD34567"
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Доски"
        ]
      },
      "delete": {
        "operationId": "deleteBoard",
        "summary": "Удалить доску",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "boardId",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,128}$"
            },
            "description": "Короткий ID разрешённой доски из GET /v1/boards или ответа создания."
          },
          {
            "in": "header",
            "name": "X-Workspace-Generation",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "generation из текущего чтения. При generation_changed остановите запись и заново согласуйте восстановленные данные."
          },
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/RequestId"
            },
            "description": "Свежий UUIDv7 для нового намерения. Сохраните его до отправки; после таймаута повторяйте прежний ID с тем же запросом. UUIDv4 не подходит."
          },
          {
            "in": "header",
            "name": "If-Match",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/MatchCondition"
            },
            "description": "Сильный ETag из чтения объекта, например \"83f8b814-4d88-4ce1-b68b-f21cdff1fc5e:2\". Принимается общий HTTP-список непрозрачных сильных/слабых тегов, включая запятые внутри кавычек. Совпадение сильное и чувствительно к регистру. Неизвестный корректный тег даёт 412. * отклоняется 422. Условие входит в отпечаток команды."
          }
        ],
        "responses": {
          "200": {
            "description": "Атомарный результат команды и исторические данные.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Workspace-Generation": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "Поколение ответа."
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "ID отдельного HTTP-вызова для диагностики; не Idempotency-Key."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BoardDeleteResult"
                },
                "example": {
                  "requestId": "019d0000-0000-7000-8000-000000000001",
                  "data": {
                    "id": "BOARD23456",
                    "deleted": true
                  },
                  "generation": "83f8b814-4d88-4ce1-b68b-f21cdff1fc5e",
                  "rev": 3,
                  "replayed": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/ExternalError401"
          },
          "403": {
            "$ref": "#/components/responses/ExternalError403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "409": {
            "$ref": "#/components/responses/ExternalError409"
          },
          "412": {
            "$ref": "#/components/responses/Error412"
          },
          "413": {
            "$ref": "#/components/responses/Error413"
          },
          "422": {
            "$ref": "#/components/responses/ExternalError422"
          },
          "428": {
            "$ref": "#/components/responses/Error428"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "description": "Нужен отдельный ключ с правами read/write. Передайте X-Workspace-Generation, новый UUIDv7 в Idempotency-Key и If-Match с ETag прочитанного объекта. При 412 rev_conflict перечитайте объект и подготовьте новую попытку; не подставляйте свежий If-Match под ID уже отклонённой команды. If-None-Match при записи запрещён и даёт 422. Тело не передавайте. Ответ 200 содержит ID, применимых родителей и deleted=true; ETag удалённого объекта не возвращается. Удаление логическое: физическая очистка и восстановление через этот API не предоставляются. Повтор той же команды возвращает подтверждение даже после удаления; новый DELETE отсутствующего объекта даёт 404. Удаление доски скрывает её списки и карточки и атомарно отзывает публичную ссылку. При потере ответа или 503 сохраните ID и весь исходный запрос. Проверьте GET /v1/requests/{requestId} либо повторите тот же запрос. replayed=true обозначает исторический результат без второго изменения. ",
        "tags": [
          "Доски"
        ]
      }
    },
    "/v1/snapshot": {
      "get": {
        "operationId": "readSnapshot",
        "summary": "Читать согласованное дерево разрешённых досок",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Успех, полный контракт в api-access.md",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Workspace-Generation": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "Поколение ответа."
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "ID отдельного HTTP-вызова для диагностики; не Idempotency-Key."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Snapshot"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ExternalError401"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "413": {
            "$ref": "#/components/responses/Error413"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "description": "Одним согласованным чтением возвращает дерево разрешённых активных досок, списков и карточек вместе с generation и rev. Размер JSON до 16 МиБ. Удалённая выбранная доска даёт пустое дерево. Учётка, API-ключи и коды публичных ссылок в снимок не входят. Чтение не меняет данные.",
        "tags": [
          "Снимок данных"
        ]
      }
    },
    "/v1/boards/{boardId}/lists": {
      "get": {
        "operationId": "listLists",
        "summary": "Читать страницу списков",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "boardId",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,128}$"
            },
            "description": "Короткий ID разрешённой доски из GET /v1/boards или ответа создания."
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "description": "Размер страницы, от 1 до 100. По умолчанию 20."
          },
          {
            "in": "query",
            "name": "offset",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 2147483647,
              "default": 0
            },
            "description": "Число пропускаемых объектов, начиная с 0. Для продолжения используйте Link rel=\"next\"."
          },
          {
            "in": "query",
            "name": "generation",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Поколение из первой страницы. Передаётся вместе с rev; при offset>0 оба поля обязательны."
          },
          {
            "in": "query",
            "name": "rev",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 2147483647
            },
            "description": "Общая ревизия из первой страницы. При её изменении собранные страницы надо перечитать."
          }
        ],
        "responses": {
          "200": {
            "description": "Результат по контракту api-create.md",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Workspace-Generation": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "Поколение ответа."
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "ID отдельного HTTP-вызова для диагностики; не Idempotency-Key."
              },
              "Link": {
                "schema": {
                  "type": "string",
                  "pattern": "^<[^>]+>; rel=\"next\"$"
                },
                "description": "Относительный URL следующей страницы с limit/offset/generation/rev, rel=\"next\". Присутствует только при hasMore=true; на последней странице отсутствует."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListsResult"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ExternalError401"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "409": {
            "$ref": "#/components/responses/ExternalError409",
            "description": "generation_changed: передано другое поколение; rev_conflict: данные изменились между страницами. Получить первую страницу заново, не смешивать наборы."
          },
          "413": {
            "$ref": "#/components/responses/Error413"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "description": "Порядок совпадает с порядком в приложении. limit: 1–100, по умолчанию 20; offset начинается с 0. При offset>0 обязательна пара generation и rev из первой страницы; на первой странице она необязательна, но передаётся вместе. hasMore и Link rel=\"next\" указывают продолжение. При 409 rev_conflict отбросьте собранные страницы и начните чтение заново; не смешивайте разные ревизии. Возвращает заголовки списков без карточек. Чужой, отсутствующий или удалённый объект даёт одинаковый 404. Ключ board видит только выбранную доску. Чтение не меняет generation или rev.",
        "tags": [
          "Списки"
        ]
      },
      "post": {
        "operationId": "createList",
        "summary": "Создать список в конце доски",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "boardId",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,128}$"
            },
            "description": "Короткий ID разрешённой доски из GET /v1/boards или ответа создания."
          },
          {
            "in": "header",
            "name": "X-Workspace-Generation",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "generation из текущего чтения. При generation_changed остановите запись и заново согласуйте восстановленные данные."
          },
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/RequestId"
            },
            "description": "Свежий UUIDv7 для нового намерения. Сохраните его до отправки; после таймаута повторяйте прежний ID с тем же запросом. UUIDv4 не подходит."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateList"
              },
              "example": {
                "title": "В работе"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Результат по контракту api-create.md",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Workspace-Generation": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "Поколение ответа."
              },
              "Location": {
                "required": true,
                "schema": {
                  "type": "string",
                  "pattern": "^/v1/boards/"
                },
                "description": "Канонический путь существующего GET созданного объекта; не ссылка на результат команды."
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "ID отдельного HTTP-вызова для диагностики; не Idempotency-Key."
              },
              "ETag": {
                "required": true,
                "schema": {
                  "type": "string",
                  "pattern": "^\"[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}:[1-9][0-9]{0,9}\"$"
                },
                "description": "Сильный тег канонического объекта: generation:rev в двойных кавычках. Общая rev консервативно обнаруживает изменения любой доски владельца. При повторе относится к историческому результату."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListCreateResult"
                },
                "example": {
                  "requestId": "019d0000-0000-7000-8000-000000000001",
                  "data": {
                    "id": "MHX5BM7EPV",
                    "title": "В работе",
                    "boardId": "BOARD23456"
                  },
                  "generation": "83f8b814-4d88-4ce1-b68b-f21cdff1fc5e",
                  "rev": 2,
                  "replayed": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/ExternalError401"
          },
          "403": {
            "$ref": "#/components/responses/ExternalError403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "409": {
            "$ref": "#/components/responses/ExternalError409",
            "description": "generation_changed: поколение изменилось; request_reused: ID связан с другим входом; request_expired: неизвестная команда вне срока; key_limit: заполнена история. Подтверждённый сохранённый отказ повторяется, неизвестный исход требует проверки прежней команды."
          },
          "413": {
            "$ref": "#/components/responses/Error413",
            "description": "limit: размер запроса/снимка либо reason=quota_exceeded. Предметный отказ может быть сохранён в истории команды; ошибка разбора тела до исполнения не сохраняется."
          },
          "415": {
            "$ref": "#/components/responses/Error415"
          },
          "422": {
            "$ref": "#/components/responses/ExternalError422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "description": "Создаёт список в конце указанной доски. Нужен ключ с create или write и доступом к доске. Передайте свежий UUIDv7 в Idempotency-Key и generation из чтения в X-Workspace-Generation. Ответ 201 содержит полный публичный объект, Location его GET и ETag. Объект, rev и результат фиксируются одной транзакцией. If-Match и If-None-Match при создании запрещены и дают 422. При потере ответа или 503 сохраните ID и весь исходный запрос. Проверьте GET /v1/requests/{requestId} либо повторите тот же запрос. replayed=true обозначает исторический результат без второго изменения. ",
        "tags": [
          "Списки"
        ]
      }
    },
    "/v1/boards/{boardId}/lists/{listId}": {
      "get": {
        "operationId": "getList",
        "summary": "Читать один список",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "boardId",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,128}$"
            },
            "description": "Короткий ID разрешённой доски из GET /v1/boards или ответа создания."
          },
          {
            "in": "path",
            "name": "listId",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,128}$"
            },
            "description": "Короткий ID списка в указанной доске. Для карточек задаёт список при создании или чтении коллекции."
          },
          {
            "in": "header",
            "name": "If-None-Match",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Условное чтение по HTTP ETag. При совпадении текущего тега возвращается 304 без JSON. Авторизация и лимиты проверяются до условного ответа. Cache-Control остаётся no-store."
          }
        ],
        "responses": {
          "200": {
            "description": "Результат по контракту api-create.md",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Workspace-Generation": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "Поколение ответа."
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "ID отдельного HTTP-вызова для диагностики; не Idempotency-Key."
              },
              "ETag": {
                "required": true,
                "schema": {
                  "type": "string",
                  "pattern": "^\"[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}:[1-9][0-9]{0,9}\"$"
                },
                "description": "Сильный тег канонического объекта: generation:rev в двойных кавычках. Общая rev консервативно обнаруживает изменения любой доски владельца. При повторе относится к историческому результату."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListResult"
                }
              }
            }
          },
          "304": {
            "description": "Текущее представление не изменилось по If-None-Match. Тело отсутствует. Проверки доступа и квот выполнены; no-store сохраняется.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "ETag": {
                "required": true,
                "schema": {
                  "type": "string",
                  "pattern": "^\"[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}:[1-9][0-9]{0,9}\"$"
                },
                "description": "Сильный тег канонического объекта: generation:rev в двойных кавычках. Общая rev консервативно обнаруживает изменения любой доски владельца. При повторе относится к историческому результату."
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ExternalError401"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "413": {
            "$ref": "#/components/responses/Error413"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "description": "Ответ содержит публичный объект, generation, rev и ETag. Для изменения или удаления скопируйте ETag в If-Match вместе с двойными кавычками. Ревизия общая для учётки. Необязательный If-None-Match позволяет получить 304 без JSON; авторизация и лимиты проверяются и в этом случае. Возвращает заголовок списка без карточек. Чужой, отсутствующий или удалённый объект даёт одинаковый 404. Ключ board видит только выбранную доску. Чтение не меняет generation или rev.",
        "tags": [
          "Списки"
        ]
      },
      "patch": {
        "operationId": "updateList",
        "summary": "Изменить список или его порядок",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "boardId",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,128}$"
            },
            "description": "Короткий ID разрешённой доски из GET /v1/boards или ответа создания."
          },
          {
            "in": "path",
            "name": "listId",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,128}$"
            },
            "description": "Короткий ID списка в указанной доске. Для карточек задаёт список при создании или чтении коллекции."
          },
          {
            "in": "header",
            "name": "X-Workspace-Generation",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "generation из текущего чтения. При generation_changed остановите запись и заново согласуйте восстановленные данные."
          },
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/RequestId"
            },
            "description": "Свежий UUIDv7 для нового намерения. Сохраните его до отправки; после таймаута повторяйте прежний ID с тем же запросом. UUIDv4 не подходит."
          },
          {
            "in": "header",
            "name": "If-Match",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/MatchCondition"
            },
            "description": "Сильный ETag из чтения объекта, например \"83f8b814-4d88-4ce1-b68b-f21cdff1fc5e:2\". Принимается общий HTTP-список непрозрачных сильных/слабых тегов, включая запятые внутри кавычек. Совпадение сильное и чувствительно к регистру. Неизвестный корректный тег даёт 412. * отклоняется 422. Условие входит в отпечаток команды."
          }
        ],
        "responses": {
          "200": {
            "description": "Атомарный результат команды и исторические данные.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Workspace-Generation": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "Поколение ответа."
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "ID отдельного HTTP-вызова для диагностики; не Idempotency-Key."
              },
              "ETag": {
                "required": true,
                "schema": {
                  "type": "string",
                  "pattern": "^\"[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}:[1-9][0-9]{0,9}\"$"
                },
                "description": "Сильный тег канонического объекта: generation:rev в двойных кавычках. Общая rev консервативно обнаруживает изменения любой доски владельца. При повторе относится к историческому результату."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListMutationResult"
                },
                "example": {
                  "requestId": "019d0000-0000-7000-8000-000000000001",
                  "data": {
                    "id": "LIST234567",
                    "boardId": "BOARD23456",
                    "title": "В работе"
                  },
                  "generation": "83f8b814-4d88-4ce1-b68b-f21cdff1fc5e",
                  "rev": 3,
                  "replayed": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/ExternalError401"
          },
          "403": {
            "$ref": "#/components/responses/ExternalError403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "409": {
            "$ref": "#/components/responses/ExternalError409"
          },
          "412": {
            "$ref": "#/components/responses/Error412"
          },
          "413": {
            "$ref": "#/components/responses/Error413"
          },
          "415": {
            "$ref": "#/components/responses/Error415"
          },
          "422": {
            "$ref": "#/components/responses/ExternalError422"
          },
          "428": {
            "$ref": "#/components/responses/Error428"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "description": "Нужен отдельный ключ с правами read/write. Передайте X-Workspace-Generation, новый UUIDv7 в Idempotency-Key и If-Match с ETag прочитанного объекта. При 412 rev_conflict перечитайте объект и подготовьте новую попытку; не подставляйте свежий If-Match под ID уже отклонённой команды. If-None-Match при записи запрещён и даёт 422. Пропущенное поле сохраняет значение. Несколько переданных полей меняются атомарно; пустой объект и неизвестные поля дают 422. beforeId=null переносит в конец, ID соседа ставит объект перед ним. Ответ 200 содержит полный публичный объект и ETag. Доступны title и beforeId; список переставляется только в своей доске. При потере ответа или 503 сохраните ID и весь исходный запрос. Проверьте GET /v1/requests/{requestId} либо повторите тот же запрос. replayed=true обозначает исторический результат без второго изменения. ",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PatchList"
              },
              "examples": {
                "rename": {
                  "summary": "Переименовать список",
                  "value": {
                    "title": "Проверка"
                  }
                },
                "end": {
                  "summary": "Перенести список в конец доски",
                  "value": {
                    "beforeId": null
                  }
                },
                "before": {
                  "summary": "Поставить перед другим списком — замените ID",
                  "value": {
                    "beforeId": "LIST345678"
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Списки"
        ]
      },
      "delete": {
        "operationId": "deleteList",
        "summary": "Удалить список",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "boardId",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,128}$"
            },
            "description": "Короткий ID разрешённой доски из GET /v1/boards или ответа создания."
          },
          {
            "in": "path",
            "name": "listId",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,128}$"
            },
            "description": "Короткий ID списка в указанной доске. Для карточек задаёт список при создании или чтении коллекции."
          },
          {
            "in": "header",
            "name": "X-Workspace-Generation",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "generation из текущего чтения. При generation_changed остановите запись и заново согласуйте восстановленные данные."
          },
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/RequestId"
            },
            "description": "Свежий UUIDv7 для нового намерения. Сохраните его до отправки; после таймаута повторяйте прежний ID с тем же запросом. UUIDv4 не подходит."
          },
          {
            "in": "header",
            "name": "If-Match",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/MatchCondition"
            },
            "description": "Сильный ETag из чтения объекта, например \"83f8b814-4d88-4ce1-b68b-f21cdff1fc5e:2\". Принимается общий HTTP-список непрозрачных сильных/слабых тегов, включая запятые внутри кавычек. Совпадение сильное и чувствительно к регистру. Неизвестный корректный тег даёт 412. * отклоняется 422. Условие входит в отпечаток команды."
          }
        ],
        "responses": {
          "200": {
            "description": "Атомарный результат команды и исторические данные.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Workspace-Generation": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "Поколение ответа."
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "ID отдельного HTTP-вызова для диагностики; не Idempotency-Key."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListDeleteResult"
                },
                "example": {
                  "requestId": "019d0000-0000-7000-8000-000000000001",
                  "data": {
                    "id": "LIST234567",
                    "boardId": "BOARD23456",
                    "deleted": true
                  },
                  "generation": "83f8b814-4d88-4ce1-b68b-f21cdff1fc5e",
                  "rev": 3,
                  "replayed": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/ExternalError401"
          },
          "403": {
            "$ref": "#/components/responses/ExternalError403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "409": {
            "$ref": "#/components/responses/ExternalError409"
          },
          "412": {
            "$ref": "#/components/responses/Error412"
          },
          "413": {
            "$ref": "#/components/responses/Error413"
          },
          "422": {
            "$ref": "#/components/responses/ExternalError422"
          },
          "428": {
            "$ref": "#/components/responses/Error428"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "description": "Нужен отдельный ключ с правами read/write. Передайте X-Workspace-Generation, новый UUIDv7 в Idempotency-Key и If-Match с ETag прочитанного объекта. При 412 rev_conflict перечитайте объект и подготовьте новую попытку; не подставляйте свежий If-Match под ID уже отклонённой команды. If-None-Match при записи запрещён и даёт 422. Тело не передавайте. Ответ 200 содержит ID, применимых родителей и deleted=true; ETag удалённого объекта не возвращается. Удаление логическое: физическая очистка и восстановление через этот API не предоставляются. Повтор той же команды возвращает подтверждение даже после удаления; новый DELETE отсутствующего объекта даёт 404. Удаление списка скрывает его карточки. Доска и её публичная ссылка сохраняются. При потере ответа или 503 сохраните ID и весь исходный запрос. Проверьте GET /v1/requests/{requestId} либо повторите тот же запрос. replayed=true обозначает исторический результат без второго изменения. ",
        "tags": [
          "Списки"
        ]
      }
    },
    "/v1/boards/{boardId}/lists/{listId}/cards": {
      "get": {
        "operationId": "listCards",
        "summary": "Читать страницу карточек",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "boardId",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,128}$"
            },
            "description": "Короткий ID разрешённой доски из GET /v1/boards или ответа создания."
          },
          {
            "in": "path",
            "name": "listId",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,128}$"
            },
            "description": "Короткий ID списка в указанной доске. Для карточек задаёт список при создании или чтении коллекции."
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "description": "Размер страницы, от 1 до 100. По умолчанию 20."
          },
          {
            "in": "query",
            "name": "offset",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 2147483647,
              "default": 0
            },
            "description": "Число пропускаемых объектов, начиная с 0. Для продолжения используйте Link rel=\"next\"."
          },
          {
            "in": "query",
            "name": "generation",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Поколение из первой страницы. Передаётся вместе с rev; при offset>0 оба поля обязательны."
          },
          {
            "in": "query",
            "name": "rev",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 2147483647
            },
            "description": "Общая ревизия из первой страницы. При её изменении собранные страницы надо перечитать."
          }
        ],
        "responses": {
          "200": {
            "description": "Результат по контракту api-create.md",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Workspace-Generation": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "Поколение ответа."
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "ID отдельного HTTP-вызова для диагностики; не Idempotency-Key."
              },
              "Link": {
                "schema": {
                  "type": "string",
                  "pattern": "^<[^>]+>; rel=\"next\"$"
                },
                "description": "Относительный URL следующей страницы с limit/offset/generation/rev, rel=\"next\". Присутствует только при hasMore=true; на последней странице отсутствует."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardsResult"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ExternalError401"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "409": {
            "$ref": "#/components/responses/ExternalError409",
            "description": "generation_changed: передано другое поколение; rev_conflict: данные изменились между страницами. Получить первую страницу заново, не смешивать наборы."
          },
          "413": {
            "$ref": "#/components/responses/Error413"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "description": "Порядок совпадает с порядком в приложении. limit: 1–100, по умолчанию 20; offset начинается с 0. При offset>0 обязательна пара generation и rev из первой страницы; на первой странице она необязательна, но передаётся вместе. hasMore и Link rel=\"next\" указывают продолжение. При 409 rev_conflict отбросьте собранные страницы и начните чтение заново; не смешивайте разные ревизии. Возвращает карточки указанного списка. Чужой, отсутствующий или удалённый объект даёт одинаковый 404. Ключ board видит только выбранную доску. Чтение не меняет generation или rev.",
        "tags": [
          "Карточки"
        ]
      },
      "post": {
        "operationId": "createCard",
        "summary": "Создать карточку в конце списка",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "boardId",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,128}$"
            },
            "description": "Короткий ID разрешённой доски из GET /v1/boards или ответа создания."
          },
          {
            "in": "path",
            "name": "listId",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,128}$"
            },
            "description": "Короткий ID списка в указанной доске. Для карточек задаёт список при создании или чтении коллекции."
          },
          {
            "in": "header",
            "name": "X-Workspace-Generation",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "generation из текущего чтения. При generation_changed остановите запись и заново согласуйте восстановленные данные."
          },
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/RequestId"
            },
            "description": "Свежий UUIDv7 для нового намерения. Сохраните его до отправки; после таймаута повторяйте прежний ID с тем же запросом. UUIDv4 не подходит."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateCard"
              },
              "example": {
                "title": "Позвонить клиенту"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Результат по контракту api-create.md",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Workspace-Generation": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "Поколение ответа."
              },
              "Location": {
                "required": true,
                "schema": {
                  "type": "string",
                  "pattern": "^/v1/boards/"
                },
                "description": "Канонический путь существующего GET созданного объекта; не ссылка на результат команды."
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "ID отдельного HTTP-вызова для диагностики; не Idempotency-Key."
              },
              "ETag": {
                "required": true,
                "schema": {
                  "type": "string",
                  "pattern": "^\"[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}:[1-9][0-9]{0,9}\"$"
                },
                "description": "Сильный тег канонического объекта: generation:rev в двойных кавычках. Общая rev консервативно обнаруживает изменения любой доски владельца. При повторе относится к историческому результату."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardCreateResult"
                },
                "example": {
                  "requestId": "019d0000-0000-7000-8000-000000000001",
                  "data": {
                    "id": "MHX5BM7EPV",
                    "title": "Позвонить клиенту",
                    "boardId": "BOARD23456",
                    "listId": "LIST234567"
                  },
                  "generation": "83f8b814-4d88-4ce1-b68b-f21cdff1fc5e",
                  "rev": 2,
                  "replayed": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/ExternalError401"
          },
          "403": {
            "$ref": "#/components/responses/ExternalError403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "409": {
            "$ref": "#/components/responses/ExternalError409",
            "description": "generation_changed: поколение изменилось; request_reused: ID связан с другим входом; request_expired: неизвестная команда вне срока; key_limit: заполнена история. Подтверждённый сохранённый отказ повторяется, неизвестный исход требует проверки прежней команды."
          },
          "413": {
            "$ref": "#/components/responses/Error413",
            "description": "limit: размер запроса/снимка либо reason=quota_exceeded. Предметный отказ может быть сохранён в истории команды; ошибка разбора тела до исполнения не сохраняется."
          },
          "415": {
            "$ref": "#/components/responses/Error415"
          },
          "422": {
            "$ref": "#/components/responses/ExternalError422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "description": "Создаёт карточку в конце указанного списка. Нужен ключ с create или write и доступом к доске; список должен принадлежать этой доске. Передайте свежий UUIDv7 в Idempotency-Key и generation из чтения в X-Workspace-Generation. Ответ 201 содержит полный публичный объект, Location его GET и ETag. Объект, rev и результат фиксируются одной транзакцией. If-Match и If-None-Match при создании запрещены и дают 422. При потере ответа или 503 сохраните ID и весь исходный запрос. Проверьте GET /v1/requests/{requestId} либо повторите тот же запрос. replayed=true обозначает исторический результат без второго изменения. ",
        "tags": [
          "Карточки"
        ]
      }
    },
    "/v1/boards/{boardId}/cards/{cardId}": {
      "get": {
        "operationId": "getCard",
        "summary": "Читать карточку с текущим listId",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "boardId",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,128}$"
            },
            "description": "Короткий ID разрешённой доски из GET /v1/boards или ответа создания."
          },
          {
            "in": "path",
            "name": "cardId",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,128}$"
            },
            "description": "Короткий ID карточки в указанной доске. Перенос карточки между списками не меняет этот ID."
          },
          {
            "in": "header",
            "name": "If-None-Match",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Условное чтение по HTTP ETag. При совпадении текущего тега возвращается 304 без JSON. Авторизация и лимиты проверяются до условного ответа. Cache-Control остаётся no-store."
          }
        ],
        "responses": {
          "200": {
            "description": "Результат по контракту api-create.md",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Workspace-Generation": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "Поколение ответа."
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "ID отдельного HTTP-вызова для диагностики; не Idempotency-Key."
              },
              "ETag": {
                "required": true,
                "schema": {
                  "type": "string",
                  "pattern": "^\"[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}:[1-9][0-9]{0,9}\"$"
                },
                "description": "Сильный тег канонического объекта: generation:rev в двойных кавычках. Общая rev консервативно обнаруживает изменения любой доски владельца. При повторе относится к историческому результату."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardResult"
                }
              }
            }
          },
          "304": {
            "description": "Текущее представление не изменилось по If-None-Match. Тело отсутствует. Проверки доступа и квот выполнены; no-store сохраняется.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "ETag": {
                "required": true,
                "schema": {
                  "type": "string",
                  "pattern": "^\"[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}:[1-9][0-9]{0,9}\"$"
                },
                "description": "Сильный тег канонического объекта: generation:rev в двойных кавычках. Общая rev консервативно обнаруживает изменения любой доски владельца. При повторе относится к историческому результату."
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ExternalError401"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "413": {
            "$ref": "#/components/responses/Error413"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "description": "Ответ содержит публичный объект, generation, rev и ETag. Для изменения или удаления скопируйте ETag в If-Match вместе с двойными кавычками. Ревизия общая для учётки. Необязательный If-None-Match позволяет получить 304 без JSON; авторизация и лимиты проверяются и в этом случае. listId показывает текущий список карточки после переноса. Адрес карточки при переносе внутри доски сохраняется. Чужой, отсутствующий или удалённый объект даёт одинаковый 404. Ключ board видит только выбранную доску. Чтение не меняет generation или rev.",
        "tags": [
          "Карточки"
        ]
      },
      "patch": {
        "operationId": "updateCard",
        "summary": "Изменить карточку или переместить её",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "boardId",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,128}$"
            },
            "description": "Короткий ID разрешённой доски из GET /v1/boards или ответа создания."
          },
          {
            "in": "path",
            "name": "cardId",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,128}$"
            },
            "description": "Короткий ID карточки в указанной доске. Перенос карточки между списками не меняет этот ID."
          },
          {
            "in": "header",
            "name": "X-Workspace-Generation",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "generation из текущего чтения. При generation_changed остановите запись и заново согласуйте восстановленные данные."
          },
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/RequestId"
            },
            "description": "Свежий UUIDv7 для нового намерения. Сохраните его до отправки; после таймаута повторяйте прежний ID с тем же запросом. UUIDv4 не подходит."
          },
          {
            "in": "header",
            "name": "If-Match",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/MatchCondition"
            },
            "description": "Сильный ETag из чтения объекта, например \"83f8b814-4d88-4ce1-b68b-f21cdff1fc5e:2\". Принимается общий HTTP-список непрозрачных сильных/слабых тегов, включая запятые внутри кавычек. Совпадение сильное и чувствительно к регистру. Неизвестный корректный тег даёт 412. * отклоняется 422. Условие входит в отпечаток команды."
          }
        ],
        "responses": {
          "200": {
            "description": "Атомарный результат команды и исторические данные.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Workspace-Generation": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "Поколение ответа."
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "ID отдельного HTTP-вызова для диагностики; не Idempotency-Key."
              },
              "ETag": {
                "required": true,
                "schema": {
                  "type": "string",
                  "pattern": "^\"[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}:[1-9][0-9]{0,9}\"$"
                },
                "description": "Сильный тег канонического объекта: generation:rev в двойных кавычках. Общая rev консервативно обнаруживает изменения любой доски владельца. При повторе относится к историческому результату."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardMutationResult"
                },
                "example": {
                  "requestId": "019d0000-0000-7000-8000-000000000001",
                  "data": {
                    "id": "CARD234567",
                    "boardId": "BOARD23456",
                    "listId": "LIST234567",
                    "title": "Позвонить клиенту"
                  },
                  "generation": "83f8b814-4d88-4ce1-b68b-f21cdff1fc5e",
                  "rev": 3,
                  "replayed": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/ExternalError401"
          },
          "403": {
            "$ref": "#/components/responses/ExternalError403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "409": {
            "$ref": "#/components/responses/ExternalError409"
          },
          "412": {
            "$ref": "#/components/responses/Error412"
          },
          "413": {
            "$ref": "#/components/responses/Error413"
          },
          "415": {
            "$ref": "#/components/responses/Error415"
          },
          "422": {
            "$ref": "#/components/responses/ExternalError422"
          },
          "428": {
            "$ref": "#/components/responses/Error428"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "description": "Нужен отдельный ключ с правами read/write. Передайте X-Workspace-Generation, новый UUIDv7 в Idempotency-Key и If-Match с ETag прочитанного объекта. При 412 rev_conflict перечитайте объект и подготовьте новую попытку; не подставляйте свежий If-Match под ID уже отклонённой команды. If-None-Match при записи запрещён и даёт 422. Пропущенное поле сохраняет значение. Несколько переданных полей меняются атомарно; пустой объект и неизвестные поля дают 422. beforeId=null переносит в конец, ID соседа ставит объект перед ним. Ответ 200 содержит полный публичный объект и ETag. Доступны title, listId и beforeId. listId выбирает активный список той же доски; без beforeId карточка добавляется в его конец. Перенос между досками не поддерживается. Без title сохраняется прежний текст целиком, включая старые многострочные карточки. При потере ответа или 503 сохраните ID и весь исходный запрос. Проверьте GET /v1/requests/{requestId} либо повторите тот же запрос. replayed=true обозначает исторический результат без второго изменения. ",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PatchCard"
              },
              "examples": {
                "rename": {
                  "summary": "Изменить текст карточки",
                  "value": {
                    "title": "Позвонить клиенту завтра"
                  }
                },
                "end": {
                  "summary": "Перенести карточку в конец текущего списка",
                  "value": {
                    "beforeId": null
                  }
                },
                "before": {
                  "summary": "Поставить перед соседней карточкой — замените ID",
                  "value": {
                    "beforeId": "CARD345678"
                  }
                },
                "move": {
                  "summary": "Перенести в другой список той же доски — замените ID",
                  "value": {
                    "listId": "LIST345678",
                    "beforeId": null
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Карточки"
        ]
      },
      "delete": {
        "operationId": "deleteCard",
        "summary": "Удалить карточку",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "boardId",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,128}$"
            },
            "description": "Короткий ID разрешённой доски из GET /v1/boards или ответа создания."
          },
          {
            "in": "path",
            "name": "cardId",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,128}$"
            },
            "description": "Короткий ID карточки в указанной доске. Перенос карточки между списками не меняет этот ID."
          },
          {
            "in": "header",
            "name": "X-Workspace-Generation",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "generation из текущего чтения. При generation_changed остановите запись и заново согласуйте восстановленные данные."
          },
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/RequestId"
            },
            "description": "Свежий UUIDv7 для нового намерения. Сохраните его до отправки; после таймаута повторяйте прежний ID с тем же запросом. UUIDv4 не подходит."
          },
          {
            "in": "header",
            "name": "If-Match",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/MatchCondition"
            },
            "description": "Сильный ETag из чтения объекта, например \"83f8b814-4d88-4ce1-b68b-f21cdff1fc5e:2\". Принимается общий HTTP-список непрозрачных сильных/слабых тегов, включая запятые внутри кавычек. Совпадение сильное и чувствительно к регистру. Неизвестный корректный тег даёт 412. * отклоняется 422. Условие входит в отпечаток команды."
          }
        ],
        "responses": {
          "200": {
            "description": "Атомарный результат команды и исторические данные.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Workspace-Generation": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "Поколение ответа."
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "ID отдельного HTTP-вызова для диагностики; не Idempotency-Key."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardDeleteResult"
                },
                "example": {
                  "requestId": "019d0000-0000-7000-8000-000000000001",
                  "data": {
                    "id": "CARD234567",
                    "boardId": "BOARD23456",
                    "listId": "LIST234567",
                    "deleted": true
                  },
                  "generation": "83f8b814-4d88-4ce1-b68b-f21cdff1fc5e",
                  "rev": 3,
                  "replayed": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/ExternalError401"
          },
          "403": {
            "$ref": "#/components/responses/ExternalError403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "409": {
            "$ref": "#/components/responses/ExternalError409"
          },
          "412": {
            "$ref": "#/components/responses/Error412"
          },
          "413": {
            "$ref": "#/components/responses/Error413"
          },
          "422": {
            "$ref": "#/components/responses/ExternalError422"
          },
          "428": {
            "$ref": "#/components/responses/Error428"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "description": "Нужен отдельный ключ с правами read/write. Передайте X-Workspace-Generation, новый UUIDv7 в Idempotency-Key и If-Match с ETag прочитанного объекта. При 412 rev_conflict перечитайте объект и подготовьте новую попытку; не подставляйте свежий If-Match под ID уже отклонённой команды. If-None-Match при записи запрещён и даёт 422. Тело не передавайте. Ответ 200 содержит ID, применимых родителей и deleted=true; ETag удалённого объекта не возвращается. Удаление логическое: физическая очистка и восстановление через этот API не предоставляются. Повтор той же команды возвращает подтверждение даже после удаления; новый DELETE отсутствующего объекта даёт 404. Удаляется только карточка; её список, доска и публичная ссылка доски сохраняются. При потере ответа или 503 сохраните ID и весь исходный запрос. Проверьте GET /v1/requests/{requestId} либо повторите тот же запрос. replayed=true обозначает исторический результат без второго изменения. ",
        "tags": [
          "Карточки"
        ]
      }
    },
    "/v1/requests/{requestId}": {
      "get": {
        "operationId": "getExternalRequest",
        "summary": "Найти результат команды этого доступа",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "requestId",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/RequestId"
            },
            "description": "UUIDv7 прежней логической команды — то же значение, которое было передано в Idempotency-Key."
          }
        ],
        "responses": {
          "200": {
            "description": "Результат по контракту api-create.md",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "X-Workspace-Generation": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "Поколение ответа."
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "ID отдельного HTTP-вызова для диагностики; не Idempotency-Key."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalRequestResult"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ExternalError401"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "405": {
            "$ref": "#/components/responses/Error405"
          },
          "409": {
            "$ref": "#/components/responses/ExternalError409",
            "description": "generation_changed: результат относится к другому поколению. Старую команду автоматически на новое поколение не переносить."
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "description": "Возвращает сохранённый status/body команды, выполненной этим постоянным API-доступом. В requestId укажите прежний Idempotency-Key. Ротация секрета сохраняет доступ к результату, другой ключ той же учётки получает 404. outcome.body содержит исторические data/rev; внешняя rev отражает состояние учётки в момент этого чтения. Сохранённый успех не восстанавливает позднее удалённый объект. При 404 можно повторить неизменённую команду с прежним ID; отсутствие результата не доказывает откат.",
        "tags": [
          "Результаты команд"
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "trk_UUID.base64url-secret",
        "description": "Вставьте сам секрет trk_... без слова Bearer. Swagger добавит Authorization: Bearer. Права и область задаются при выпуске ключа в настройках учётки."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "minLength": 1,
            "description": "Стабильный код ошибки для программы."
          },
          "message": {
            "type": "string",
            "minLength": 1,
            "description": "Понятное пользователю объяснение ошибки на русском языке."
          },
          "path": {
            "type": "string",
            "description": "Поле или HTTP-заголовок, к которому относится ошибка. Может отсутствовать."
          },
          "reason": {
            "type": "string",
            "description": "Уточняющий код причины, например blank или unsupported_precondition. Может отсутствовать."
          },
          "currentVersion": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2147483647,
            "description": "Текущая версия управляемого ключа при конфликте сессионной команды."
          },
          "currentRev": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2147483647,
            "description": "Текущая общая ревизия при конфликте If-Match. Перечитайте объект перед новой попыткой."
          }
        },
        "required": [
          "code",
          "message"
        ],
        "additionalProperties": true,
        "description": "Отказ API. Для обработки используйте code и при наличии reason/path; message предназначен человеку. Поля, неприменимые к ошибке, могут отсутствовать."
      },
      "RequestId": {
        "type": "string",
        "format": "uuid",
        "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-7[a-fA-F0-9]{3}-[89abAB][a-fA-F0-9]{3}-[a-fA-F0-9]{12}$",
        "description": "UUIDv7. Для нового исполнения возраст до 24 часов, будущее до 5 минут. Сначала проверяется сохранённый результат, хранение 7 суток. Регистр UUID на входе незначим; сервер возвращает нижний регистр."
      },
      "Board": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{1,128}$",
            "description": "Короткий ID объекта. Стабилен при переименовании и переносе."
          },
          "title": {
            "type": "string",
            "description": "Отображаемое название объекта."
          },
          "color": {
            "enum": [
              "gray",
              "green",
              "cyan",
              "purple",
              "red",
              "brown",
              "blue",
              "sage",
              "kobi",
              "cadet",
              "baby",
              "sandy"
            ],
            "description": "Код цвета доски из перечисленных значений."
          }
        },
        "required": [
          "id",
          "title",
          "color"
        ],
        "additionalProperties": false,
        "description": "Публичный заголовок доски без списков, карточек и кода публикации."
      },
      "Card": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{1,128}$",
            "description": "Короткий ID объекта. Стабилен при переименовании и переносе."
          },
          "boardId": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{1,128}$",
            "description": "ID родительской доски."
          },
          "listId": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{1,128}$",
            "description": "ID текущего списка карточки."
          },
          "title": {
            "type": "string",
            "maxLength": 2000,
            "description": "Старый многострочный текст сохраняется без обрезания."
          }
        },
        "required": [
          "id",
          "boardId",
          "listId",
          "title"
        ],
        "additionalProperties": false,
        "description": "Публичная карточка с родительской доской и текущим списком."
      },
      "List": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{1,128}$",
            "description": "Короткий ID объекта. Стабилен при переименовании и переносе."
          },
          "boardId": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{1,128}$",
            "description": "ID родительской доски."
          },
          "title": {
            "type": "string",
            "description": "Отображаемое название объекта."
          },
          "cards": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Card"
            },
            "description": "Карточки списка в текущем порядке."
          }
        },
        "required": [
          "id",
          "boardId",
          "title",
          "cards"
        ],
        "additionalProperties": false,
        "description": "Список с карточками в согласованном снимке."
      },
      "SnapshotBoard": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{1,128}$",
            "description": "Короткий ID объекта. Стабилен при переименовании и переносе."
          },
          "title": {
            "type": "string",
            "description": "Отображаемое название объекта."
          },
          "color": {
            "enum": [
              "gray",
              "green",
              "cyan",
              "purple",
              "red",
              "brown",
              "blue",
              "sage",
              "kobi",
              "cadet",
              "baby",
              "sandy"
            ],
            "description": "Код цвета доски из перечисленных значений."
          },
          "lists": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/List"
            },
            "description": "Списки доски в текущем порядке."
          }
        },
        "required": [
          "id",
          "title",
          "color",
          "lists"
        ],
        "additionalProperties": false,
        "description": "Доска со списками и карточками в согласованном снимке."
      },
      "Snapshot": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "boards": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/SnapshotBoard"
                }
              }
            },
            "required": [
              "boards"
            ],
            "additionalProperties": false,
            "description": "Публичные данные ответа; состав определяется методом."
          },
          "generation": {
            "type": "string",
            "format": "uuid",
            "description": "Поколение данных после восстановления сервера. Смена поколения требует заново согласовать запись."
          },
          "rev": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2147483647,
            "description": "Общая ревизия всей учётки в момент этого чтения."
          }
        },
        "required": [
          "data",
          "generation",
          "rev"
        ],
        "additionalProperties": false,
        "description": "Полное разрешённое дерево и общая версия одного чтения."
      },
      "BoardResult": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Board",
            "description": "Публичные данные ответа; состав определяется методом."
          },
          "generation": {
            "type": "string",
            "format": "uuid",
            "description": "Поколение данных после восстановления сервера. Смена поколения требует заново согласовать запись."
          },
          "rev": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2147483647,
            "description": "Общая ревизия всей учётки в момент этого чтения."
          }
        },
        "required": [
          "data",
          "generation",
          "rev"
        ],
        "additionalProperties": false,
        "description": "Текущий заголовок доски и общая версия учётки."
      },
      "BoardsResult": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Board"
            },
            "description": "Публичные данные ответа; состав определяется методом."
          },
          "generation": {
            "type": "string",
            "format": "uuid",
            "description": "Поколение данных после восстановления сервера. Смена поколения требует заново согласовать запись."
          },
          "rev": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2147483647,
            "description": "Общая ревизия всей учётки в момент этого чтения."
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "description": "Размер страницы, использованный для этого ответа."
          },
          "offset": {
            "type": "integer",
            "minimum": 0,
            "description": "Число объектов перед началом этой страницы."
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "Общее число доступных объектов этой коллекции в указанной ревизии."
          },
          "hasMore": {
            "type": "boolean",
            "description": "Есть следующая страница этого согласованного набора. Для продолжения используйте Link с rel=next."
          }
        },
        "required": [
          "data",
          "generation",
          "rev",
          "limit",
          "offset",
          "total",
          "hasMore"
        ],
        "additionalProperties": false,
        "description": "Страница заголовков разрешённых досок в предметном порядке."
      },
      "ListHeader": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{1,128}$",
            "description": "Короткий ID объекта. Стабилен при переименовании и переносе."
          },
          "boardId": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{1,128}$",
            "description": "ID родительской доски."
          },
          "title": {
            "type": "string",
            "description": "Отображаемое название объекта."
          }
        },
        "required": [
          "id",
          "boardId",
          "title"
        ],
        "additionalProperties": false,
        "description": "Публичный заголовок списка без карточек."
      },
      "ListResult": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/ListHeader",
            "description": "Публичные данные ответа; состав определяется методом."
          },
          "generation": {
            "type": "string",
            "format": "uuid",
            "description": "Поколение данных после восстановления сервера. Смена поколения требует заново согласовать запись."
          },
          "rev": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2147483647,
            "description": "Общая ревизия всей учётки в момент этого чтения."
          }
        },
        "required": [
          "data",
          "generation",
          "rev"
        ],
        "additionalProperties": false,
        "description": "Текущий заголовок списка и общая версия учётки."
      },
      "CardResult": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Card",
            "description": "Публичные данные ответа; состав определяется методом."
          },
          "generation": {
            "type": "string",
            "format": "uuid",
            "description": "Поколение данных после восстановления сервера. Смена поколения требует заново согласовать запись."
          },
          "rev": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2147483647,
            "description": "Общая ревизия всей учётки в момент этого чтения."
          }
        },
        "required": [
          "data",
          "generation",
          "rev"
        ],
        "additionalProperties": false,
        "description": "Текущая карточка с текущим listId и общей версией учётки."
      },
      "ListsResult": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ListHeader"
            },
            "description": "Публичные данные ответа; состав определяется методом."
          },
          "generation": {
            "type": "string",
            "format": "uuid",
            "description": "Поколение данных после восстановления сервера. Смена поколения требует заново согласовать запись."
          },
          "rev": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2147483647,
            "description": "Общая ревизия всей учётки в момент этого чтения."
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "description": "Размер страницы, использованный для этого ответа."
          },
          "offset": {
            "type": "integer",
            "minimum": 0,
            "description": "Число объектов перед началом этой страницы."
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "Общее число доступных объектов этой коллекции в указанной ревизии."
          },
          "hasMore": {
            "type": "boolean",
            "description": "Есть следующая страница этого согласованного набора. Для продолжения используйте Link с rel=next."
          }
        },
        "required": [
          "data",
          "generation",
          "rev",
          "limit",
          "offset",
          "total",
          "hasMore"
        ],
        "additionalProperties": false,
        "description": "Страница заголовков списков одной доски."
      },
      "CardsResult": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Card"
            },
            "description": "Публичные данные ответа; состав определяется методом."
          },
          "generation": {
            "type": "string",
            "format": "uuid",
            "description": "Поколение данных после восстановления сервера. Смена поколения требует заново согласовать запись."
          },
          "rev": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2147483647,
            "description": "Общая ревизия всей учётки в момент этого чтения."
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "description": "Размер страницы, использованный для этого ответа."
          },
          "offset": {
            "type": "integer",
            "minimum": 0,
            "description": "Число объектов перед началом этой страницы."
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "Общее число доступных объектов этой коллекции в указанной ревизии."
          },
          "hasMore": {
            "type": "boolean",
            "description": "Есть следующая страница этого согласованного набора. Для продолжения используйте Link с rel=next."
          }
        },
        "required": [
          "data",
          "generation",
          "rev",
          "limit",
          "offset",
          "total",
          "hasMore"
        ],
        "additionalProperties": false,
        "description": "Страница карточек одного списка."
      },
      "CreateBoard": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80,
            "description": "Непустая после проверки пробелов корректная Unicode-строка, до 80 единиц UTF-16; NUL запрещён. Сохраняется без trim и нормализации. maxLength — верхняя граница code points, не эквивалент UTF-16; точную проверку выполняют x-maxUtf16Length, x-wellFormedUnicode и x-nonBlank в контрактном валидаторе проекта.",
            "x-maxUtf16Length": 80,
            "x-wellFormedUnicode": true,
            "x-nonBlank": true,
            "pattern": "^[^\\u0000]*$"
          },
          "color": {
            "enum": [
              "gray",
              "green",
              "cyan",
              "purple",
              "red",
              "brown",
              "blue",
              "sage",
              "kobi",
              "cadet",
              "baby",
              "sandy"
            ],
            "default": "gray",
            "description": "Код цвета доски из перечисленных значений."
          }
        },
        "required": [
          "title"
        ],
        "additionalProperties": false,
        "description": "Новая доска. title обязателен; пропущенный color получает значение gray."
      },
      "CreateList": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80,
            "description": "Непустая после проверки пробелов корректная Unicode-строка, до 80 единиц UTF-16; NUL запрещён. Сохраняется без trim и нормализации. maxLength — верхняя граница code points, не эквивалент UTF-16; точную проверку выполняют x-maxUtf16Length, x-wellFormedUnicode и x-nonBlank в контрактном валидаторе проекта.",
            "x-maxUtf16Length": 80,
            "x-wellFormedUnicode": true,
            "x-nonBlank": true,
            "pattern": "^[^\\u0000]*$"
          }
        },
        "required": [
          "title"
        ],
        "additionalProperties": false,
        "description": "Новый список в конце указанной доски."
      },
      "CreateCard": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500,
            "pattern": "^[^\\r\\n\\u2028\\u2029\\u0000]*$",
            "description": "Непустая после проверки пробелов корректная Unicode-строка, до 500 единиц UTF-16; NUL запрещён. Сохраняется без trim и нормализации. maxLength — верхняя граница code points, не эквивалент UTF-16; точную проверку выполняют x-maxUtf16Length, x-wellFormedUnicode и x-nonBlank в контрактном валидаторе проекта. Переносы строк запрещены; старые карточки читаются без обрезания.",
            "x-maxUtf16Length": 500,
            "x-wellFormedUnicode": true,
            "x-nonBlank": true
          }
        },
        "required": [
          "title"
        ],
        "additionalProperties": false,
        "description": "Новая карточка в конце указанного списка."
      },
      "CreatedObject": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/Board"
          },
          {
            "$ref": "#/components/schemas/ListHeader"
          },
          {
            "$ref": "#/components/schemas/Card"
          }
        ],
        "description": "Подтверждённая публичная модель созданного объекта. В историю сохраняются исходные поля; повтор не подставляет текущее состояние."
      },
      "CreateResult": {
        "type": "object",
        "properties": {
          "requestId": {
            "$ref": "#/components/schemas/RequestId",
            "description": "ID логической команды из Idempotency-Key. Не идентификатор отдельного HTTP-вызова X-Request-Id."
          },
          "data": {
            "$ref": "#/components/schemas/CreatedObject",
            "description": "Публичные данные ответа; состав определяется методом."
          },
          "generation": {
            "type": "string",
            "format": "uuid",
            "description": "Поколение данных после восстановления сервера. Смена поколения требует заново согласовать запись."
          },
          "rev": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2147483647,
            "description": "Общая ревизия учётки после этой команды; при повторе историческая, не текущая версия объекта."
          },
          "replayed": {
            "type": "boolean",
            "description": "true: возвращён сохранённый итог прежней команды, второго создания не было."
          }
        },
        "required": [
          "requestId",
          "data",
          "generation",
          "rev",
          "replayed"
        ],
        "additionalProperties": false,
        "description": "Подтверждённый результат создания: исходный публичный объект и версия после команды."
      },
      "ExternalRequestResult": {
        "type": "object",
        "properties": {
          "requestId": {
            "$ref": "#/components/schemas/RequestId",
            "description": "ID логической команды из Idempotency-Key; отличается от X-Request-Id отдельного HTTP-вызова."
          },
          "outcome": {
            "type": "object",
            "properties": {
              "status": {
                "type": "integer",
                "minimum": 200,
                "maximum": 499,
                "description": "HTTP-статус первоначального подтверждённого исхода команды."
              },
              "body": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/CommandResult"
                  },
                  {
                    "$ref": "#/components/schemas/Error"
                  }
                ],
                "description": "Исходное публичное тело успеха или ошибки."
              }
            },
            "required": [
              "status",
              "body"
            ],
            "additionalProperties": false,
            "description": "Сохранённый HTTP-статус и тело прежней команды. Это исторический результат, а не новое исполнение."
          },
          "generation": {
            "type": "string",
            "format": "uuid",
            "description": "Поколение данных после восстановления сервера. Смена поколения требует заново согласовать запись."
          },
          "rev": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2147483647,
            "description": "Текущая общая ревизия при чтении результата. outcome.body.rev остаётся исторической ревизией команды."
          }
        },
        "required": [
          "requestId",
          "outcome",
          "generation",
          "rev"
        ],
        "additionalProperties": false,
        "description": "Подтверждённый исход прежней команды этого API-доступа и текущая версия учётки."
      },
      "BoardCreateResult": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CreateResult"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Board"
              }
            }
          }
        ],
        "description": "Исторический результат создания Board."
      },
      "ListCreateResult": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CreateResult"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/ListHeader"
              }
            }
          }
        ],
        "description": "Исторический результат создания List."
      },
      "CardCreateResult": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CreateResult"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Card"
              }
            }
          }
        ],
        "description": "Исторический результат создания Card."
      },
      "PatchBoard": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80,
            "description": "Непустая после проверки пробелов корректная Unicode-строка, до 80 единиц UTF-16; NUL запрещён. Сохраняется без trim и нормализации. maxLength — верхняя граница code points, не эквивалент UTF-16; точную проверку выполняют x-maxUtf16Length, x-wellFormedUnicode и x-nonBlank в контрактном валидаторе проекта.",
            "x-maxUtf16Length": 80,
            "x-wellFormedUnicode": true,
            "x-nonBlank": true,
            "pattern": "^[^\\u0000]*$"
          },
          "color": {
            "enum": [
              "gray",
              "green",
              "cyan",
              "purple",
              "red",
              "brown",
              "blue",
              "sage",
              "kobi",
              "cadet",
              "baby",
              "sandy"
            ],
            "description": "Код цвета доски из перечисленных значений."
          },
          "beforeId": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^[A-Za-z0-9_-]{1,128}$",
            "description": "ID следующего активного соседа в том же порядке. null переносит в конец. Отсутствие сохраняет порядок; ID самого объекта не принимается."
          }
        },
        "minProperties": 1,
        "additionalProperties": false,
        "description": "Изменить поля или порядок доски. Отсутствие поля сохраняет значение; null разрешён только для beforeId."
      },
      "PatchList": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80,
            "description": "Непустая после проверки пробелов корректная Unicode-строка, до 80 единиц UTF-16; NUL запрещён. Сохраняется без trim и нормализации. maxLength — верхняя граница code points, не эквивалент UTF-16; точную проверку выполняют x-maxUtf16Length, x-wellFormedUnicode и x-nonBlank в контрактном валидаторе проекта.",
            "x-maxUtf16Length": 80,
            "x-wellFormedUnicode": true,
            "x-nonBlank": true,
            "pattern": "^[^\\u0000]*$"
          },
          "beforeId": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^[A-Za-z0-9_-]{1,128}$",
            "description": "ID следующего активного соседа в том же порядке. null переносит в конец. Отсутствие сохраняет порядок; ID самого объекта не принимается."
          }
        },
        "minProperties": 1,
        "additionalProperties": false,
        "description": "Переименовать или переставить список внутри одной доски."
      },
      "PatchCard": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500,
            "pattern": "^[^\\r\\n\\u2028\\u2029\\u0000]*$",
            "description": "Непустая после проверки пробелов корректная Unicode-строка, до 500 единиц UTF-16; NUL запрещён. Сохраняется без trim и нормализации. maxLength — верхняя граница code points, не эквивалент UTF-16; точную проверку выполняют x-maxUtf16Length, x-wellFormedUnicode и x-nonBlank в контрактном валидаторе проекта. Переносы строк запрещены; старые карточки читаются без обрезания.",
            "x-maxUtf16Length": 500,
            "x-wellFormedUnicode": true,
            "x-nonBlank": true
          },
          "listId": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{1,128}$",
            "description": "Активный список той же доски. Смена списка без beforeId добавляет карточку в конец."
          },
          "beforeId": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^[A-Za-z0-9_-]{1,128}$",
            "description": "ID следующего активного соседа в том же порядке. null переносит в конец. Отсутствие сохраняет порядок; ID самого объекта не принимается."
          }
        },
        "minProperties": 1,
        "additionalProperties": false,
        "description": "Изменить текст или перенести карточку внутри одной доски. Пропущенные поля сохраняются."
      },
      "DeletedBoard": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{1,128}$",
            "description": "Короткий ID объекта. Стабилен при переименовании и переносе."
          },
          "deleted": {
            "const": true,
            "description": "true подтверждает логическое удаление объекта."
          }
        },
        "required": [
          "id",
          "deleted"
        ],
        "additionalProperties": false,
        "description": "Подтверждение логического удаления доски."
      },
      "DeletedList": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{1,128}$",
            "description": "Короткий ID объекта. Стабилен при переименовании и переносе."
          },
          "boardId": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{1,128}$",
            "description": "ID родительской доски."
          },
          "deleted": {
            "const": true,
            "description": "true подтверждает логическое удаление объекта."
          }
        },
        "required": [
          "id",
          "boardId",
          "deleted"
        ],
        "additionalProperties": false,
        "description": "Подтверждение логического удаления списка."
      },
      "DeletedCard": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{1,128}$",
            "description": "Короткий ID объекта. Стабилен при переименовании и переносе."
          },
          "boardId": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{1,128}$",
            "description": "ID родительской доски."
          },
          "listId": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{1,128}$",
            "description": "ID текущего списка карточки."
          },
          "deleted": {
            "const": true,
            "description": "true подтверждает логическое удаление объекта."
          }
        },
        "required": [
          "id",
          "boardId",
          "listId",
          "deleted"
        ],
        "additionalProperties": false,
        "description": "Подтверждение логического удаления карточки."
      },
      "CommandObject": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/Board"
          },
          {
            "$ref": "#/components/schemas/ListHeader"
          },
          {
            "$ref": "#/components/schemas/Card"
          },
          {
            "$ref": "#/components/schemas/DeletedBoard"
          },
          {
            "$ref": "#/components/schemas/DeletedList"
          },
          {
            "$ref": "#/components/schemas/DeletedCard"
          }
        ],
        "description": "Полный публичный объект после создания/изменения либо маркер удаления."
      },
      "CommandResult": {
        "type": "object",
        "properties": {
          "requestId": {
            "$ref": "#/components/schemas/RequestId",
            "description": "ID логической команды из Idempotency-Key. Не идентификатор отдельного HTTP-вызова X-Request-Id."
          },
          "data": {
            "$ref": "#/components/schemas/CommandObject",
            "description": "Публичные данные ответа; состав определяется методом."
          },
          "generation": {
            "type": "string",
            "format": "uuid",
            "description": "Поколение данных после восстановления сервера. Смена поколения требует заново согласовать запись."
          },
          "rev": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2147483647,
            "description": "Общая ревизия учётки после этой команды; при повторе историческая, не текущая версия объекта."
          },
          "replayed": {
            "type": "boolean",
            "description": "true: возвращён исторический результат той же команды, повторного изменения не было."
          }
        },
        "required": [
          "requestId",
          "data",
          "generation",
          "rev",
          "replayed"
        ],
        "additionalProperties": false,
        "description": "Подтверждённый исход логической команды. При повторе содержит исторические данные и версию."
      },
      "MutationResult": {
        "$ref": "#/components/schemas/CommandResult",
        "description": "Подтверждённый результат PATCH или DELETE."
      },
      "BoardMutationResult": {
        "allOf": [
          {
            "$ref": "#/components/schemas/MutationResult"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Board"
              }
            }
          }
        ],
        "description": "Историческое публичное представление после PATCH."
      },
      "BoardDeleteResult": {
        "allOf": [
          {
            "$ref": "#/components/schemas/MutationResult"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/DeletedBoard"
              }
            }
          }
        ],
        "description": "Историческое подтверждение удаления без восстановления объекта."
      },
      "ListMutationResult": {
        "allOf": [
          {
            "$ref": "#/components/schemas/MutationResult"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/ListHeader"
              }
            }
          }
        ],
        "description": "Историческое публичное представление после PATCH."
      },
      "ListDeleteResult": {
        "allOf": [
          {
            "$ref": "#/components/schemas/MutationResult"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/DeletedList"
              }
            }
          }
        ],
        "description": "Историческое подтверждение удаления без восстановления объекта."
      },
      "CardMutationResult": {
        "allOf": [
          {
            "$ref": "#/components/schemas/MutationResult"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Card"
              }
            }
          }
        ],
        "description": "Историческое публичное представление после PATCH."
      },
      "CardDeleteResult": {
        "allOf": [
          {
            "$ref": "#/components/schemas/MutationResult"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/DeletedCard"
              }
            }
          }
        ],
        "description": "Историческое подтверждение удаления без восстановления объекта."
      },
      "MatchCondition": {
        "type": "string",
        "minLength": 1,
        "maxLength": 2048,
        "pattern": "^[\\t ,]*(?:W/)?\"[\\x21\\x23-\\x7e\\x80-\\xff]*\"[\\t ]*(?:,[\\t ,]*(?:W/)?\"[\\x21\\x23-\\x7e\\x80-\\xff]*\"[\\t ]*)*[\\t ,]*(?![\\s\\S])",
        "description": "HTTP-список непрозрачных ETag, максимум 2048 символов. Допустимы сильные и слабые теги с префиксом только W/, SP/HTAB и пустые элементы списка при наличии хотя бы одного тега. Запятая внутри кавычек является частью тега. Значения не нормализуются по регистру. Неизвестный корректный тег, включая пустой, приводит к 412 при отсутствии совпадения. * отклоняется 422: API требует явные теги."
      }
    },
    "responses": {
      "Error400": {
        "description": "bad_json: JSON не удалось прочитать. Изменение не выполнено; исправьте тело перед новой отправкой.",
        "headers": {
          "Cache-Control": {
            "schema": {
              "const": "no-store"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "code": "bad_json",
              "message": "Не удалось прочитать запрос. Повторите попытку."
            }
          }
        }
      },
      "Error404": {
        "description": "not_found: объект или результат недоступен этому доступу, отсутствует либо удалён. Чужие данные не раскрываются.",
        "headers": {
          "Cache-Control": {
            "schema": {
              "const": "no-store"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "code": "not_found",
              "message": "Запрошенная страница или доска недоступна."
            }
          }
        }
      },
      "Error413": {
        "description": "limit: тело запроса превышает разрешённый размер. Исправьте запрос; изменение не выполнено.",
        "headers": {
          "Cache-Control": {
            "schema": {
              "const": "no-store"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Error422": {
        "description": "invalid_input: проверьте входные поля по path/reason. Исправьте запрос перед новой отправкой.",
        "headers": {
          "Cache-Control": {
            "schema": {
              "const": "no-store"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Error429": {
        "description": "rate_limit: превышен бюджет частоты. Подождите Retry-After секунд; при неизвестном исходе сохраняйте прежний ID и запрос.",
        "headers": {
          "Cache-Control": {
            "schema": {
              "const": "no-store"
            }
          },
          "Retry-After": {
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "code": "rate_limit",
              "message": "Слишком много запросов. Подождите и повторите попытку."
            }
          }
        }
      },
      "Error503": {
        "description": "temporarily_unavailable: сервер временно не может обработать запрос. Подождите Retry-After секунд и проверьте результат прежней команды; новый ID автоматически не создавайте.",
        "headers": {
          "Cache-Control": {
            "schema": {
              "const": "no-store"
            }
          },
          "Retry-After": {
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "code": "temporarily_unavailable",
              "message": "Сервис занят. Подождите и повторите попытку."
            }
          }
        }
      },
      "Error500": {
        "description": "server_error: непредвиденная ошибка сервера. Исход записи может быть неизвестен; проверьте сохранённый результат и сохраняйте прежний ID.",
        "headers": {
          "Cache-Control": {
            "schema": {
              "const": "no-store"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "code": "server_error",
              "message": "Сервис временно недоступен. Повторите попытку позже."
            }
          }
        }
      },
      "ExternalError401": {
        "description": "invalid_key — Bearer-ключ отсутствует, недействителен либо отозван.",
        "headers": {
          "Cache-Control": {
            "schema": {
              "const": "no-store"
            }
          },
          "WWW-Authenticate": {
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^Bearer(?: |$)"
            },
            "description": "Bearer challenge. Basic Auth не используется."
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "code": "invalid_key",
              "message": "API-ключ недействителен или отозван."
            }
          }
        }
      },
      "ExternalError403": {
        "description": "scope_denied: ключ не имеет требуемого create/write либо операция перестановки доски требует scope=all. Ключ read/create не получает write автоматически.",
        "headers": {
          "Cache-Control": {
            "schema": {
              "const": "no-store"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "code": "scope_denied",
              "message": "API-ключ не разрешает это действие в выбранной области."
            }
          }
        }
      },
      "ExternalError409": {
        "description": "generation_changed: остановите запись после восстановления данных. rev_conflict при пагинации: перечитайте страницы. request_reused: прежний ID пришёл с другим вводом. request_expired: срок нового исполнения UUIDv7 истёк. key_limit: заполнена история команд. Если исход неизвестен, сначала ищите результат прежнего ID.",
        "headers": {
          "Cache-Control": {
            "schema": {
              "const": "no-store"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Error405": {
        "description": "Метод не поддерживается для известного внешнего ресурса. Допустимые методы указаны в Allow.",
        "headers": {
          "Cache-Control": {
            "schema": {
              "const": "no-store"
            }
          },
          "Allow": {
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            }
          },
          "Accept-Patch": {
            "schema": {
              "const": "application/json"
            },
            "description": "Частичное изменение через PATCH принимает JSON по схеме этого ресурса."
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Error"
                },
                {
                  "type": "object",
                  "properties": {
                    "code": {
                      "const": "method_not_allowed"
                    }
                  }
                }
              ]
            }
          }
        }
      },
      "Error415": {
        "description": "Не поддерживаются Content-Type, Content-Encoding либо charset. Объект и итог команды не созданы.",
        "headers": {
          "Cache-Control": {
            "schema": {
              "const": "no-store"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Error"
                },
                {
                  "type": "object",
                  "properties": {
                    "code": {
                      "const": "unsupported_media_type"
                    }
                  }
                }
              ]
            },
            "examples": {
              "contentType": {
                "value": {
                  "code": "unsupported_media_type",
                  "message": "Передайте тело в формате application/json.",
                  "reason": "content_type"
                }
              }
            }
          }
        }
      },
      "ExternalError422": {
        "description": "invalid_input: неверное поле или формат предусловия. Пустой PATCH, unknown field, beforeId=self, некорректные If-Match и неподдерживаемое * отклоняются до исполнения; код и path/reason объясняют исправление. Неподдерживаемое условие создания/записи даёт reason=unsupported_precondition с именем заголовка в path; HTTP-условие не игнорируется.",
        "headers": {
          "Cache-Control": {
            "schema": {
              "const": "no-store"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "examples": {
              "blankTitle": {
                "summary": "Пустое название после проверки пробелов",
                "value": {
                  "code": "invalid_input",
                  "message": "Введите непустое название в title. Одних пробелов недостаточно.",
                  "path": "title",
                  "reason": "blank"
                }
              },
              "unsupportedPrecondition": {
                "summary": "If-None-Match запрещён для изменяющей команды",
                "value": {
                  "code": "invalid_input",
                  "message": "Этот условный заголовок не поддерживается данным методом. Для PATCH и DELETE используйте If-Match; If-None-Match доступен только при чтении.",
                  "path": "If-None-Match",
                  "reason": "unsupported_precondition"
                }
              }
            }
          }
        }
      },
      "Error412": {
        "description": "rev_conflict: If-Match не совпадает с текущим ETag разрешённого объекта. Команда не меняет данные, отказ сохраняется при наличии места в истории. Перечитать состояние и осознанно создать новую попытку.",
        "headers": {
          "Cache-Control": {
            "schema": {
              "const": "no-store"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Error"
                },
                {
                  "type": "object",
                  "properties": {
                    "code": {
                      "const": "rev_conflict"
                    },
                    "currentRev": {
                      "type": "integer",
                      "minimum": 1,
                      "maximum": 2147483647
                    }
                  },
                  "required": [
                    "currentRev"
                  ]
                }
              ]
            },
            "example": {
              "code": "rev_conflict",
              "message": "Данные изменились. Перечитайте объект и подготовьте отдельную попытку.",
              "currentRev": 3
            }
          }
        }
      },
      "Error428": {
        "description": "precondition_required: PATCH/DELETE требуют If-Match прочитанного объекта. Команда не исполнялась и результат не сохранён.",
        "headers": {
          "Cache-Control": {
            "schema": {
              "const": "no-store"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Error"
                },
                {
                  "type": "object",
                  "properties": {
                    "code": {
                      "const": "precondition_required"
                    },
                    "path": {
                      "const": "If-Match"
                    }
                  },
                  "required": [
                    "path"
                  ]
                }
              ]
            },
            "example": {
              "code": "precondition_required",
              "message": "Прочитайте объект и передайте ETag в If-Match.",
              "path": "If-Match"
            }
          }
        }
      }
    }
  },
  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
  "tags": [
    {
      "name": "Доски",
      "description": "Получить, создать, переименовать, перекрасить, переставить или удалить свою доску."
    },
    {
      "name": "Списки",
      "description": "Управлять списками и их порядком внутри одной доски."
    },
    {
      "name": "Карточки",
      "description": "Управлять карточками и переносить их между списками одной доски."
    },
    {
      "name": "Снимок данных",
      "description": "Прочитать согласованное дерево разрешённых досок за один запрос."
    },
    {
      "name": "Результаты команд",
      "description": "Узнать подтверждённый исход команды после потери ответа."
    }
  ]
}
