Aller au contenu
Sursa Developers

POST/v1/search

Rechercher dans les collections

search

Authentification

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

Paramètres d’en-tête

  • X-View-Asstring

    Uniquement pour les clés API ayant le rôle admin. Exécute la requête avec le profil de données <profile>[:viewer|verifier|editor], par exemple employee:viewer. La clé d’installation ne peut pas utiliser cet en-tête (403).

Paramètres de cookie

  • kb_view_asstring

    Cookie du mode « View as » pour une session. POST /auth/view-as le définit et DELETE /auth/view-as le supprime.

Corps de la requête

application/json

Objet : SearchRequest

  • querystringobligatoire

    length ≥ 1

  • collectionstring

    Par défaut : "default"

  • tagsarray of string | null
  • exportstring | null
  • card_idsarray of string | null

    items ≤ 50

  • toolsboolean | null
  • qualitystring

    Équilibre entre la rapidité et la précision de la recherche qui produit le résultat : fast est plus rapide, precise plus précis. Par défaut : precise.

    Valeurs autorisées: fastprecise

Réponses

200Réponse réussie

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 : SearchResponse

  • querystringobligatoire
  • collectionstringobligatoire
  • timingsobjectobligatoire
    Champs
    • search_msintegerobligatoire
  • hitsarray of SearchHitobligatoire
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

403L’action n’est pas autorisée : le rôle est insuffisant, il n’y a pas d’accès à la collection ou à la fiche, la requête s’exécute en mode « View as », ou l’organisation est suspendue ou supprimée (`detail` est un objet avec `code: org_suspended | org_deleted`).

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

404L’objet n’existe pas ou ne vous est pas accessible. L’API ne confirme pas l’existence d’un objet à accès restreint.

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

422Erreur de validation : le corps ou les paramètres ne correspondent pas au schéma (`detail` est une liste d’erreurs de validation), ou la valeur d’un paramètre est hors des limites admises (`detail` est un message).

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.

Nouvelles tentatives sans risque

Envoyez un en-tête Idempotency-Key (par exemple un UUID) avec chaque POST et PATCH. Une nouvelle tentative avec la même clé dans les 24 heures renvoie la réponse enregistrée au lieu d’exécuter à nouveau la requête.

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.

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