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 у секундах: зачекайте й повторіть запит.