# Retriever API

- [API Retriever](https://docs.retriever.run/index.md): Lancez l'agent de prospection Retriever par API : sourcing, enrichissement et qualification de leads, tables exportables.
- [Quickstart](https://docs.retriever.run/quickstart.md): Faites votre premier appel authentifié à l'API Retriever et obtenez une liste d'entreprises en 5 minutes.
- [Runs](https://docs.retriever.run/concepts/runs.md): Cycle de vie d'un run Retriever : statuts, polling, idempotence, contrats de sortie JSON ou tables, artefacts et exports.
- [Tables](https://docs.retriever.run/concepts/tables.md): Modèle de données des tables Retriever : colonnes, valeurs, statuts de cellule, qualification, fit de ligne et import de listes.
- [Exclusions](https://docs.retriever.run/concepts/exclusions.md): Listes d'exclusion Retriever : empêcher le sourcing de proposer vos clients, concurrents ou contacts déjà engagés.
- [Erreurs](https://docs.retriever.run/concepts/errors.md): Format standard des erreurs de l'API Retriever, codes stables par statut HTTP et actions à mener.
- [Limites de débit](https://docs.retriever.run/concepts/rate-limits.md): Budgets de requêtes de l'API Retriever par clé et par classe, en-têtes RateLimit et gestion des réponses 429.
- [Pagination](https://docs.retriever.run/concepts/pagination.md): Pagination par offset et par curseur dans l'API Retriever, avec exemples de boucles en Node et Python.
- [Le client Node commun](https://docs.retriever.run/recipes/client.md): Client Node.js réutilisable pour l'API Retriever : gestion des erreurs, timeouts et retries sûrs sur 429 et 5xx.
- [Enrichir une liste de votre CRM](https://docs.retriever.run/recipes/enrich-crm-list.md): Importer des entreprises de votre CRM dans Retriever, trouver leur CEO et LinkedIn, puis exporter le résultat en CSV.
- [Synchroniser vos clients vers la liste d'exclusion](https://docs.retriever.run/recipes/sync-exclusions.md): Synchroniser automatiquement vos clients CRM vers les exclusions Retriever, sans jamais vider la liste par erreur.
- [Obtenir une table au format garanti](https://docs.retriever.run/recipes/guaranteed-table-format.md): Imposer les colonnes du résultat d'un run Retriever avec un contrat de sortie et un row_schema JSON Schema.
- [Gérer plusieurs clients (multitenant)](https://docs.retriever.run/recipes/multitenant.md): Isoler les données de plusieurs clients finaux avec l'API Retriever : une clé par organisation ou un workspace par client.
- [Rendre vos intégrations robustes](https://docs.retriever.run/recipes/robust-integrations.md): Idempotence, retries, polling économe et reprise après crash pour une intégration fiable de l'API Retriever.
- [Poursuivre un run avec une nouvelle consigne](https://docs.retriever.run/recipes/follow-up-runs.md): Continuer une conversation Retriever par API avec un nouveau run, et gérer l'erreur conversation_busy.
- [Extraire une donnée structurée avec Go](https://docs.retriever.run/recipes/structured-extraction-go.md): Obtenir une réponse web précise et typée (fondateurs, levée de fonds) avec Retriever Go et un JSON Schema.
- [Lister les runs](https://docs.retriever.run/api-reference/runs/list-runs.md)
- [Lancer un run](https://docs.retriever.run/api-reference/runs/create-run.md): Enregistre le run et répond immédiatement `202`. Suivez-le avec `GET /v1/runs/{id}`. Sans `workspace_id` ni `conversation_id`, Retriever crée un workspace et une conversation.
- [Lire l'état d'un run](https://docs.retriever.run/api-reference/runs/get-run.md): Pollez jusqu'à un statut terminal (`completed`, `failed`, `cancelled`). Respectez `Retry-After` (15 s pour un run actif). Envoyez `If-None-Match` avec l'`ETag` reçu pour obtenir `304` si rien n'a changé.
- [Demander l'annulation](https://docs.retriever.run/api-reference/runs/cancel-run.md): Marque `cancellation_requested: true`. Le worker s'arrête au prochain battement. Les modifications déjà faites dans les tables restent.
- [Lire la sortie publiée](https://docs.retriever.run/api-reference/runs/get-run-output.md): Disponible seulement si le run a été créé avec `output` et s'est terminé.
- [Métadonnées d'une table figée](https://docs.retriever.run/api-reference/runs/get-output-table.md)
- [Lignes d'une table figée](https://docs.retriever.run/api-reference/runs/list-output-table-rows.md)
- [Créer un export CSV ou JSON d'une table figée](https://docs.retriever.run/api-reference/runs/create-export.md): L'export est généré pendant la requête : la réponse `201` signifie qu'il est prêt à télécharger. Il contient les valeurs métier, sans métadonnées de cellules. En CSV, les listes d'expériences et de formations sont aplaties en texte.
- [Télécharger un export](https://docs.retriever.run/api-reference/runs/download-export.md)
- [Métadonnées d'une table vivante](https://docs.retriever.run/api-reference/tables/get-table.md)
- [Lignes d'une table vivante](https://docs.retriever.run/api-reference/tables/list-table-rows.md): Pagination par curseur. L'ordre est stable (position puis id). La table peut changer pendant la lecture (run en cours).
- [Lister les workspaces](https://docs.retriever.run/api-reference/workspaces/list-workspaces.md)
- [Créer un workspace](https://docs.retriever.run/api-reference/workspaces/create-workspace.md): Pas d'idempotence : chaque appel crée un nouveau workspace.
- [Lister les tables non archivées](https://docs.retriever.run/api-reference/workspaces/list-workspace-tables.md)
- [Importer une table (colonnes + lignes JSON)](https://docs.retriever.run/api-reference/workspaces/import-table.md): Transaction unique : une erreur annule tout l'import. Toute propriété de ligne doit correspondre à une colonne déclarée. Pas d'endpoint d'ajout de lignes à une table existante.
- [Lister une liste d'exclusion](https://docs.retriever.run/api-reference/exclusions/list-exclusions.md)
- [Ajouter des valeurs (upsert)](https://docs.retriever.run/api-reference/exclusions/add-exclusions.md): 1 000 valeurs max par appel. Renvoyer une valeur existante ne fait rien. Les valeurs invalides sont listées dans `invalid` sans faire échouer la requête.
- [Retirer des valeurs](https://docs.retriever.run/api-reference/exclusions/remove-exclusions.md)
- [Recherche structurée synchrone](https://docs.retriever.run/api-reference/go/run-sync.md): Attend le résultat. Pour les recherches de plus de ~30 s, utilisez `POST /v1/go/runs`.
- [Recherche structurée asynchrone](https://docs.retriever.run/api-reference/go/create-go-run.md)
- [État d'un job Go](https://docs.retriever.run/api-reference/go/get-go-run.md): Toujours `200` si le job existe. Un job `failed` ou `cancelled` a `ok: false` et un objet `error`. `Retry-After: 3` tant qu'il tourne.
- [Annuler un job Go](https://docs.retriever.run/api-reference/go/cancel-go-run.md): Sans effet sur un job déjà terminé (renvoie son statut).
- [Découvrir les services](https://docs.retriever.run/api-reference/services/list-services.md)
- [Décrire un service (schéma d'entrée, coût)](https://docs.retriever.run/api-reference/services/get-service.md)
- [Exécuter un service](https://docs.retriever.run/api-reference/services/execute-service.md): Lisez d'abord le schéma d'entrée avec `GET /services/{serviceName}`. Chaque appel réussi est facturé, y compris s'il est rejoué après un timeout : ne le réessayez pas automatiquement.
- [Solde de crédits](https://docs.retriever.run/api-reference/credits/get-credits.md)

## OpenAPI Specs

- [openapi](/openapi.yaml)