# Agent (/fr/api-reference/endpoint/agent)

<!-- agent-signals: reading_time_min: 3 · est_tokens: 1799 · updated: 2026-07-30 -->

> Êtes-vous un agent IA qui a besoin d'une clé API Firecrawl ? Consultez [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) pour obtenir des instructions d'intégration automatisée.

`POST /agent`

Démarrer une tâche d’agent pour l’extraction de données pilotée par un agent

## OpenAPI

```json
{
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "properties": {
            "auditMetadata": {
              "additionalProperties": false,
              "description": "Informations d’attribution de l’utilisateur incluses dans les événements de journalisation SIEM lorsque SIEM Logging est activé pour l’organisation.",
              "properties": {
                "username": {
                  "description": "Le nom d’utilisateur associé à la requête.",
                  "maxLength": 1024,
                  "type": "string"
                }
              },
              "required": [
                "username"
              ],
              "type": "object"
            },
            "maxCredits": {
              "description": "<[\n  {\n    \"key\": \"0\",\n    \"translation\": \"Nombre maximal de crédits à utiliser pour cette tâche d’agent. La valeur par défaut est de 2500 si elle n’est pas spécifiée. Les valeurs supérieures à 2 500 sont toujours facturées comme des requêtes payantes.\"\n  }\n]</>",
              "type": "number"
            },
            "model": {
              "default": "spark-1-mini",
              "description": "Le modèle à utiliser pour les tâches d’agent. spark-1-mini (par défaut) coûte 60 % de moins, tandis que spark-1-pro offre une meilleure précision pour les tâches complexes.",
              "enum": [
                "spark-1-mini",
                "spark-1-pro"
              ],
              "type": "string"
            },
            "prompt": {
              "description": "Le prompt décrivant les données à extraire",
              "maxLength": 10000,
              "type": "string"
            },
            "schema": {
              "description": "Schéma JSON facultatif pour structurer les données extraites",
              "type": "object"
            },
            "strictConstrainToURLs": {
              "description": "Si la valeur est true, l’agent ne visitera que les URL fournies dans le tableau urls",
              "type": "boolean"
            },
            "threatProtection": {
              "description": "Dérogation [Protection contre les menaces](https://docs.firecrawl.dev/features/threat-protection) au niveau de la requête. Les champs que vous fournissez remplacent les champs correspondants de la politique de votre organisation pour cette requête uniquement ; les champs omis conservent leurs valeurs définies au niveau de l'organisation. La Protection contre les menaces doit être activée pour votre équipe (fonctionnalité Enterprise) ; sinon, la requête est rejetée avec un code 403. Si votre organisation a désactivé les dérogations par requête, toute requête qui inclut cet objet est rejetée avec un code 403. Si la Protection contre les menaces est appliquée à votre équipe, `mode` ne peut pas être défini sur `off`.",
              "properties": {
                "blacklist": {
                  "description": "Domaines à toujours bloquer, sous forme de domaines simples (`example.com`) ou de motifs avec joker (`*.example.com`). Sans protocole, chemin ni port.",
                  "items": {
                    "type": "string"
                  },
                  "maxItems": 1000,
                  "type": "array"
                },
                "blockedTlds": {
                  "description": "Domaines de premier niveau à bloquer systématiquement, en minuscules et sans le point initial (par ex. `zip`).",
                  "items": {
                    "type": "string"
                  },
                  "maxItems": 1000,
                  "type": "array"
                },
                "failurePolicy": {
                  "description": "Comportement à adopter lorsque le classifieur est injoignable : `closed` bloque la requête, `open` l'autorise.",
                  "enum": [
                    "open",
                    "closed"
                  ],
                  "type": "string"
                },
                "mode": {
                  "description": "Mode d’analyse des URL pour cette requête. `normal` vérifie les URL via Google Web Risk (+2 crédits par URL analysée).",
                  "enum": [
                    "off",
                    "normal"
                  ],
                  "type": "string"
                },
                "riskScoreThreshold": {
                  "description": "Score de risque normalisé (0–100) à partir duquel une décision du classifieur bloque l’URL. Plus il est faible, plus le filtrage est strict.",
                  "example": 75,
                  "maximum": 100,
                  "minimum": 0,
                  "type": "integer"
                },
                "whitelist": {
                  "description": "Domaines à toujours autoriser, sous forme de domaines simples ou de motifs avec joker. Prend le pas sur toutes les autres règles.",
                  "items": {
                    "type": "string"
                  },
                  "maxItems": 1000,
                  "type": "array"
                }
              },
              "title": "Threat Protection Override",
              "type": "object"
            },
            "urls": {
              "description": "Liste facultative d’URL servant à limiter l’agent",
              "items": {
                "format": "uri",
                "type": "string"
              },
              "type": "array"
            }
          },
          "required": [
            "prompt"
          ],
          "type": "object"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "properties": {
              "id": {
                "format": "uuid",
                "type": "string"
              },
              "success": {
                "type": "boolean"
              }
            },
            "type": "object"
          }
        }
      },
      "description": "La tâche de l’agent a démarré avec succès"
    },
    "402": {
      "content": {
        "application/json": {
          "schema": {
            "properties": {
              "error": {
                "example": "Payment required to access this resource.",
                "type": "string"
              }
            },
            "type": "object"
          }
        }
      },
      "description": "Paiement requis"
    },
    "429": {
      "content": {
        "application/json": {
          "schema": {
            "properties": {
              "error": {
                "example": "Rate limit exceeded.",
                "type": "string"
              }
            },
            "type": "object"
          }
        }
      },
      "description": "Trop de requêtes"
    }
  }
}
```