Aller au contenu
Sursa Developers

GET/v1/folders

Obtenir les arborescences de dossiers de toutes les collections

folder_trees

Renvoie, en une seule réponse, les arborescences de dossiers de toutes les collections où l’utilisateur voit au moins un objet, avec les mêmes règles de visibilité que GET /v1/collections/{name}/folders et dans l’ordre de GET /v1/collections. Une collection sans objet visible est omise. En plus de cards, chaque dossier comporte les totaux de sa sous-arborescence cards_total, sensitive_total et top_category. Avec updated_since ou metadata[<key>]=, les folders de chaque collection contiennent les dossiers correspondants sous forme de liste à plat (children est vide, et parent_id indique la place dans l’arborescence). Avec updated_since, ils sont triés par updated_at croissant, puis par id ; sans ce paramètre, dans l’ordre de sort_key. Les collections sans dossier correspondant sont omises.

Authentification

Envoyez une clé API dans l’en-tête Authorization : Authorization: Bearer <clé>.

Paramètres de requête

  • limitinteger

    Taille de page. Sans limit ni cursor, la liste entière est renvoyée ; avec ces paramètres, au plus limit éléments, et la page suivante est indiquée dans les en-têtes Link (rel="next") et X-Next-Cursor.

    ≥ 1, ≤ 200

  • cursorstring

    Curseur de la page suivante, tiré de X-Next-Cursor ou de next_cursor de la réponse précédente avec les mêmes filtres ; il porte la taille de page. Avec offset : 422 validation.failed ; curseur d’une autre liste, d’autres filtres ou mal formé : 400 api.cursor_invalid.

    length ≤ 512

  • updated_sincestring (date-time)

    Uniquement les objets dont updated_at est égal ou postérieur à ce moment (RFC 3339 avec décalage horaire), pour la synchronisation. Avec ce paramètre, la liste est triée par updated_at croissant, puis par id, et le curseur suit cet ordre. Les objets supprimés ne sont pas listés : les suppressions arrivent sous forme d’événements.

    length ≤ 512

  • metadatamap of string

    Filtre par metadata : metadata[<key>]=<value> vérifie une correspondance exacte. Jusqu’à 3 conditions, qui doivent toutes être remplies (?metadata[team]=support&metadata[crm_id]=A-1042). Plus de 3 conditions ou une clé invalide renvoient 400 api.metadata_invalid.

Réponses

200Réponse réussie

En-têtes de la réponse

  • Link

    Adresse de la page suivante, <…>; rel="next". L’absence de cet en-tête signifie qu’il s’agit de la dernière page.

  • X-Next-Cursor

    Curseur de la page suivante pour le paramètre cursor. L’absence de cet en-tête signifie qu’il s’agit de la dernière page.

  • RateLimit-Policy

    Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.

  • RateLimit

    Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).

  • X-RateLimit-Remaining

    Requêtes restantes au titre de la limite la plus stricte.

  • X-RateLimit-Reset

    Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : FolderTreeList

array of FolderTree
  • collection_idintegerobligatoire
  • collection_namestringobligatoire
  • collection_titlestringobligatoire

    Nom de la collection à afficher.

  • permissionsarray of stringobligatoire

    Permissions effectives de l’utilisateur sur la collection.

  • unfiledintegerobligatoire

    Fiches de la collection accessibles à l’utilisateur qui ne sont dans aucun dossier. Les fiches archivées ne sont pas comptées, comme dans la liste des fiches par défaut.

  • foldersarray of FolderNodeobligatoire
401Aucun identifiant n’a été envoyé (ni cookie de session ni clé API), ou la clé est introuvable.

En-têtes de la réponse

  • RateLimit-Policy

    Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.

  • RateLimit

    Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).

  • X-RateLimit-Remaining

    Requêtes restantes au titre de la limite la plus stricte.

  • X-RateLimit-Reset

    Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

429Trop de requêtes (`api.rate_limited`), quota de l’organisation pour la minute, le jour ou le mois épuisé (`api.quota_exceeded` ; `error.details` contient `quota`, `limit` et `reset_at`), limite de l’organisation atteinte, ou service de réponses occupé (`answers.engine_busy`). Attendez le délai indiqué dans l’en-tête `Retry-After`.

En-têtes de la réponse

  • Retry-After

    Nombre de secondes à attendre avant de réessayer la requête.

  • RateLimit-Policy

    Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.

  • RateLimit

    Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).

  • X-RateLimit-Remaining

    Requêtes restantes au titre de la limite la plus stricte.

  • X-RateLimit-Reset

    Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

Codes d’erreur

Codes que ce point de terminaison peut renvoyer dans error.code, en plus des codes généraux communs à toutes les requêtes.

Limites de débit

Les réponses portent les en-têtes RateLimit et RateLimit-Policy, ainsi que les anciens X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. Une réponse 429 contient Retry-After en secondes : attendez, puis réessayez.

← folders · Référence de l’API