{
  "openapi":"3.1.0",
  "info":{"title":"DAO DZEN API","version":"1.3.0","description":"HTTPS-only API для подтверждённых клиентов и владельца сайта. Токен привязан к пользователю, подключению, текущей роли и организации. Все изменяющие запросы используют application/json; конкурентные изменения защищены ETag/If-Match."},
  "servers":[{"url":"/api/v1"}],
  "security":[{"bearerAuth":[]}],
  "components":{
    "securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"opaque","description":"Короткоживущий токен на 15 минут, полученный через /auth/token."}},
    "parameters":{"TaskId":{"name":"taskId","in":"path","required":true,"schema":{"type":"string"}},"IfMatch":{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"},"description":"ETag-версия объекта. Без заголовка возвращается 428."},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":120},"description":"Уникальный ключ создания задачи; повтор возвращает исходный результат."}},
    "schemas":{
      "Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":true},"requestId":{"type":"string"}}}}},
      "Token":{"type":"object","required":["accessToken","tokenType","expiresIn","expiresAt","scopes"],"properties":{"accessToken":{"type":"string"},"tokenType":{"const":"Bearer"},"expiresIn":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time"},"scopes":{"type":"array","items":{"type":"string"}}}},
      "User":{"type":"object","required":["id","username","role","status"],"properties":{"id":{"type":"string"},"username":{"type":"string"},"role":{"type":"string"},"status":{"type":"string"},"approvalStatus":{"type":"string"},"profile":{"type":"object","additionalProperties":true}}},
      "Task":{"type":"object","required":["id","organizationId","status","version","title"],"properties":{"id":{"type":"string"},"number":{"type":["integer","null"]},"organizationId":{"type":"string"},"requesterUserId":{"type":"string"},"assigneeUserId":{"type":["string","null"]},"status":{"type":"string"},"priority":{"enum":["low","normal","high","critical"]},"dueAt":{"type":["string","null"],"format":"date-time"},"version":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string"},"customFields":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},
      "Organization":{"type":"object","required":["id","legalType","fullName","shortName","version"],"properties":{"id":{"type":"string"},"legalType":{"enum":["OOO","IP"]},"fullName":{"type":"string"},"shortName":{"type":"string"},"inn":{"type":"string"},"kpp":{"type":"string"},"ogrn":{"type":"string"},"ogrnip":{"type":"string"},"legalAddress":{"type":"string"},"actualAddress":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"website":{"type":"string"},"directorName":{"type":"string"},"status":{"type":"string"},"version":{"type":"integer"}}},
      "Member":{"type":"object","required":["id","name","role","status"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"role":{"type":"string"},"status":{"type":"string"}}},
      "Invitation":{"type":"object","required":["id","email","role","expiresAt"],"properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"role":{"type":"string"},"status":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}}},
      "Webhook":{"type":"object","required":["id","url","events","status"],"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"status":{"enum":["active","disabled","revoked"]},"consecutiveFailures":{"type":"integer"},"secret":{"type":"string","description":"Возвращается только при создании."}}},
      "File":{"type":"object","required":["id","filename","mediaType","byteSize"],"properties":{"id":{"type":"string"},"filename":{"type":"string"},"mediaType":{"enum":["image/png","image/jpeg","image/webp","application/pdf","text/plain"]},"byteSize":{"type":"integer"},"contentUrl":{"type":"string"}}},
      "Page":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{}},"nextCursor":{"type":["string","null"]}}},
      "OrganizationUpdate":{"type":"object","properties":{"legalType":{"enum":["OOO","IP"]},"fullName":{"type":"string","maxLength":240},"shortName":{"type":"string","maxLength":160},"inn":{"type":"string"},"kpp":{"type":"string"},"ogrn":{"type":"string"},"ogrnip":{"type":"string"},"legalAddress":{"type":"string"},"actualAddress":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"website":{"type":"string","format":"uri"},"directorName":{"type":"string"}}},
      "InvitationCreate":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","maxLength":160},"role":{"enum":["org_owner","org_admin","requester","org_viewer","org_billing"]}}},
      "TaskCreate":{"type":"object","required":["title","description"],"properties":{"organizationId":{"type":"string","description":"Обязательно для глобального подключения владельца сайта."},"title":{"type":"string","maxLength":160},"description":{"type":"string","minLength":10,"maxLength":5000},"requesterUserId":{"type":"string"},"priority":{"enum":["low","normal","high","critical"]},"customFields":{"type":"object","additionalProperties":true}}},
      "TaskUpdate":{"type":"object","properties":{"title":{"type":"string","maxLength":160},"description":{"type":"string","minLength":10,"maxLength":5000},"customFields":{"type":"object","additionalProperties":true}}},
      "TransitionCreate":{"type":"object","required":["status"],"properties":{"status":{"type":"string","maxLength":40}}},
      "CommentCreate":{"type":"object","required":["body"],"properties":{"body":{"type":"string","minLength":1,"maxLength":5000},"authorUserId":{"type":"string"}}},
      "FileCreate":{"type":"object","required":["filename","mediaType","contentBase64"],"properties":{"filename":{"type":"string","maxLength":240},"mediaType":{"enum":["image/png","image/jpeg","image/webp","application/pdf","text/plain"]},"contentBase64":{"type":"string","contentEncoding":"base64","description":"До 10 МБ после декодирования."}}},
      "WebhookCreate":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri","pattern":"^https://"},"events":{"type":"array","minItems":1,"items":{"type":"string"}}}},
      "WebhookUpdate":{"type":"object","properties":{"url":{"type":"string","format":"uri","pattern":"^https://"},"events":{"type":"array","minItems":1,"items":{"type":"string"}},"status":{"enum":["active","disabled"]}}}
    },
    "requestBodies":{"OrganizationUpdate":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationUpdate"}}}},"InvitationCreate":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitationCreate"}}}},"TaskCreate":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCreate"}}}},"TaskUpdate":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskUpdate"}}}},"TransitionCreate":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransitionCreate"}}}},"CommentCreate":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentCreate"}}}},"FileCreate":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileCreate"}}}},"WebhookCreate":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreate"}}}},"WebhookUpdate":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookUpdate"}}}}},
    "responses":{"Error":{"description":"Ошибка","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Требуется действующий Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Недостаточно scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"MethodNotAllowed":{"description":"Метод не поддерживается; допустимые методы перечислены в Allow","headers":{"Allow":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnsupportedMediaType":{"description":"Изменяющий запрос должен использовать application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PreconditionRequired":{"description":"Не передан If-Match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}
  },
  "paths":{
    "/auth/token":{"post":{"operationId":"issueToken","security":[],"x-required-scope":"","summary":"Получить токен на 15 минут","description":"Работает только по HTTPS. Проверяет логин, пароль, Client ID, Client secret, подтверждение пользователя и его текущую роль.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["username","password","clientId","clientSecret"],"properties":{"username":{"type":"string"},"password":{"type":"string","format":"password"},"clientId":{"type":"string"},"clientSecret":{"type":"string","format":"password"}}}}}},"responses":{"200":{"description":"Токен","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Token"}}}},"401":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"426":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},
    "/me":{"get":{"operationId":"getMe","x-required-scope":"profile:read","summary":"Профиль владельца токена","responses":{"200":{"description":"Профиль","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},
    "/organizations":{"get":{"operationId":"listSiteOrganizations","x-required-scope":"site:read","summary":"Все организации сайта","description":"Только глобальное подключение владельца сайта.","responses":{"200":{"description":"Организации","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"403":{"$ref":"#/components/responses/Forbidden"}}}},
    "/organizations/{organizationId}":{"get":{"operationId":"getSiteOrganization","x-required-scope":"site:read","summary":"Организация по ID","description":"Только глобальное подключение владельца сайта.","parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Организация","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/Error"}}}},
    "/organizations/current":{"get":{"operationId":"getCurrentOrganization","x-required-scope":"organizations:read","summary":"Текущая организация","responses":{"200":{"description":"Организация","headers":{"ETag":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/Error"},"405":{"$ref":"#/components/responses/MethodNotAllowed"}}},"patch":{"operationId":"updateCurrentOrganization","x-required-scope":"organizations:write","summary":"Изменить организацию","parameters":[{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"$ref":"#/components/requestBodies/OrganizationUpdate"},"responses":{"200":{"description":"Организация","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"409":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Error"},"428":{"$ref":"#/components/responses/PreconditionRequired"}}}},
    "/organizations/current/members":{"get":{"operationId":"listMembers","x-required-scope":"members:read","summary":"Сотрудники организации","responses":{"200":{"description":"Список сотрудников","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},
    "/organizations/current/invitations":{"get":{"operationId":"listInvitations","x-required-scope":"members:read","summary":"Приглашения сотрудников","responses":{"200":{"description":"Список приглашений","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}}}},"post":{"operationId":"createInvitation","x-required-scope":"members:write","summary":"Создать одноразовое приглашение","requestBody":{"$ref":"#/components/requestBodies/InvitationCreate"},"responses":{"201":{"description":"Приглашение поставлено в очередь","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invitation"}}}},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Error"}}}},
    "/tasks":{"get":{"operationId":"listTasks","x-required-scope":"tasks:read","summary":"Задачи доступного контура","parameters":[{"name":"organizationId","in":"query","description":"Фильтр владельца сайта. Клиентское подключение всегда ограничено своей организацией.","schema":{"type":"string"}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"search","in":"query","schema":{"type":"string","maxLength":120}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"assigneeUserId","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Список задач","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}}}},"post":{"operationId":"createTask","x-required-scope":"tasks:write","summary":"Создать задачу","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"$ref":"#/components/requestBodies/TaskCreate"},"responses":{"201":{"description":"Задача","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"409":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Error"}}}},
    "/tasks/{taskId}":{"parameters":[{"$ref":"#/components/parameters/TaskId"}],"get":{"operationId":"getTask","x-required-scope":"tasks:read","summary":"Карточка задачи","responses":{"200":{"description":"Задача","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"404":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"updateTask","x-required-scope":"tasks:write","summary":"Изменить задачу","parameters":[{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"$ref":"#/components/requestBodies/TaskUpdate"},"responses":{"200":{"description":"Задача","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"409":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Error"},"428":{"$ref":"#/components/responses/PreconditionRequired"}}}},
    "/tasks/{taskId}/transitions":{"post":{"operationId":"transitionTask","x-required-scope":"tasks:status","summary":"Изменить статус по управляемой матрице переходов","parameters":[{"$ref":"#/components/parameters/TaskId"},{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"$ref":"#/components/requestBodies/TransitionCreate"},"responses":{"200":{"description":"Задача","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"409":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Error"},"428":{"$ref":"#/components/responses/PreconditionRequired"}}}},
    "/tasks/{taskId}/comments":{"parameters":[{"$ref":"#/components/parameters/TaskId"}],"get":{"operationId":"listComments","x-required-scope":"comments:read","summary":"Публичные комментарии","responses":{"200":{"description":"Комментарии","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}}}},"post":{"operationId":"createComment","x-required-scope":"comments:write","summary":"Добавить публичный комментарий","requestBody":{"$ref":"#/components/requestBodies/CommentCreate"},"responses":{"201":{"description":"Комментарий создан"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Error"}}}},
    "/tasks/{taskId}/events":{"get":{"operationId":"listTaskEvents","x-required-scope":"events:read","summary":"История задачи","parameters":[{"$ref":"#/components/parameters/TaskId"}],"responses":{"200":{"description":"События","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}}}}},
    "/tasks/{taskId}/files":{"parameters":[{"$ref":"#/components/parameters/TaskId"}],"get":{"operationId":"listTaskFiles","x-required-scope":"files:read","summary":"Публичные файлы","responses":{"200":{"description":"Файлы","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}}}},"post":{"operationId":"createTaskFile","x-required-scope":"files:write","summary":"Загрузить файл в base64","requestBody":{"$ref":"#/components/requestBodies/FileCreate"},"responses":{"201":{"description":"Файл","content":{"application/json":{"schema":{"$ref":"#/components/schemas/File"}}}},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Error"}}}},
    "/files/{fileId}/content":{"get":{"operationId":"downloadFile","x-required-scope":"files:read","summary":"Скачать файл","parameters":[{"name":"fileId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Содержимое файла","headers":{"Content-Disposition":{"schema":{"type":"string"}}},"content":{"image/png":{},"image/jpeg":{},"image/webp":{},"application/pdf":{},"text/plain":{}}},"404":{"$ref":"#/components/responses/Error"}}}},
    "/webhooks":{"get":{"operationId":"listWebhooks","x-required-scope":"webhooks:manage","summary":"Подписки на вебхуки","responses":{"200":{"description":"Список подписок","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}},"availableEvents":{"type":"array","items":{"type":"string"}}}}}}}}},"post":{"operationId":"createWebhook","x-required-scope":"webhooks:manage","summary":"Создать подписку; секрет возвращается один раз","requestBody":{"$ref":"#/components/requestBodies/WebhookCreate"},"responses":{"201":{"description":"Подписка и секрет","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Error"}}}},
    "/webhooks/{webhookId}":{"parameters":[{"name":"webhookId","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"operationId":"updateWebhook","x-required-scope":"webhooks:manage","summary":"Изменить подписку","requestBody":{"$ref":"#/components/requestBodies/WebhookUpdate"},"responses":{"200":{"description":"Подписка","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"404":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/Error"}}},"delete":{"operationId":"revokeWebhook","x-required-scope":"webhooks:manage","summary":"Отозвать подписку","responses":{"204":{"description":"Отозвано"},"404":{"$ref":"#/components/responses/Error"}}}}
  }
}