Référence API

Liens de référence

Attachez des URL à un agent et faites-les explorer pour les intégrer à sa base de connaissances. Chaque endpoint ici est limité à un seul agent.

URL de base: https://api.aethexai.com/api/v1
Endpoints: 9
Portées: agents:readagents:write

POST/agents/:id/reference-links

Associez une ou plusieurs URL et mettez en file d'attente leur premier crawl.

Attacher des liens de référence

Retourne immédiatement avec chaque lien crawl_state = queued : un crawl de cinquante pages avec embedding ne peut pas s'exécuter dans le cadre d'une requête HTTP, et il n'y a rien à examiner tant qu'il n'a pas été effectué. Tout ou rien. Une URL invalide rejette l'ensemble de la requête avec un message l'identifiant, plutôt que de créer les autres et de vous laisser déterminer lesquelles ont été enregistrées.

Chemin & Requête

idstringrequis
L'agent auquel appartient le lien.

Corps de la requête

linksarrayrequis
Les liens à associer. Au minimum un, au maximum dix par requête, et un agent peut en porter au maximum dix au total.
links[].urlstringrequis
Une URL http ou https. Normalisée avant d'être stockée : les paramètres de suivi et le fragment sont supprimés, l'hôte est converti en minuscules. Deux orthographes d'une même page comptent donc comme un seul lien.
links[].crawl_modestringoptionnel
page (par défaut) lit uniquement cette URL. site suit également ses liens internes, dans les limites globales de pages et de profondeur.

Erreurs

401Clé API manquante ou invalide

L'en-tête X-API-Key était absent, malformé, ou la clé a été révoquée.

Envoyez une clé active depuis votre tableau de bord.

403La clé ne dispose pas du périmètre requis

La lecture des liens nécessite agents:read ; l'attachement, l'approbation, l'acceptation et la suppression nécessitent agents:write.

Utilisez une clé disposant du périmètre requis, ou ajoutez-le à celle-ci.

404Agent introuvable

Aucun agent avec cet identifiant n'existe sur votre compte. Les agents sont limités au tenant de la clé ; un agent appartenant à un autre compte apparaît donc comme absent.

Vérifiez l'identifiant de l'agent.

409Lien déjà associé

Cet agent possède déjà un lien pour l'une de ces URL. Les URL étant normalisées au préalable, /docs et /docs?utm_source=x entrent en collision ici.

L'erreur indique les URL concernées. Supprimez-les de la requête, ou relancez le crawl du lien existant à la place.

422URL malformée

Une URL n'est pas http/https, contient des identifiants, des caractères de contrôle, ou dépasse 2048 caractères. La même requête échoue également si elle liste une même page deux fois.

Le message indique l'URL fautive. Corrigez-la et renvoyez la liste complète.

422Trop de liens

Un agent peut porter au maximum dix liens de référence, et la requête dépasserait cette limite.

Supprimez les liens dont vous n'avez plus besoin, ou répartissez les pages entre plusieurs agents.

Requête

json

curl -X POST https://api.aethexai.com/api/v1/agents/agent-uuid/reference-links \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "links": [
      { "url": "https://docs.example.com/", "crawl_mode": "site" },
      { "url": "https://example.com/pricing" }
    ]
  }'

201 Réponse

json

[
  {
    "id": "bfc29d66-6839-4056-9e6f-05d6613bd470",
    "url": "https://docs.example.com/",
    "crawl_mode": "site",
    "crawl_state": "queued",
    "last_crawl_at": null,
    "last_crawl_error_code": null,
    "last_crawl_error_detail": null,
    "next_crawl_at": "2026-08-31T12:18:07.902114Z",
    "pages": { "in_service": 0, "awaiting_review": 0, "rejected": 0, "flagged": 0 }
  },
  {
    "id": "9d2f0a71-1c4e-4a6b-9f31-2b8a5c7e0d14",
    "url": "https://example.com/pricing",
    "crawl_mode": "page",
    "crawl_state": "queued",
    "last_crawl_at": null,
    "last_crawl_error_code": null,
    "last_crawl_error_detail": null,
    "next_crawl_at": "2026-08-31T12:18:07.902114Z",
    "pages": { "in_service": 0, "awaiting_review": 0, "rejected": 0, "flagged": 0 }
  }
]

GET/agents/:id/reference-links

Tous les liens de l'agent, avec le détail de ses pages.

Lister les liens de référence

pages.flagged est le compteur à surveiller : il indique le nombre de pages contenant une extraction que le crawler a refusé de publier, recalculé à chaque lecture. crawl_state répond à une question différente, à savoir si le dernier crawl a réussi. Ainsi, une page dont l'extraction a échoué laisse le lien en état ready.

Chemin & Requête

idstringrequis
L'agent auquel appartient le lien.

Erreurs

401Clé API manquante ou invalide

L'en-tête X-API-Key était absent, malformé, ou la clé a été révoquée.

Envoyez une clé active depuis votre tableau de bord.

403La clé ne dispose pas du périmètre requis

La lecture des liens nécessite agents:read ; l'attachement, l'approbation, l'acceptation et la suppression nécessitent agents:write.

Utilisez une clé disposant du périmètre requis, ou ajoutez-le à celle-ci.

404Agent introuvable

Aucun agent avec cet identifiant n'existe sur votre compte. Les agents sont limités au tenant de la clé ; un agent appartenant à un autre compte apparaît donc comme absent.

Vérifiez l'identifiant de l'agent.

Requête

json

curl https://api.aethexai.com/api/v1/agents/agent-uuid/reference-links \
  -H "X-API-Key: YOUR_KEY"

Réponse 200

json

[
  {
    "id": "bfc29d66-6839-4056-9e6f-05d6613bd470",
    "url": "https://docs.example.com/",
    "crawl_mode": "site",
    "crawl_state": "ready",
    "last_crawl_at": "2026-08-31T12:19:22.471531Z",
    "last_crawl_error_code": null,
    "last_crawl_error_detail": null,
    "next_crawl_at": "2026-09-01T12:19:22.471531Z",
    "pages": {
      "in_service": 1,
      "awaiting_review": 0,
      "rejected": 0,
      "flagged": 1
    }
  }
]

GET/agents/:id/reference-links/:link_id

La même structure que la liste, pour un seul lien.

Récupérer un lien de référence

Utile pour interroger l'état après avoir attaché un lien ou forcé un nouveau crawl : surveillez crawl_state passer de queued à crawling.

Chemin & Requête

idstringrequis
L'agent auquel appartient le lien.
link_idstringrequis
Le lien de référence.

Erreurs

401Clé API manquante ou invalide

L'en-tête X-API-Key était absent, malformé, ou la clé a été révoquée.

Envoyez une clé active depuis votre tableau de bord.

403La clé ne dispose pas du périmètre requis

La lecture des liens nécessite agents:read ; l'attachement, l'approbation, l'acceptation et la suppression nécessitent agents:write.

Utilisez une clé disposant du périmètre requis, ou ajoutez-le à celle-ci.

404Agent introuvable

Aucun agent avec cet identifiant n'existe sur votre compte. Les agents sont limités au tenant de la clé ; un agent appartenant à un autre compte apparaît donc comme absent.

Vérifiez l'identifiant de l'agent.

404Lien de référence introuvable

Aucun lien avec cet identifiant n'est attaché à cet agent.

Listez les liens de l'agent et utilisez un identifiant issu de la réponse.

Requête

json

curl https://api.aethexai.com/api/v1/agents/agent-uuid/reference-links/link-uuid \
  -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "id": "bfc29d66-6839-4056-9e6f-05d6613bd470",
  "url": "https://docs.example.com/",
  "crawl_mode": "site",
  "crawl_state": "ready",
  "last_crawl_at": "2026-08-31T12:19:22.471531Z",
  "last_crawl_error_code": null,
  "last_crawl_error_detail": null,
  "next_crawl_at": "2026-09-01T12:19:22.471531Z",
  "pages": {
    "in_service": 1,
    "awaiting_review": 0,
    "rejected": 0,
    "flagged": 1
  }
}

GET/agents/:id/reference-links/:link_id/pages

Ce que le crawl a extrait, anomalies en premier.

Prévisualiser les pages d'un lien

Trié côté serveur afin que tous les clients voient le même ordre : les pages contenant un candidat en premier, puis celles en attente de révision, et au sein de chaque groupe la plus courte extraction en premier, car une page revenue presque vide est le scraping défaillant le plus probable. excerpt correspond aux 600 premiers caractères du markdown. candidate n'est présent que lorsqu'un nouveau crawl a mis une extraction en attente ; il indique la taille avant et après, ainsi que le titre que prendrait la nouvelle version.

Chemin & Requête

idstringrequis
L'agent auquel appartient le lien.
link_idstringrequis
Le lien de référence.

Erreurs

401Clé API manquante ou invalide

L'en-tête X-API-Key était absent, malformé, ou la clé a été révoquée.

Envoyez une clé active depuis votre tableau de bord.

403La clé ne dispose pas du périmètre requis

La lecture des liens nécessite agents:read ; l'attachement, l'approbation, l'acceptation et la suppression nécessitent agents:write.

Utilisez une clé disposant du périmètre requis, ou ajoutez-le à celle-ci.

404Agent introuvable

Aucun agent avec cet identifiant n'existe sur votre compte. Les agents sont limités au tenant de la clé ; un agent appartenant à un autre compte apparaît donc comme absent.

Vérifiez l'identifiant de l'agent.

404Lien de référence introuvable

Aucun lien avec cet identifiant n'est attaché à cet agent.

Listez les liens de l'agent et utilisez un identifiant issu de la réponse.

Requête

json

curl https://api.aethexai.com/api/v1/agents/agent-uuid/reference-links/link-uuid/pages \
  -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "link_id": "bfc29d66-6839-4056-9e6f-05d6613bd470",
  "pages": [
    {
      "id": "7db1d521-4546-4a3a-b271-9a7ab9e52ce7",
      "source_url": "https://docs.example.com/pricing",
      "title": "Pricing",
      "status": "completed",
      "size_bytes": 7178,
      "chunk_count": 4,
      "excerpt": "# Pricing\n\nEvery plan includes unlimited agents...",
      "candidate": {
        "at": "2026-08-31T12:19:22.471531Z",
        "title": "Pricing",
        "size": 501,
        "previous_size": 7178
      }
    },
    {
      "id": "44585690-6c50-4713-93e0-0205132470b1",
      "source_url": "https://docs.example.com/",
      "title": "Documentation",
      "status": "completed",
      "size_bytes": 15886,
      "chunk_count": 9,
      "excerpt": "# Documentation\n\nStart here...",
      "candidate": null
    }
  ]
}

GET/agents/:id/reference-links/:link_id/pages/:doc_id

Le texte complet d'une page, et la version retenue s'il y en a une.

Lire une page explorée

La liste des pages ne contient que des extraits ; cet endpoint renvoie la page en entier. Lorsqu'une nouvelle exploration a retenu une version réduite, candidate contient le markdown de cette version à côté de celle qui est encore servie : vous comparez ainsi deux textes plutôt que deux tailles en octets avant d'accepter ou de laisser en l'état.

Chemin & Requête

idstringrequis
L'agent auquel appartient le lien.
link_idstringrequis
Le lien de référence.
doc_idstringrequis
La page, identifiée par l'id retourné par l'endpoint de prévisualisation.

Erreurs

401Clé API manquante ou invalide

L'en-tête X-API-Key était absent, malformé, ou la clé a été révoquée.

Envoyez une clé active depuis votre tableau de bord.

403La clé ne dispose pas du périmètre requis

La lecture des liens nécessite agents:read ; l'attachement, l'approbation, l'acceptation et la suppression nécessitent agents:write.

Utilisez une clé disposant du périmètre requis, ou ajoutez-le à celle-ci.

404Agent introuvable

Aucun agent avec cet identifiant n'existe sur votre compte. Les agents sont limités au tenant de la clé ; un agent appartenant à un autre compte apparaît donc comme absent.

Vérifiez l'identifiant de l'agent.

404Lien de référence introuvable

Aucun lien avec cet identifiant n'est attaché à cet agent.

Listez les liens de l'agent et utilisez un identifiant issu de la réponse.

Requête

json

curl https://api.aethexai.com/api/v1/agents/agent-uuid/reference-links/link-uuid/pages/doc-uuid \
  -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "id": "7db1d521-4546-4a3a-b271-9a7ab9e52ce7",
  "source_url": "https://docs.example.com/pricing",
  "title": "Pricing",
  "status": "completed",
  "size_bytes": 7178,
  "chunk_count": 4,
  "content_hash": "9f2c1b7e...",
  "markdown": "# Pricing\n\nEvery plan includes unlimited agents...",
  "candidate": {
    "at": "2026-08-31T12:19:22.471531Z",
    "title": "Pricing",
    "size": 501,
    "previous_size": 7178,
    "markdown": "# Pricing\n\nContact sales."
  }
}

POST/agents/:id/reference-links/:link_id/approve

Mettre en service les pages en attente du lien, à l'exception de celles que vous excluez.

Approuver les pages d'un lien

Un seul endpoint plutôt qu'une paire approuver/rejeter : il reproduit ce que fait un réviseur — décocher puis confirmer — il s'agit d'une transaction unique, et il n'existe aucun état où la moitié du lien est en ligne. Une page exclue passe à l'état rejected et perd ses chunks, de sorte que l'index ne contient rien qui ne sera jamais servi ; la décision est mémorisée, et un nouveau crawl ultérieur ne re-propose la page que si le site l'a modifiée.

Chemin & Requête

idstringrequis
L'agent auquel appartient le lien.
link_idstringrequis
Le lien de référence.

Corps de la requête

excludearrayoptionnel
Identifiants de pages à refuser, issus de l'endpoint de prévisualisation. Omettez ce paramètre ou envoyez une liste vide pour tout approuver.

Erreurs

401Clé API manquante ou invalide

L'en-tête X-API-Key était absent, malformé, ou la clé a été révoquée.

Envoyez une clé active depuis votre tableau de bord.

403La clé ne dispose pas du périmètre requis

La lecture des liens nécessite agents:read ; l'attachement, l'approbation, l'acceptation et la suppression nécessitent agents:write.

Utilisez une clé disposant du périmètre requis, ou ajoutez-le à celle-ci.

404Agent introuvable

Aucun agent avec cet identifiant n'existe sur votre compte. Les agents sont limités au tenant de la clé ; un agent appartenant à un autre compte apparaît donc comme absent.

Vérifiez l'identifiant de l'agent.

404Lien de référence introuvable

Aucun lien avec cet identifiant n'est attaché à cet agent.

Listez les liens de l'agent et utilisez un identifiant issu de la réponse.

Requête

json

curl -X POST \
  https://api.aethexai.com/api/v1/agents/agent-uuid/reference-links/link-uuid/approve \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "exclude": ["doc-uuid-you-reject"] }'

Réponse 200

json

{
  "approved": 8,
  "rejected": 1
}

POST/agents/:id/reference-links/:link_id/pages/:doc_id/accept-candidate

Publier l'extraction qu'un nouveau crawl a mise en attente sur une page.

Accepter un candidat en attente

Un nouveau crawl qui revient avec une fraction du texte continue à servir ce qu'il avait et stocke la nouvelle extraction à part. Cet endpoint la publie : la page est re-découpée et ré-indexée, sans jamais quitter le service pendant cette opération. Il dispose de sa propre route plutôt qu'un indicateur sur approve, car approve est limité au lien et sa liste exclude signifie « refuser cette page ». Une page laissée dans la liste devrait signifier « remplacer le contenu en ligne par ce nouveau texte ». Il n'existe délibérément pas de contrepartie permettant de rejeter un candidat : la mise en attente indique que la source sert une page qui a perdu la majeure partie de son texte, ce qui reste vrai jusqu'à ce que le site change, et se résout automatiquement lorsque c'est le cas.

Chemin & Requête

idstringrequis
L'agent auquel appartient le lien.
link_idstringrequis
Le lien de référence.
doc_idstringrequis
La page, identifiée par l'id retourné par l'endpoint de prévisualisation.

Erreurs

401Clé API manquante ou invalide

L'en-tête X-API-Key était absent, malformé, ou la clé a été révoquée.

Envoyez une clé active depuis votre tableau de bord.

403La clé ne dispose pas du périmètre requis

La lecture des liens nécessite agents:read ; l'attachement, l'approbation, l'acceptation et la suppression nécessitent agents:write.

Utilisez une clé disposant du périmètre requis, ou ajoutez-le à celle-ci.

404Agent introuvable

Aucun agent avec cet identifiant n'existe sur votre compte. Les agents sont limités au tenant de la clé ; un agent appartenant à un autre compte apparaît donc comme absent.

Vérifiez l'identifiant de l'agent.

404Lien de référence introuvable

Aucun lien avec cet identifiant n'est attaché à cet agent.

Listez les liens de l'agent et utilisez un identifiant issu de la réponse.

404Page introuvable sur ce lien

Aucune page avec cet identifiant n'appartient à ce lien.

Utilisez l'identifiant fourni par l'endpoint de prévisualisation.

409Aucun élément en attente de révision

Cette page n'a pas de candidat. Soit elle n'en a jamais eu, soit un passage ultérieur l'a résolu : un nouveau crawl réussi lève la mise en attente automatiquement.

Relisez la prévisualisation : si candidate est null, il n'y a rien à publier.

Requête

json

curl -X POST \
  https://api.aethexai.com/api/v1/agents/agent-uuid/reference-links/link-uuid/pages/doc-uuid/accept-candidate \
  -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "id": "7db1d521-4546-4a3a-b271-9a7ab9e52ce7",
  "source_url": "https://docs.example.com/pricing",
  "size_bytes": 501,
  "chunk_count": 1
}

POST/agents/:id/reference-links/:link_id/recrawl

Lancer un passage immédiatement sans attendre la planification.

Forcer un nouveau crawl

Retourne le lien tel qu'il est avant l'exécution du passage. L'identifiant du job est déterministe : si un passage est déjà en file d'attente ou en cours, cette action se fusionne avec celui-ci plutôt que de lancer deux crawls sur les mêmes pages.

Chemin & Requête

idstringrequis
L'agent auquel appartient le lien.
link_idstringrequis
Le lien de référence.

Erreurs

401Clé API manquante ou invalide

L'en-tête X-API-Key était absent, malformé, ou la clé a été révoquée.

Envoyez une clé active depuis votre tableau de bord.

403La clé ne dispose pas du périmètre requis

La lecture des liens nécessite agents:read ; l'attachement, l'approbation, l'acceptation et la suppression nécessitent agents:write.

Utilisez une clé disposant du périmètre requis, ou ajoutez-le à celle-ci.

404Agent introuvable

Aucun agent avec cet identifiant n'existe sur votre compte. Les agents sont limités au tenant de la clé ; un agent appartenant à un autre compte apparaît donc comme absent.

Vérifiez l'identifiant de l'agent.

404Lien de référence introuvable

Aucun lien avec cet identifiant n'est attaché à cet agent.

Listez les liens de l'agent et utilisez un identifiant issu de la réponse.

Requête

json

curl -X POST \
  https://api.aethexai.com/api/v1/agents/agent-uuid/reference-links/link-uuid/recrawl \
  -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "id": "bfc29d66-6839-4056-9e6f-05d6613bd470",
  "url": "https://docs.example.com/",
  "crawl_mode": "site",
  "crawl_state": "ready",
  "last_crawl_at": "2026-08-31T12:19:22.471531Z",
  "last_crawl_error_code": null,
  "last_crawl_error_detail": null,
  "next_crawl_at": "2026-09-01T12:19:22.471531Z",
  "pages": {
    "in_service": 1,
    "awaiting_review": 0,
    "rejected": 0,
    "flagged": 1
  }
}

DELETE/agents/:id/reference-links/:link_id

Supprimer le lien, ses pages et leurs fragments.

Supprimer un lien de référence

Suppression en cascade : chaque document produit par le lien est supprimé avec ses vecteurs, de sorte que l'agent cesse immédiatement de répondre depuis cette source. Une page individuelle ne peut pas être supprimée via les endpoints de la base de connaissances, car le prochain crawl la recréerait. Excluez-la lors de l'approbation, ou supprimez l'intégralité du lien.

Chemin & Requête

idstringrequis
L'agent auquel appartient le lien.
link_idstringrequis
Le lien de référence.

Erreurs

401Clé API manquante ou invalide

L'en-tête X-API-Key était absent, malformé, ou la clé a été révoquée.

Envoyez une clé active depuis votre tableau de bord.

403La clé ne dispose pas du périmètre requis

La lecture des liens nécessite agents:read ; l'attachement, l'approbation, l'acceptation et la suppression nécessitent agents:write.

Utilisez une clé disposant du périmètre requis, ou ajoutez-le à celle-ci.

404Agent introuvable

Aucun agent avec cet identifiant n'existe sur votre compte. Les agents sont limités au tenant de la clé ; un agent appartenant à un autre compte apparaît donc comme absent.

Vérifiez l'identifiant de l'agent.

404Lien de référence introuvable

Aucun lien avec cet identifiant n'est attaché à cet agent.

Listez les liens de l'agent et utilisez un identifiant issu de la réponse.