API Azure DevOps pour vos intelligences artificielles

Votre assistant IA sait lire du code, mais il ne voit pas ce qui dort dans vos dépôts Azure DevOps. Cette API fait le pont : projets, fichiers, commits, pull requests, le tout en JSON simple, avec vos propres droits d'accès.

Soyons clairs dès le départ : je l'ai conçue d'abord pour des machines. Un agent IA, un serveur MCP (le protocole qui permet à un assistant comme Claude d'appeler des outils extérieurs) ou un simple script. Les humains sont les bienvenus, mais l'idée est qu'une IA puisse demander « montre-moi ce fichier » ou « qu'est-ce qui a changé dans ce commit » sans avoir à deviner comment marche l'API d'Azure DevOps, qui est puissante mais franchement touffue.

Voilà la page Swagger du service, où tous les appels sont listés :

Gratuit ou PRO : ce que vous avez

Les deux formules donnent accès aux mêmes appels, écriture comprise. La seule différence, c'est le nombre de requêtes par jour. La barre verte montre ce que vous pouvez demander en une journée.

Le compteur repart à minuit UTC, donc à 1 h ou 2 h du matin en France selon la saison. Dix requêtes, ça part vite avec un agent bavard. Mon conseil pour les faire durer : l'appel files:batch ramène jusqu'à 50 fichiers et ne compte que pour une seule requête.

Ce que l'API sait faire

Une vingtaine d'appels, tous sous https://devops.digital3d.com/api/Devops/. Je les ai rangés par besoin plutôt que par ordre alphabétique :

Il y a aussi deux appels de service : Health, qui répond sans clé et ne compte jamais, et WhoAmI, qui confirme que vos en-têtes sont bien compris.

Les trois en-têtes à envoyer

Chaque requête porte trois en-têtes. Un pour moi, deux pour Azure DevOps.

La clé Digital3D. Créez un compte, validez votre adresse e-mail, puis copiez la clé affichée dans votre compte. C'est la même clé que pour mes autres services. Si vous utilisiez l'ancienne version, attention : l'en-tête X-Api-Key a laissé la place à Authorization.

Le nom de l'organisation. Connectez-vous sur https://dev.azure.com et regardez l'adresse. Dans https://dev.azure.com/ma-societe/, la valeur à envoyer est ma-societe. C'est le nom de l'organisation, pas celui d'un projet.

Le jeton d'accès personnel (le PAT, une sorte de mot de passe à droits limités). Dans Azure DevOps, cliquez sur l'icône des paramètres utilisateur en haut à droite, puis « Personal access tokens » et « New Token ». Donnez-lui un nom parlant, une durée courte (30 ou 90 jours), et seulement les droits utiles : « Code (Read) » et « Project and Team (Read) » suffisent pour tout lire. Ajoutez « Code (Read & Write) » uniquement si votre agent doit écrire. Copiez le jeton tout de suite, Azure DevOps ne l'affiche qu'une fois.

Un mot de prudence, parce que c'est votre code : ce jeton donne accès à vos dépôts, et il transite par mon serveur à chaque requête. Donnez-lui le minimum de droits, une date d'expiration, et révoquez-le le jour où vous n'en avez plus besoin. C'est ce que je ferais à votre place.

Premiers appels

Commencez par vérifier que les trois en-têtes passent :

curl "https://devops.digital3d.com/api/Devops/WhoAmI" \
  -H "Authorization: Bearer VotreCleApi" \
  -H "X-Ado-Org: ma-societe" \
  -H "X-Ado-Pat: VotreJetonAzure"

Ensuite, la liste des dépôts. Chaque dépôt a un identifiant (un GUID), et c'est lui que tous les autres appels attendent à la place de {repoId} :

curl "https://devops.digital3d.com/api/Devops/Repos?project=MonProjet" \
  -H "Authorization: Bearer VotreCleApi" \
  -H "X-Ado-Org: ma-societe" \
  -H "X-Ado-Pat: VotreJetonAzure"

Pour chercher tous les fichiers C# d'un dépôt, sur sa branche par défaut :

curl "https://devops.digital3d.com/api/Devops/Repos/{repoId}/search?glob=**/*.cs" \
  -H "Authorization: Bearer VotreCleApi" \
  -H "X-Ado-Org: ma-societe" \
  -H "X-Ado-Pat: VotreJetonAzure"

Et pour lire plusieurs fichiers en une seule requête, c'est un POST avec la liste des chemins :

curl -X POST "https://devops.digital3d.com/api/Devops/Repos/{repoId}/files:batch" \
  -H "Authorization: Bearer VotreCleApi" \
  -H "X-Ado-Org: ma-societe" \
  -H "X-Ado-Pat: VotreJetonAzure" \
  -H "Content-Type: application/json" \
  -d '{ "paths": ["/README.md", "/src/Program.cs"], "refName": "main" }'

Partout où une branche est attendue (refName), vous pouvez écrire main ou la forme complète refs/heads/main. Si vous ne mettez rien, c'est la branche par défaut du dépôt qui est prise.

Comparer et écrire

Là, ça devient vraiment intéressant pour un agent. Pour savoir ce qui sépare deux commits :

curl -X POST "https://devops.digital3d.com/api/Devops/Repos/{repoId}/diffs/commits" \
  -H "Authorization: Bearer VotreCleApi" \
  -H "X-Ado-Org: ma-societe" \
  -H "X-Ado-Pat: VotreJetonAzure" \
  -H "Content-Type: application/json" \
  -d '{ "baseCommit": "abc123", "targetCommit": "def456", "summaryOnly": true }'

Avec summaryOnly à true (la valeur par défaut), la réponse est un résumé compact : les totaux et les chemins des fichiers modifiés. C'est voulu. Une IA paie chaque mot qu'elle lit, alors autant ne pas lui servir la réponse brute d'Azure DevOps quand un résumé suffit.

Et pour écrire un fichier :

curl -X POST "https://devops.digital3d.com/api/Devops/Repos/{repoId}/write" \
  -H "Authorization: Bearer VotreCleApi" \
  -H "X-Ado-Org: ma-societe" \
  -H "X-Ado-Pat: VotreJetonAzure" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/docs/notes.md",
    "content": "# Notes\n\nEcrit par mon agent.",
    "branch": "feature/notes",
    "createBranch": true,
    "commitMessage": "Ajout des notes"
  }'

Bon, soyons sérieux deux minutes : laisser une IA écrire dans un dépôt, ça se fait avec des garde-fous. Trois réglages existent pour ça. createBranch crée la branche si elle n'existe pas, ce qui permet de faire travailler l'agent à l'écart et de relire son travail dans une pull request. expectHeadCommit annonce le dernier commit que l'agent a vu : si quelqu'un a poussé entre-temps, l'écriture est refusée au lieu d'écraser son travail. Et la taille du fichier écrit est plafonnée côté serveur. Et si vous ne voulez pas d'écriture du tout, le plus sûr reste un jeton en lecture seule : Azure DevOps refusera de lui-même.

Sous le capot

Quelques choix techniques qui expliquent le comportement de l'API.

C'est vous qui dites, à chaque requête, quelle organisation interroger et avec quel jeton. La même API sert donc n'importe quelle organisation Azure DevOps, et elle ne voit rien de plus que ce que votre jeton autorise.

La clé Digital3D est vérifiée en premier. Une requête est comptée dès que la clé est acceptée, quoi que réponde Azure DevOps ensuite. Un mauvais nom d'organisation ou un jeton expiré coûte donc une requête : d'où l'intérêt de valider votre configuration avec WhoAmI une bonne fois, plutôt que de tâtonner.

Deux erreurs 401 se ressemblent et n'ont pas la même cause. Celle qui porte l'en-tête WWW-Authenticate: Bearer vient de moi : la clé Digital3D est absente ou refusée, et rien n'est compté. Celle qui ne le porte pas vient d'Azure DevOps : regardez du côté de X-Ado-Org et de X-Ado-Pat.

Les réponses sont bornées pour rester digestes : 50 fichiers et environ 2 Mo par lecture groupée, 2000 entrées par défaut pour une liste de fichiers, 50 commits par défaut pour un journal. Ces plafonds se règlent avec les paramètres top et maxItems.

Suivre votre quota

Dès que la clé est acceptée, chaque réponse porte trois en-têtes : X-RateLimit-Limit (votre limite du jour), X-RateLimit-Remaining (ce qu'il vous reste) et X-RateLimit-Reset (l'heure de la remise à zéro, en secondes Unix). Un agent bien élevé lit X-RateLimit-Remaining et lève le pied avant de se cogner au mur.

• 429 : le quota du jour est épuisé. L'en-tête Retry-After donne le nombre de secondes à attendre avant la remise à zéro.
• 503 : le service n'a pas pu vérifier la clé. Ça se retente 30 secondes plus tard.
• Les autres erreurs sont un objet JSON avec un champ error qui dit ce qui ne va pas.

Tester sans écrire une ligne de code

Tout est documenté dans le Swagger de l'API. Cliquez sur « Authorize », remplissez les trois champs (la clé, l'organisation, le jeton), puis essayez chaque appel avec le bouton « Try it out ». Attention quand même : ces essais comptent dans votre quota, comme n'importe quelle requête. Ce même Swagger sert de contrat à une IA : donnez-lui l'adresse du fichier https://devops.digital3d.com/swagger/v1/swagger.json et elle découvre les appels toute seule.

Pourquoi un abonnement ?

Parce que tout ça tourne sur un serveur que je paie. Le gratuit reste là pour tester et pour un usage léger. Si un agent travaille tous les jours sur vos dépôts, l'abonnement PRO à 12 € par mois monte la limite à 1000 requêtes par jour, inclut le guide TV complet et tous mes logiciels, et c'est ce qui garde le service en vie. L'usage commercial sans abonnement n'est pas autorisé. Et s'il vous en faut davantage, écrivez-moi.