> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retriever.run/llms.txt
> Use this file to discover all available pages before exploring further.

# API Retriever

> Lancez l'agent de prospection Retriever par API : sourcing, enrichissement et qualification de leads, tables exportables.

L'API Retriever donne accès par programme à l'agent de prospection : vous envoyez une consigne, Retriever source, enrichit et qualifie des entreprises ou des contacts, puis vous lisez ou exportez la table produite.

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Votre premier appel authentifié et une vraie liste d'entreprises en 5 minutes.
  </Card>

  <Card title="Référence API" icon="code" href="/api-reference/runs/create-run">
    Chaque endpoint, ses paramètres, ses réponses et ses erreurs.
  </Card>

  <Card title="Recettes" icon="book-open" href="/recipes/enrich-crm-list">
    Enrichir une liste CRM, synchroniser des exclusions, gérer plusieurs clients.
  </Card>

  <Card title="Erreurs" icon="triangle-exclamation" href="/concepts/errors">
    Format standard, codes stables et actions à mener.
  </Card>
</CardGroup>

## Base URL

| Environnement | Base URL                    |
| ------------- | --------------------------- |
| Production    | `https://api.retriever.run` |
| Local         | `http://localhost:4320`     |

## Authentification

Chaque requête envoie une clé API dans l'en-tête `Authorization` :

```http theme={null}
Authorization: Bearer ret_live_xxxxxxxxxxxxxxxx
```

* Créez la clé dans l'application : **Paramètres → Clés API → Créer une clé API**. Elle n'est affichée qu'une fois.
* La clé agit au nom de son créateur. Elle accède aux workspaces, tables et runs de son organisation. Les listes d'exclusion et les crédits sont ceux de l'utilisateur créateur.

<Warning>
  Gardez la clé côté serveur. Ne la mettez jamais dans un navigateur, une application mobile ou un dépôt Git.
</Warning>

## Ce que couvre l'API

| Domaine        | Rôle                                                                                   |
| -------------- | -------------------------------------------------------------------------------------- |
| **Runs**       | Confier une consigne à l'agent et récupérer ses tables ou une sortie au format imposé. |
| **Tables**     | Lire les tables vivantes d'un workspace, ligne par ligne.                              |
| **Workspaces** | Créer des workspaces et importer vos propres listes.                                   |
| **Exclusions** | Synchroniser les entreprises et les personnes à ne jamais sourcer.                     |
| **Go**         | Recherche web autonome qui renvoie une valeur conforme à votre JSON Schema.            |
| **Services**   | Appeler directement des services atomiques (recherche, scraping, email…).              |

## Conventions

* Les routes `/v1/*` sont versionnées. `/services` et `/credits` n'ont **pas** de préfixe `/v1`.
* Les requêtes `POST` avec corps envoient `Content-Type: application/json`.
* Les champs JSON sont en `snake_case`, sauf `GET /credits` (`remainingCredits`).
* Les liens renvoyés dans `links` sont relatifs à la base URL et exigent la même clé.
* Les messages d'erreur de l'API sont en anglais. Branchez votre code sur `error.code`, jamais sur `message`.