> ## 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. # Lancer un run > 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. Envoyez un `Idempotency-Key` pour pouvoir rejouer la requête sans créer de doublon : même clé + même corps = même run ; même clé + corps différent = `409 idempotency_conflict`. ## OpenAPI ````yaml /openapi.yaml post /v1/runs openapi: 3.1.0 info: title: Retriever Public API version: 1.0.0 description: > API publique de Retriever : lancer l'agent de prospection (runs), lire et exporter des tables, importer des données, synchroniser des listes d'exclusion, lancer des recherches structurées (Go) et appeler des services atomiques. **Authentification** : `Authorization: Bearer ret_live_…`. Créez la clé dans l'application : Paramètres → **Clés API** → **Créer une clé API**. La clé donne accès aux ressources de l'organisation de son propriétaire. **Erreurs** : toutes les erreurs HTTP ont la forme `{ "error": { "code": "…", "message": "…", "details": … } }`. Branchez votre code sur `error.code` (stable), jamais sur `message`. **Limites de débit** : les réponses authentifiées par clé portent `RateLimit-Limit`, `RateLimit-Remaining` et `RateLimit-Reset` (secondes). Une réponse `429` porte aussi `Retry-After` (secondes). Les messages d'erreur de l'API sont en anglais. contact: name: Retriever servers: - url: https://api.retriever.run description: Production - url: http://localhost:4320 description: Serveur local security: - bearerAuth: [] tags: - name: Runs description: Agent de prospection « prompt in, table out ». Asynchrone. - name: Tables description: Lecture des tables vivantes d'un workspace. - name: Workspaces description: Créer des workspaces et importer des tables. - name: Exclusions description: Listes d'entreprises et de personnes à ne jamais sourcer. - name: Go description: Recherche web autonome et extraction structurée. - name: Services description: Services atomiques (recherche, scraping, email…). - name: Credits description: Solde de crédits. paths: /v1/runs: post: tags: - Runs summary: Lancer un run description: | 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. Envoyez un `Idempotency-Key` pour pouvoir rejouer la requête sans créer de doublon : même clé + même corps = même run ; même clé + corps différent = `409 idempotency_conflict`. operationId: createRun parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateRunRequest' examples: simple: summary: Prompt seul value: prompt: >- Trouve 30 fintechs françaises de 50 à 200 salariés avec leur CEO. frozenTable: summary: Sortie tabulaire figée value: prompt: >- Trouve le CEO et son LinkedIn pour chaque entreprise de la table tbl_001. workspace_id: ws_001 output: type: tables tables: - key: contacts responses: '202': description: Run accepté. headers: Location: schema: type: string description: Chemin du run, ex. /v1/runs/run_001. Retry-After: schema: type: integer description: Délai conseillé avant le premier poll (5 s). RateLimit-Limit: $ref: '#/components/headers/RateLimit-Limit' RateLimit-Remaining: $ref: '#/components/headers/RateLimit-Remaining' RateLimit-Reset: $ref: '#/components/headers/RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/Run' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': description: '`workspace_not_found` ou `conversation_not_found`.' content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- `idempotency_conflict` (même clé, corps différent) ou `conversation_busy` (un run est déjà actif dans cette conversation). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: conversation_busy message: This conversation already has an active run. '415': $ref: '#/components/responses/UnsupportedMediaType' '429': $ref: '#/components/responses/TooManyRequests' '503': description: >- `runs_unavailable` : stockage des runs indisponible. Réessayez plus tard. content: application/json: schema: $ref: '#/components/schemas/Error' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false schema: type: string minLength: 1 description: Identifiant unique de la demande côté client (ex. UUID). Non vide. schemas: CreateRunRequest: type: object additionalProperties: false required: - prompt properties: prompt: type: string minLength: 1 description: Consigne en langage naturel. Non vide. workspace_id: type: string description: Workspace existant. Sinon un workspace est créé. conversation_id: type: string description: Continue une conversation (nouveau run dans le même fil). output: $ref: '#/components/schemas/OutputContract' Run: type: object properties: id: type: string workspace_id: type: string conversation_id: type: string status: type: string enum: - queued - running - recovering - completed - failed - cancelled message: type: - string - 'null' description: Texte final de l'agent. artifacts: type: array description: Tables créées ou modifiées par le run (état vivant). items: type: object properties: type: const: table id: type: string name: type: string effect: type: string enum: - created - updated links: type: object properties: self: type: string rows: type: string last_heartbeat_at: type: - string - 'null' format: date-time progress: type: object properties: phase: type: - string - 'null' updated_at: type: string output: type: - object - 'null' properties: type: type: string enum: - json - tables links: type: object properties: self: type: string error: type: - object - 'null' properties: code: type: string message: type: string created_at: type: string format: date-time updated_at: type: string format: date-time started_at: type: - string - 'null' format: date-time completed_at: type: - string - 'null' format: date-time cancellation_requested: type: boolean links: type: object properties: self: type: string app: type: string description: >- Ouvre la conversation du run, et ses tables, dans l'app Retriever (session requise). example: id: run_001 workspace_id: ws_001 conversation_id: conv_001 status: completed message: J'ai créé la table Fintechs FR avec 30 entreprises. artifacts: - type: table id: tbl_001 name: Fintechs FR effect: created links: self: /v1/tables/tbl_001 rows: /v1/tables/tbl_001/rows output: null error: null cancellation_requested: false links: self: /v1/runs/run_001 app: >- https://app.retriever.so/app/workspaces/ws_001/conversations/conv_001 Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Code stable, à utiliser dans votre code. message: type: string description: Explication lisible. Peut changer. details: description: Détails optionnels (ex. liste des champs invalides). OutputContract: description: | Contrat de sortie optionnel. Sans lui, le run renvoie `message`, `artifacts` et `output: null`. oneOf: - type: object additionalProperties: false required: - type - schema properties: type: const: json schema: description: >- JSON Schema draft 7 autonome. La sortie est validée sans coercition. type: - object - boolean - type: object additionalProperties: false required: - type properties: type: const: tables tables: type: array items: type: object additionalProperties: false required: - key properties: key: type: string minLength: 1 description: Clé unique dans le contrat. row_schema: type: - object - boolean description: JSON Schema imposé à `values` de chaque ligne. headers: RateLimit-Limit: schema: type: integer description: Budget de la fenêtre. RateLimit-Remaining: schema: type: integer description: Requêtes restantes. RateLimit-Reset: schema: type: integer description: Secondes avant la remise à zéro. responses: BadRequest: description: >- `invalid_request` : JSON illisible, champ ou paramètre de requête inconnu, type incorrect, `limit` hors bornes, `Idempotency-Key` vide, contrat `output` invalide. `message` nomme chaque champ en faute, `details` les liste sous forme `{ path, message }`. Sur `POST /v1/runs`, `workspace_mismatch` : la conversation n'appartient pas au workspace fourni. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_request message: 'prompt: prompt must not be blank' details: - path: prompt message: prompt must not be blank Unauthorized: description: >- `not_authenticated` : header absent, mal formé (attendu `Bearer `), clé révoquée ou inconnue. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: not_authenticated message: A valid API key is required. UnsupportedMediaType: description: '`invalid_request` : ajoutez `Content-Type: application/json`.' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_request message: Content-Type must be application/json. TooManyRequests: description: '`rate_limited` : attendez `Retry-After` secondes puis réessayez.' headers: Retry-After: schema: type: integer RateLimit-Limit: $ref: '#/components/headers/RateLimit-Limit' RateLimit-Remaining: $ref: '#/components/headers/RateLimit-Remaining' RateLimit-Reset: $ref: '#/components/headers/RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: rate_limited message: Rate limit exceeded. Retry later. securitySchemes: bearerAuth: type: http scheme: bearer description: Clé API `ret_live_…` créée dans Settings → API keys. ````