Liens de référence

Vous associez une ou plusieurs URLs à un agent. Une tâche en arrière-plan récupère chaque page, la convertit en markdown propre, la divise en fragments, les intègre et enregistre chaque page en tant que document ordinaire de la base de connaissances. À partir de là, la récupération est identique à celle d'un PDF téléversé : une recherche locale de quelques dizaines de millisecondes, sans rien récupérer pendant l'appel. Un lien peut correspondre à une seule page ou à un site entier : en mode `site`, le crawler suit les liens internes de la page, dans les limites indiquées ci-dessous.

Envoyez une liste, pas une URL à la fois. `crawl_mode` est défini par lien, car une racine de documentation mérite d'être explorée en mode `site`, contrairement à une page de tarification. La requête retourne immédiatement avec chaque lien à l'état `queued` : un crawl de cinquante pages avec intégration ne peut pas tenir dans une requête HTTP.

curl -X POST "$BASE_URL/agents/$AGENT_ID/reference-links" \
  -H "X-API-Key: $AETHEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "links": [
      { "url": "https://docs.example.com/", "crawl_mode": "site" },
      { "url": "https://example.com/pricing", "crawl_mode": "page" }
    ]
  }'

Un crawl ne met rien à disposition de vos appelants. Chaque page stockée attend à l'état `pending_review` jusqu'à ce que vous approuviez le lien, car un scraping défectueux qui passe inaperçu compromet tous les appels futurs. L'aperçu trie les anomalies en premier plutôt que par ordre de crawl. Un candidat en attente, puis tout ce qui est en attente de révision, et au sein de chaque groupe, l'extraction la plus courte en premier, car une page revenue presque vide est le scraping défectueux le plus probable. L'approbation prend l'ensemble du lien, à l'exception des pages que vous excluez ; une page exclue est mémorisée comme rejetée et perd ses fragments, de sorte que l'index ne contient rien qui ne sera jamais servi.

# What the crawl found, anomalies first.
curl "$BASE_URL/agents/$AGENT_ID/reference-links/$LINK_ID/pages" \
  -H "X-API-Key: $AETHEX_API_KEY"

# Put them into service, minus the ones you do not want.
curl -X POST "$BASE_URL/agents/$AGENT_ID/reference-links/$LINK_ID/approve" \
  -H "X-API-Key: $AETHEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "exclude": ["doc-uuid-of-a-page-you-reject"] }'

Chaque lien est relu à intervalle fixe afin qu'une page modifiée ne devienne pas obsolète. Il n'existe pas de paramètre par lien : l'intervalle est identique pour tous les liens, ce qui signifie qu'un lien ne peut pas être fixé pour ne jamais être ré-exploré. Un passage qui trouve la page inchangée ne fait absolument rien : il ne ré-intègre pas et ne vous demande pas d'approuver quoi que ce soit à nouveau.

Un cas ne reçoit aucun des deux traitements : une ré-exploration qui revient avec une fraction du texte qu'elle avait auparavant. C'est ce à quoi ressemble un modèle cassé ou une migration de site, et remplacer un bon contenu par celui-ci serait pire que de ne rien faire. La page continue donc de servir ce qu'elle avait, et la nouvelle extraction est mise de côté en tant que candidat. L'aperçu affiche alors les deux versions : la taille avant, la taille maintenant, et le titre propre du candidat, afin que vous puissiez juger laquelle correspond à la vraie page.

{
  "id": "doc-uuid",
  "source_url": "https://docs.example.com/pricing",
  "status": "completed",
  "size_bytes": 7178,
  "chunk_count": 4,
  "candidate": {
    "at": "2026-08-31T12:19:22Z",
    "title": "Pricing",
    "size": 501,
    "previous_size": 7178
  }
}

# Accept it, and the shorter version takes over without the page
# ever leaving service.
curl -X POST \
  "$BASE_URL/agents/$AGENT_ID/reference-links/$LINK_ID/pages/$DOC_ID/accept-candidate" \
  -H "X-API-Key: $AETHEX_API_KEY"

`crawl_state` répond à une seule question : le crawl a-t-il fonctionné ? Il est écrit par un crawl et rien d'autre ; ainsi, chaque valeur qu'il peut contenir est définitive dès la fin d'un passage.

Un échec sur une page découverte n'interrompt pas le crawl : il est enregistré et le passage continue, et `last_crawl_error_detail` résume ce qui s'est passé. Un échec sur l'URL que vous avez attachée fait échouer le lien, et `last_crawl_error_code` contient l'une des valeurs suivantes.

Dix liens par agent. Un crawl en mode `site` lit jusqu'à 50 pages, sur trois niveaux de profondeur, et s'arrête après dix minutes. Une page individuelle est lue jusqu'à 5 Mo. Le robot s'identifie, respecte `robots.txt` y compris `Crawl-delay`, et effectue une requête à la fois par hôte avec une pause entre chacune. Il lit le site d'un tiers, il ne le soumet pas à un test de charge. Ces paramètres sont identiques pour tous les comptes et ne sont pas configurables.

Les liens de référence et les fichiers téléversés aboutissent au même endroit. Voir la base de connaissances pour en savoir plus sur ce qui arrive à un document une fois en service, et sur la façon dont la récupération l'utilise.