Комментарии и файлы

Все методы · Ключи и права · Ошибки

Примеры ответов сокращены. Пустой массив означает допустимый результат без доступных записей, а не обязательное отсутствие данных.

Для методов с ключом действуют общие проверки: 401 — ключ не принят, 403 — не хватает scope или прав владельца, 429 — превышен лимит. Неверные параметры могут дать 400, недоступный адресный ресурс — 404. Особенности команды указаны рядом с методом. Точную причину смотрите в error.code и details: как обработать ошибку и безопасно повторить запрос.

Получить комментарии

GET /api/v1/objects/{objectId}/comments

Действие ключа: comments:read. Оно не заменяет права владельца на объекты и поля.

Внутренние комментарии доступны только при отдельном праве Private Comment.

Параметры пути: objectId. Тело: не требуется.

Пример запроса

GET /api/v1/objects/OBJECT_ID/comments HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY

Ответ и ошибки

Успех: 200. Массив комментариев.

{
  "data": [],
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

Добавить комментарий

POST /api/v1/objects/{objectId}/comments

Действие ключа: comments:write. Оно не заменяет права владельца на объекты и поля.

body — текст; visibility: public или internal. Указывайте явно: значение по умолчанию internal. Для internal нужно соответствующее право.

Параметры пути: objectId. Тело: JSON; пример ниже показывает основные поля.

Поддерживает Idempotency-Key. См. безопасные повторы.

Пример запроса

POST /api/v1/objects/OBJECT_ID/comments HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: example-operation-001

{
  "body": "Текст комментария",
  "visibility": "public"
}

Ответ и ошибки

Успех: 201. Комментарий.

{
  "data": {
    "id": "COMMENT_ID",
    "revision": 1,
    "body": "Текст комментария",
    "visibility": "public"
  },
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

JSON-тело свыше 10 MiB отклоняется с 413.

Изменить комментарий

PATCH /api/v1/comments/{commentId}

Действие ключа: comments:write. Оно не заменяет права владельца на объекты и поля.

Нужны право редактирования и ревизия комментария. visibility можно не менять.

Параметры пути: commentId. Тело: JSON; пример ниже показывает основные поля.

Пример запроса

PATCH /api/v1/comments/COMMENT_ID HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "expectedRevision": 1,
  "body": "Уточнённый текст",
  "visibility": "public"
}

Ответ и ошибки

Успех: 200. Обновлённый комментарий.

{
  "data": {
    "id": "COMMENT_ID",
    "revision": 2,
    "body": "Уточнённый текст"
  },
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

JSON-тело свыше 10 MiB отклоняется с 413.

Удалить комментарий

DELETE /api/v1/comments/{commentId}

Действие ключа: comments:write. Оно не заменяет права владельца на объекты и поля.

expectedRevision — ревизия комментария, не родительской записи.

Параметры пути: commentId. Тело: JSON; пример ниже показывает основные поля.

Пример запроса

DELETE /api/v1/comments/COMMENT_ID HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "expectedRevision": 1
}

Ответ и ошибки

Успех: 200. Архивированный комментарий.

{
  "data": {
    "id": "COMMENT_ID",
    "state": "ARCHIVED"
  },
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

JSON-тело свыше 10 MiB отклоняется с 413.

Получить вложения

GET /api/v1/objects/{objectId}/attachments

Действие ключа: files:read. Оно не заменяет права владельца на объекты и поля.

Список обычных вложений, без встроенных изображений rich-text/отчёта о решении.

Параметры пути: objectId. Тело: не требуется.

Пример запроса

GET /api/v1/objects/OBJECT_ID/attachments HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY

Ответ и ошибки

Успех: 200. Массив метаданных файлов.

{
  "data": [],
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

Загрузить вложение

POST /api/v1/objects/{objectId}/attachments

Действие ключа: files:write. Оно не заменяет права владельца на объекты и поля.

JSON, не multipart. filename, contentBase64; mediaType необязателен. Пустой файл отвергается. Лимит JSON 10 MiB включает base64. objectId в теле, если передан, должен совпадать с URL.

Параметры пути: objectId. Тело: JSON; пример ниже показывает основные поля.

Поддерживает Idempotency-Key. См. безопасные повторы.

Пример запроса

POST /api/v1/objects/OBJECT_ID/attachments HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: example-operation-001

{
  "filename": "example.txt",
  "mediaType": "text/plain",
  "contentBase64": "SGVsbG8="
}

Ответ и ошибки

Успех: 201. Метаданные вложения.

{
  "data": {
    "id": "ATTACHMENT_ID",
    "originalFilename": "example.txt",
    "size": 5,
    "revision": 1
  },
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

JSON-тело свыше 10 MiB отклоняется с 413.

Скачать содержимое

GET /api/v1/attachments/{attachmentId}/content

Действие ключа: files:read. Оно не заменяет права владельца на объекты и поля.

Ответ — байты файла с Content-Type и Content-Disposition, без JSON envelope. Права проверяются повторно после чтения хранилища.

Параметры пути: attachmentId. Тело: не требуется.

Пример запроса

GET /api/v1/attachments/ATTACHMENT_ID/content HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY

Ответ и ошибки

Успех: 200. Двоичное тело.

Hello

Удалить вложение

DELETE /api/v1/attachments/{attachmentId}

Действие ключа: files:write. Оно не заменяет права владельца на объекты и поля.

Нужны attachment.delete и ревизия вложения. Встроенные изображения нельзя удалять этим методом.

Параметры пути: attachmentId. Тело: JSON; пример ниже показывает основные поля.

Пример запроса

DELETE /api/v1/attachments/ATTACHMENT_ID HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "expectedRevision": 1
}

Ответ и ошибки

Успех: 200. Архивированные метаданные.

{
  "data": {
    "id": "ATTACHMENT_ID",
    "state": "ARCHIVED"
  },
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

JSON-тело свыше 10 MiB отклоняется с 413.

Связанные статьи

• Обзор API
• Права доступа
• Интеграции