Coverse API (1.0.0)

Download OpenAPI specification:Download

Поддержка Coverse: contact@coverse.team

Публичный REST API для чтения и записи данных в таблицах Coverse.

API рассчитан на интеграции (машина-машина): создайте токен доступа в настройках аккаунта Coverse (раздел «Автоматизация и API») и обращайтесь к эндпоинтам /v1. Значения читаются из заранее вычисленного снимка, поэтому при чтении формулы уже посчитаны; запись проходит через движок таблиц, так что отправленные формулы пересчитываются на сервере.

Как устроены значения ячеек (важно при построении интеграций):

Каждая ячейка возвращается как { v, m, f? }. v — исходное значение, m — строка в том виде, в каком её видит пользователь, f — формула (только у формульных ячеек). Пустая ячейка возвращается как null.
Числа в v используют точку как десятичный разделитель. Строка m следует локали документа (в русском документе число может выглядеть как 1 234,50).
Даты хранятся в v как серийные номера (число дней от эпохи таблицы), а в m — как отформатированная строка.
При записи формул используйте английские имена функций, ; как разделитель аргументов и , как десятичный разделитель, например =SUM(A1;B1), =ROUND(3,14159;2).

Документы

Список документов и доступ к отдельному документу.

Список документов

Возвращает документы, доступные владельцу токена. Требуется право sheets.read. В список попадает каждый документ, который пользователь может открыть; доступ проверяется по каждому документу теми же правами, что и в приложении.

Authorizations:

bearerAuth

query Parameters

type	string Examples: type=table Фильтр по типу документа, например `table`.

Responses

Request samples

cURL
JavaScript
Python

curl "https://app.coverse.team/v1/documents?type=table" \
  -H "Authorization: Bearer $TOKEN"

Response samples

200
401
403
429

Content type

application/json

{"documents": [{"id": "3f2b9c10-8a4e-4f21-9b7d-2c5e6a1f0d34",
"type": "table",
"title": "Заявки",
"revisionId": "121",
"createdAt": "2026-06-01T10:00:00+00:00",
"updatedAt": "2026-07-09T09:15:14+00:00",
"content": {"contentUrl": "https://storage.coverse.team/…/content.json",
"stylesUrl": "https://storage.coverse.team/…/styles.json"
}
}
]
}

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

Возвращает один документ по идентификатору. Требуется право sheets.read и доступ на просмотр документа.

Authorizations:

bearerAuth

path Parameters

document

required

string <uuid>

Идентификатор документа (UUID).

Responses

Request samples

cURL
JavaScript
Python

curl "https://app.coverse.team/v1/documents/$DOCUMENT_ID" \
  -H "Authorization: Bearer $TOKEN"

Response samples

200
401
403
404

Content type

application/json

{"document": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"type": "table",
"title": "string",
"revisionId": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"content": {"contentUrl": "string",
"stylesUrl": "string"
}
}
}

Значения

Чтение и запись значений ячеек в таблице.

Прочитать диапазон

Читает значения из одного диапазона в A1-нотации. Требуется право sheets.read.

Сегмент пути {range} может содержать имя листа и разделитель диапазона :, поэтому его нужно URL-кодировать (например Sheet1!A1:C10 превращается в Sheet1%21A1%3AC10). Поддерживаются открытые диапазоны: A:A (весь столбец), 1:1 (вся строка), A1:A (открытый снизу). Результат разбивается на страницы и ограничен серверным лимитом строк.

Authorizations:

bearerAuth

path Parameters

document required	string <uuid> Идентификатор документа (UUID).
range required	string Диапазон в A1-нотации, URL-кодированный. Примеры: `A1`, `A1:C10`, `Sheet1!A1:C10`, `'Мой лист'!B2`, открытые диапазоны `A:A`, `1:1`, `A1:A`.

query Parameters

offset	integer >= 0 Default: 0 Смещение по строкам внутри разрешённого диапазона (от 0).
limit	integer >= 1 Максимальное число строк в ответе. Ограничивается серверным максимумом (1000). Если не указан, сервер возвращает до максимума и выставляет `hasMore`, когда есть ещё строки.

Responses

Request samples

cURL
JavaScript
Python

curl "https://app.coverse.team/v1/documents/$DOCUMENT_ID/values/A1:B10" \
  -H "Authorization: Bearer $TOKEN"

Response samples

200
401
403
404
422

Content type

application/json

{"values": {"sheet": "Лист 1",
"range": "A1:B2",
"majorDimension": "ROWS",
"cells": [[{"v": "Имя",
"m": "Имя"
},
{"v": "Сумма",
"m": "Сумма"
}
],
[{"v": "Заявка №1",
"m": "Заявка №1"
},
{"v": 3456,
"m": "3 456"
}
]
],
"pagination": {"offset": 0,
"limit": 1000,
"total": 2,
"returned": 2,
"hasMore": false,
"nextOffset": null
}
}
}

Записать диапазон

Записывает блок значений, где верхняя-левая ячейка диапазона — точка привязки. Требуется право sheets.write и доступ на редактирование. При USER_ENTERED (по умолчанию) ведущий = считается формулой и движок пересчитывает; при RAW всё записывается как есть.

Authorizations:

bearerAuth

path Parameters

document required	string <uuid> Идентификатор документа (UUID).
range required	string Диапазон в A1-нотации, URL-кодированный. Примеры: `A1`, `A1:C10`, `Sheet1!A1:C10`, `'Мой лист'!B2`, открытые диапазоны `A:A`, `1:1`, `A1:A`.

header Parameters

Idempotency-Key

string

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

Request Body schema: application/json
required

values required	Array of strings or numbers or booleans or null (ValueMatrix) non-empty [ items ] Матрица значений для записи, по строкам. Каждый вложенный массив — строка. При `USER_ENTERED` ведущий `=` в строке считается формулой.
valueInputOption	string (ValueInputOption) Enum: "RAW" "USER_ENTERED" `USER_ENTERED` разбирает ввод как при наборе пользователем (формулы, распознавание чисел и дат). `RAW` записывает значения как есть.

Responses

Request samples

Payload
cURL
JavaScript
Python

Content type

application/json

{"values": [["Заявка №2",
"=B2+100"
]
],
"valueInputOption": "USER_ENTERED"
}

Response samples

200
401
403
404
422

Content type

application/json

{"updated": {"sheet": "Лист 1",
"cells": 2
}
}

Прочитать несколько диапазонов

Читает несколько диапазонов A1 за один запрос. Требуется право sheets.read. Некорректный диапазон или отсутствующий лист даёт запись с полем error, а не роняет весь запрос. Не более 20 диапазонов.

Authorizations:

bearerAuth

path Parameters

document

required

string <uuid>

Идентификатор документа (UUID).

query Parameters

ranges

required

Array of strings [ 1 .. 20 ] items

По одной записи на диапазон, например ranges[]=A1:B2&ranges[]=Sheet2!C1:C10.

Responses

Request samples

cURL
JavaScript
Python

curl "https://app.coverse.team/v1/documents/$DOCUMENT_ID/values/batchGet?ranges[]=A1:B2&ranges[]=D1:D5" \
  -H "Authorization: Bearer $TOKEN"

Response samples

200
401
403
422

Content type

application/json

{"valueRanges": [{"sheet": "Лист 1",
"range": "A1:A2",
"majorDimension": "ROWS",
"cells": [[{"v": "Имя",
"m": "Имя"
}
],
[{"v": "Заявка №1",
"m": "Заявка №1"
}
]
],
"pagination": {"offset": 0,
"limit": 1000,
"total": 2,
"returned": 2,
"hasMore": false,
"nextOffset": null
}
},
{"range": "Лист 5!A1",
"error": "Sheet not found"
}
]
}

Записать несколько диапазонов атомарно

Записывает несколько диапазонов одной атомарной операцией. Требуется право sheets.write. Все диапазоны применяются за один прогон движка и одну транзакцию; если хотя бы один диапазон некорректен — весь запрос отклоняется и ничего не записывается.

Authorizations:

bearerAuth

path Parameters

document

required

string <uuid>

Идентификатор документа (UUID).

header Parameters

Idempotency-Key

string

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

Request Body schema: application/json
required

required	Array of objects non-empty
valueInputOption	string (ValueInputOption) Enum: "RAW" "USER_ENTERED" `USER_ENTERED` разбирает ввод как при наборе пользователем (формулы, распознавание чисел и дат). `RAW` записывает значения как есть.

Responses

Request samples

Payload
cURL
JavaScript
Python

Content type

application/json

{"data": [{"range": "Лист 1!A2",
"values": [["Заявка №1",
3456
]
]
},
{"range": "Лист 1!D1",
"values": [["Статус"
]
]
}
],
"valueInputOption": "USER_ENTERED"
}

Response samples

200
401
403
404
422

Content type

application/json

{"updated": {"ranges": ["Лист 1!A2:B2",
"Лист 1!D1"
],
"cells": 3
}
}

Дописать строки

Добавляет строки после последней заполненной строки листа. Требуется право sheets.write. Начальный столбец берётся из range; начальная строка — последняя заполненная плюс один.

Authorizations:

bearerAuth

path Parameters

document

required

string <uuid>

Идентификатор документа (UUID).

header Parameters

Idempotency-Key

string

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

Request Body schema: application/json
required

range required	string
values required	Array of strings or numbers or booleans or null (ValueMatrix) non-empty [ items ] Матрица значений для записи, по строкам. Каждый вложенный массив — строка. При `USER_ENTERED` ведущий `=` в строке считается формулой.
valueInputOption	string (ValueInputOption) Enum: "RAW" "USER_ENTERED" `USER_ENTERED` разбирает ввод как при наборе пользователем (формулы, распознавание чисел и дат). `RAW` записывает значения как есть.

Responses

Request samples

Payload
cURL
JavaScript
Python

Content type

application/json

{"range": "Лист 1!A1",
"values": [["Заявка №3",
780
],
["Заявка №4",
1290
]
]
}

Response samples

200
401
403
404
422

Content type

application/json

{"updated": {"sheet": "Лист 1",
"startRow": 6,
"cells": 4
}
}

Очистить диапазон

Очищает заполненные ячейки в диапазоне. Требуется право sheets.write. Удаляются только заполненные ячейки; открытые диапазоны разрешаются по размеру листа.

Authorizations:

bearerAuth

path Parameters

document

required

string <uuid>

Идентификатор документа (UUID).

header Parameters

Idempotency-Key

string

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

Request Body schema: application/json
required

range

required

string

Responses

Request samples

Payload
cURL
JavaScript
Python

Content type

application/json

{"range": "Лист 1!A2:B100"
}

Response samples

200
401
403
404
422

Content type

application/json

{"updated": {"sheet": "Лист 1",
"cells": 8
}
}

Листы

Список и управление листами (вкладками) внутри таблицы.

Список листов

Возвращает листы (вкладки) таблицы. Требуется право sheets.read.

Authorizations:

bearerAuth

path Parameters

document

required

string <uuid>

Идентификатор документа (UUID).

Responses

Request samples

cURL
JavaScript
Python

curl "https://app.coverse.team/v1/documents/$DOCUMENT_ID/sheets" \
  -H "Authorization: Bearer $TOKEN"

Response samples

200
401
403
422

Content type

application/json

{"sheets": [{"sheetId": "0",
"uid": "8a4e4f21-9b7d-2c5e-6a1f-0d343f2b9c10",
"name": "Лист 1",
"hidden": false,
"order": 0,
"color": null
}
]
}

Создать лист

Создаёт новый лист. Требуется право sheets.write. Имя необязательно; если не указано — назначается имя по умолчанию.

Authorizations:

bearerAuth

path Parameters

document

required

string <uuid>

Идентификатор документа (UUID).

header Parameters

Idempotency-Key

string

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

Request Body schema: application/json
optional

name	string <= 255 characters

Responses

Request samples

Payload
cURL
JavaScript
Python

Content type

application/json

{"name": "string"
}

Response samples

201
401
403
422

Content type

application/json

{"sheet": {"sheetId": "string",
"uid": "string",
"name": "string",
"hidden": true,
"order": 0,
"color": "string"
}
}

Переименовать лист

Переименовывает лист. Требуется право sheets.write.

Authorizations:

bearerAuth

path Parameters

document required	string <uuid> Идентификатор документа (UUID).
sheet required	string Идентификатор листа, как его возвращают эндпоинты листов (`sheetId`).

Request Body schema: application/json
required

name

required

string <= 255 characters

Responses

Request samples

Payload
cURL
JavaScript
Python

Content type

application/json

{"name": "string"
}

Response samples

200
401
403
404
422

Content type

application/json

{"sheet": {"sheetId": "string",
"uid": "string",
"name": "string",
"hidden": true,
"order": 0,
"color": "string"
}
}

Удалить лист

Удаляет лист. Требуется право sheets.write.

Authorizations:

bearerAuth

path Parameters

document required	string <uuid> Идентификатор документа (UUID).
sheet required	string Идентификатор листа, как его возвращают эндпоинты листов (`sheetId`).

Responses

Request samples

cURL
JavaScript
Python

curl -X DELETE "https://app.coverse.team/v1/documents/$DOCUMENT_ID/sheets/$SHEET_ID" \
  -H "Authorization: Bearer $TOKEN"

Response samples

200
401
403
404
422

Content type

application/json

{"deleted": {"sheetId": "string",
"uid": "string",
"name": "string",
"hidden": true,
"order": 0,
"color": "string"
}
}

Вебхуки

Подписка на уведомления об изменениях документа.

Уведомление об изменении документа Webhook

Это исходящий запрос, который Coverse отправляет на url вашей http-подписки при изменении документа. Настраивается через POST /documents/{document}/webhooks.

Доставка сгруппирована (дебаунс): близкие по времени правки объединяются в одно уведомление на документ. Тело содержит изменённые ячейки на момент доставки. Ваш обработчик должен ответить кодом 2xx, иначе доставка считается неуспешной и повторяется с задержкой.

Проверка подписи (обязательно для безопасности). В заголовке X-Coverse-Signature приходит sha256=<hex>, где <hex> — это HMAC-SHA256 от сырого тела запроса с ключом, равным секрету подписи (secret, выданному один раз при создании подписки). Сравнивайте подпись по сырым байтам тела, до любого разбора JSON. Пример на PHP: hash_hmac('sha256', $rawBody, $secret).

Authorizations:

bearerAuth

header Parameters

X-Coverse-Event	string Имя события, например `document.updated`.
X-Coverse-Signature	string Подпись тела: `sha256=<hex HMAC-SHA256(secret, rawBody)>`.
X-Coverse-Timestamp	string <date-time> Момент доставки в формате ISO 8601 (защита от повторной отправки).

Request Body schema: application/json

Тело уведомления.

schemaVersion	string Версия схемы payload.
event	string
source	string Enum: "api" "browser" Откуда пришло изменение — через API или из браузера.
sourceToken	string or null Имя токена-интеграции для изменений через API; для браузера — null.
documentId	string or null <uuid>
documentTitle	string or null
documentUrl	string or null Прямая ссылка на документ.
	object or null
	object Диапазон ревизий, охваченных этим уведомлением.
changedAt	string or null <date-time>
	Array of objects
cellCount	integer Общее число изменённых ячеек (даже если часть не вошла в `cells`).
changes	string Готовая строка-сводка всех включённых ячеек, например `Лист 1!E21 = 3456; …` — удобно для no-code инструментов.
ranges	Array of strings Изменённые ячейки, схлопнутые в горизонтальные диапазоны A1.
	Array of objects
truncated	boolean `true`, если ячеек больше лимита payload — тогда `cells` обрезан, а `cellCount` показывает полное число.
deliveryId	string <uuid> Идентификатор доставки, стабилен при повторах.
attempt	integer Номер попытки доставки (растёт при повторах).
deliveredAt	string or null <date-time>

Responses

Request samples

Payload

Content type

application/json

{"schemaVersion": "1.0",
"event": "document.updated",
"source": "api",
"sourceToken": "Интеграция с CRM",
"documentId": "3f2b9c10-8a4e-4f21-9b7d-2c5e6a1f0d34",
"documentTitle": "Заявки",
"documentUrl": "https://app.coverse.team/files/document/3f2b9c10-8a4e-4f21-9b7d-2c5e6a1f0d34",
"workspace": {"id": 42,
"name": "Отдел продаж"
},
"revision": {"from": 118,
"to": 121
},
"changedAt": "2026-07-09T09:15:04+00:00",
"authors": [{"id": 7,
"name": "Павел Власов"
}
],
"cellCount": 2,
"changes": "Лист 1!E21 = 3456; Лист 1!F21 = Новый",
"ranges": ["Лист 1!E21:F21"
],
"cells": [{"sheet": "0",
"sheetName": "Лист 1",
"ref": "E21",
"row": 20,
"col": 4,
"v": 3456,
"m": "3456",
"f": null,
"t": "number"
},
{"sheet": "0",
"sheetName": "Лист 1",
"ref": "F21",
"row": 20,
"col": 5,
"v": "Новый",
"m": "Новый",
"f": null,
"t": "string"
}
],
"truncated": false,
"deliveryId": "9a1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e",
"attempt": 1,
"deliveredAt": "2026-07-09T09:15:14+00:00"
}

Список вебхуков

Возвращает подписки-вебхуки документа. Требуется право sheets.webhooks.

Authorizations:

bearerAuth

path Parameters

document

required

string <uuid>

Идентификатор документа (UUID).

Responses

Request samples

cURL
JavaScript
Python

curl "https://app.coverse.team/v1/documents/$DOCUMENT_ID/webhooks" \
  -H "Authorization: Bearer $TOKEN"

Response samples

200
401
403

Content type

application/json

{"webhooks": [{"id": 0,
"channel": "http",
"events": ["string"
],
"active": true,
"createdAt": "2019-08-24T14:15:22Z",
"url": "string",
"token": "string",
"chatId": "string"
}
]
}

Создать вебхук

Создаёт подписку-вебхук. Требуется право sheets.webhooks. Для канала http в ответе один раз возвращается секрет подписи — больше он не показывается. Для канала telegram вместо url укажите botToken и chatId.

Authorizations:

bearerAuth

path Parameters

document

required

string <uuid>

Идентификатор документа (UUID).

Request Body schema: application/json
required

channel	string Default: "http" Enum: "http" "telegram"
url	string <uri> <= 2048 characters Обязателен для канала `http`.
botToken	string <= 255 characters Обязателен для канала `telegram`.
chatId	string <= 64 characters Обязателен для канала `telegram`.
events	Array of strings non-empty Items Value: "document.updated"

Responses

Request samples

Payload
cURL
JavaScript
Python

Content type

application/json

Example

Канал http

{"channel": "http",
"url": "https://example.com/hooks/coverse"
}

Response samples

201
401
403
422

Content type

application/json

{"webhook": {"id": 15,
"channel": "http",
"events": ["document.updated"
],
"active": true,
"createdAt": "2026-07-09T09:20:00+00:00",
"url": "https://example.com/hooks/coverse",
"token": "Интеграция с CRM"
},
"secret": "whsec_8f3a9b2c1d4e5f6a7b8c9d0e1f2a3b4c"
}

Удалить вебхук

Удаляет подписку-вебхук. Требуется право sheets.webhooks.

Authorizations:

bearerAuth

path Parameters

document required	string <uuid> Идентификатор документа (UUID).
webhook required	integer Числовой идентификатор подписки-вебхука.

Responses

Request samples

cURL
JavaScript
Python

curl -X DELETE "https://app.coverse.team/v1/documents/$DOCUMENT_ID/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $TOKEN"

Response samples

200
401
403
404

Content type

application/json

{"success": true
}

Аудит

Журнал изменений, сделанных через API.

Прочитать журнал изменений

Возвращает журнал изменений документа, сделанных через API и интеграции. Требуется право sheets.read и тариф с аудитом (Профессиональный и выше); иначе возвращается 403.

Authorizations:

bearerAuth

path Parameters

document

required

string <uuid>

Идентификатор документа (UUID).

query Parameters

offset	integer >= 0 Default: 0
limit	integer >= 1 Default: 50 Ограничивается значением 200.

Responses

Request samples

cURL
JavaScript
Python

curl "https://app.coverse.team/v1/documents/$DOCUMENT_ID/audit?limit=50" \
  -H "Authorization: Bearer $TOKEN"

Response samples

200
401
403

Content type

application/json

{"audit": {"entries": [{"id": 204,
"action": "update",
"origin": "api",
"userId": 7,
"userName": "Павел Власов",
"token": "Интеграция с CRM",
"properties": {"range": "Лист 1!A2:B2",
"cells": 2
},
"createdAt": "2026-07-09T09:15:14+00:00"
}
],
"total": 1,
"offset": 0,
"limit": 50,
"tokens": ["Интеграция с CRM"
]
}
}

Ошибки

При ошибке возвращается соответствующий HTTP-код и тело вида { "message": "..." } с пояснением.

Код	Когда возникает
`401`	Токен доступа отсутствует или недействителен.
`403`	У токена нет нужного права (scope), либо действие не разрешено тарифом (например, аудит — только на тарифе Профессиональный и выше).
`404`	Документ или лист не существует или недоступен вашему токену.
`422`	Некорректный запрос: неверный диапазон A1, документ не является таблицей, неправильное тело запроса; либо достигнут лимит вебхуков тарифа.
`429`	Превышен лимит запросов. Базовый лимит — 60 запросов в минуту на токен; тарифы могут его повышать.

При batchGet некорректный диапазон или отсутствующий лист не роняет весь запрос — в ответе для такого диапазона приходит поле error, а остальные диапазоны отдаются нормально.

Coverse API (1.0.0)

Документы

Список документов

Authorizations:

query Parameters

Responses

Request samples

Response samples

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

Authorizations:

path Parameters

Responses

Request samples

Response samples

Значения

Прочитать диапазон

Authorizations:

path Parameters

query Parameters

Responses

Request samples

Response samples

Записать диапазон

Authorizations:

path Parameters

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Прочитать несколько диапазонов

Authorizations:

path Parameters

query Parameters

Responses

Request samples

Response samples

Записать несколько диапазонов атомарно

Authorizations:

path Parameters

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Дописать строки

Authorizations:

path Parameters

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Очистить диапазон

Authorizations:

path Parameters

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Листы

Список листов

Authorizations:

path Parameters

Responses

Request samples

Response samples

Создать лист

Authorizations:

path Parameters

header Parameters

Request Body schema: application/jsonoptional

Responses

Request samples

Response samples

Переименовать лист

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
optional

Request Body schema: application/json
required

Request Body schema: application/json
required