GET/v1/folders
Получить деревья папок всех коллекций
folder_trees
Возвращает одним ответом деревья папок всех коллекций, где пользователь видит хотя бы один объект, с теми же правилами видимости, что и GET /v1/collections/{name}/folders, и в порядке GET /v1/collections. Коллекция без видимых объектов не включается. Помимо cards, у каждой папки есть итоги по поддереву: cards_total, sensitive_total и top_category. С updated_since или metadata[<key>]= поле folders каждой коллекции содержит подходящие папки плоским списком (children пуст, а parent_id указывает место в дереве). С updated_since они отсортированы по updated_at по возрастанию, затем по id; без него — в порядке sort_key. Коллекции без подходящих папок не включаются.
Аутентификация
Передайте ключ API в заголовке Authorization: Authorization: Bearer <ключ>.
Параметры запроса
limitintegerРазмер страницы. Без
limitиcursorвозвращается весь список; с ним — не большеlimitэлементов, а следующая страница указывается в заголовкахLink(rel="next") иX-Next-Cursor.≥ 1, ≤ 200
cursorstringКурсор следующей страницы из
X-Next-Cursorилиnext_cursorпредыдущего ответа с теми же фильтрами; он несёт размер страницы. Вместе сoffset—422 validation.failed; курсор другого списка, других фильтров или испорченный —400 api.cursor_invalid.length ≤ 512
updated_sincestring (date-time)Только объекты, у которых
updated_atне раньше этого момента (RFC 3339 со смещением), — для синхронизации. С этим параметром список сортируется поupdated_atпо возрастанию, затем поid, и курсор продолжает в том же порядке. Удалённые объекты в список не попадают: об удалениях сообщают события.length ≤ 512
metadatamap of stringФильтр по
metadata:metadata[<key>]=<value>— точное совпадение. До 3 условий, и выполняться должны все (?metadata[team]=support&metadata[crm_id]=A-1042). Больше 3 условий или недопустимый ключ — ответ400 api.metadata_invalid.
Ответы
200Успешный ответ
Заголовки ответа
LinkАдрес следующей страницы,
<…>; rel="next". Нет заголовка — это последняя страница.X-Next-CursorКурсор следующей страницы для параметра
cursor. Нет заголовка — это последняя страница.RateLimit-PolicyДействующие лимиты в формате черновика IETF
draft-ietf-httpapi-ratelimit-headers: элементы через запятую"<name>";q=<quota>;w=<window in seconds>.key— частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии этоuser, без учётных данных —ip);minute,dayиmonth— квоты организации на календарную минуту, день и месяц по UTC.RateLimitСколько осталось по каждому лимиту из
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitЛимит самой строгой записи в
RateLimit-Policy(той, где осталось меньше всего запросов).X-RateLimit-RemainingСколько запросов осталось в пределах самого строгого лимита.
X-RateLimit-ResetЧерез сколько секунд сбросится самый строгий лимит.
application/json
collection_idintegerобязательноcollection_namestringобязательноcollection_titlestringобязательноНазвание коллекции для показа.
permissionsarray of stringобязательноДействующие права пользователя на коллекцию.
unfiledintegerобязательноДоступные пользователю карточки коллекции, которые не лежат ни в одной папке. Архивные карточки не считаются, как и в списке карточек по умолчанию.
401Учётные данные не переданы (нет ни cookie сессии, ни ключа API) или ключ не найден.
Заголовки ответа
RateLimit-PolicyДействующие лимиты в формате черновика IETF
draft-ietf-httpapi-ratelimit-headers: элементы через запятую"<name>";q=<quota>;w=<window in seconds>.key— частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии этоuser, без учётных данных —ip);minute,dayиmonth— квоты организации на календарную минуту, день и месяц по UTC.RateLimitСколько осталось по каждому лимиту из
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitЛимит самой строгой записи в
RateLimit-Policy(той, где осталось меньше всего запросов).X-RateLimit-RemainingСколько запросов осталось в пределах самого строгого лимита.
X-RateLimit-ResetЧерез сколько секунд сбросится самый строгий лимит.
application/json
429Слишком много запросов (`api.rate_limited`), квота организации на минуту, день или месяц исчерпана (`api.quota_exceeded`; в `error.details` — `quota`, `limit` и `reset_at`), достигнут лимит организации или сервис ответов занят (`answers.engine_busy`). Подождите время, указанное в заголовке `Retry-After`.
Заголовки ответа
Retry-AfterСколько секунд подождать перед повтором запроса.
RateLimit-PolicyДействующие лимиты в формате черновика IETF
draft-ietf-httpapi-ratelimit-headers: элементы через запятую"<name>";q=<quota>;w=<window in seconds>.key— частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии этоuser, без учётных данных —ip);minute,dayиmonth— квоты организации на календарную минуту, день и месяц по UTC.RateLimitСколько осталось по каждому лимиту из
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitЛимит самой строгой записи в
RateLimit-Policy(той, где осталось меньше всего запросов).X-RateLimit-RemainingСколько запросов осталось в пределах самого строгого лимита.
X-RateLimit-ResetЧерез сколько секунд сбросится самый строгий лимит.
application/json
Коды ошибок
Коды, которые эта операция может вернуть в error.code, помимо общих кодов любого запроса.
Лимиты частоты
В ответах есть заголовки RateLimit и RateLimit-Policy, а также прежние X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset. В ответе 429 есть Retry-After в секундах: подождите и повторите запрос.