API Azure DevOps voor je AI's

Je AI-assistent kan code lezen, maar hij ziet niet wat er in je Azure DevOps-repositories ligt te slapen. Deze API slaat de brug: projecten, bestanden, commits, pull requests, alles in eenvoudige JSON, met je eigen toegangsrechten.

Laten we meteen duidelijk zijn: ik heb hem eerst voor machines ontworpen. Een AI-agent, een MCP-server (het protocol waarmee een assistent zoals Claude externe tools kan aanroepen) of een eenvoudig script. Mensen zijn welkom, maar het idee is dat een AI kan vragen „laat me dit bestand zien” of „wat is er veranderd in deze commit” zonder te moeten raden hoe de API van Azure DevOps werkt, die krachtig maar eerlijk gezegd behoorlijk dichtbegroeid is.

Dit is de Swagger-pagina van de service, waar alle aanroepen opgesomd staan:

Gratis of PRO: dit krijg je

Beide formules geven toegang tot dezelfde aanroepen, inclusief schrijven. Het enige verschil is het aantal aanvragen per dag. De groene balk toont wat je op één dag kunt aanvragen.

De teller begint om middernacht UTC opnieuw, dus om 1 of 2 uur 's nachts in Frankrijk, afhankelijk van het seizoen. Tien aanvragen zijn snel op met een praatgrage agent. Mijn advies om ze langer te laten meegaan: de aanroep files:batch haalt tot 50 bestanden op en telt maar voor één aanvraag.

Wat de API kan

Een twintigtal aanroepen, allemaal onder https://devops.digital3d.com/api/Devops/. Ik heb ze gerangschikt op basis van behoefte in plaats van alfabetisch:

Er zijn ook twee service-aanroepen: Health, die zonder sleutel antwoordt en nooit meetelt, en WhoAmI, die bevestigt dat je headers goed begrepen worden.

De drie headers die je moet versturen

Elke aanvraag bevat drie headers. Eén voor mij, twee voor Azure DevOps.

De Digital3D-sleutel. Maak een account aan, bevestig je e-mailadres en kopieer daarna de sleutel die in je account wordt getoond. Het is dezelfde sleutel als voor mijn andere services. Als je de oude versie gebruikte, let dan op: de header X-Api-Key heeft plaatsgemaakt voor Authorization.

De naam van de organisatie. Log in op https://dev.azure.com en kijk naar het adres. In https://dev.azure.com/ma-societe/ is de waarde die je moet versturen ma-societe. Het is de naam van de organisatie, niet die van een project.

De persoonlijke toegangstoken (de PAT, een soort wachtwoord met beperkte rechten). Klik in Azure DevOps rechtsboven op het pictogram voor gebruikersinstellingen en daarna op “Personal access tokens” en “New Token”. Geef hem een duidelijke naam, een korte geldigheidsduur (30 of 90 dagen) en alleen de nodige rechten: “Code (Read)” en “Project and Team (Read)” volstaan om alles te lezen. Voeg “Code (Read & Write)” alleen toe als je agent moet schrijven. Kopieer de token meteen, Azure DevOps toont hem maar één keer.

Een waarschuwing, want het gaat om jouw code: deze token geeft toegang tot je opslagplaatsen en gaat bij elke aanvraag via mijn server. Geef hem zo weinig mogelijk rechten, een vervaldatum en trek hem in op de dag dat je hem niet meer nodig hebt. Dat zou ik doen als ik jou was.

Eerste aanroepen

Begin met controleren of de drie headers doorkomen:

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

Daarna de lijst van repositories. Elke repository heeft een identificatie (een GUID), en het is die identificatie die alle andere aanroepen verwachten in plaats van {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"

Om alle C#-bestanden van een repository te zoeken, op de standaardbranch:

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"

En om meerdere bestanden in één verzoek te lezen, is het een POST met de lijst van paden:

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" }'

Overal waar een branch verwacht wordt (refName), kun je main schrijven of de volledige vorm refs/heads/main. Als je niets invult, wordt de standaardbranch van de repository gebruikt.

Vergelijken en schrijven

Hier wordt het echt interessant voor een agent. Om te weten wat twee commits van elkaar scheidt:

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 }'

Met summaryOnly op true (de standaardwaarde), is het antwoord een compacte samenvatting: de totalen en de paden van de gewijzigde bestanden. Dat is de bedoeling. Een AI betaalt voor elk woord dat ze leest, dus kun je haar net zo goed niet het ruwe antwoord van Azure DevOps voorschotelen wanneer een samenvatting volstaat.

En om een bestand te schrijven:

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"
  }'

Goed, laten we twee minuten serieus zijn: een AI in een repository laten schrijven, dat doe je met vangnetten. Daar bestaan drie instellingen voor. createBranch maakt de branch aan als die niet bestaat, zodat je de agent apart kunt laten werken en zijn werk in een pull request kunt nalezen. expectHeadCommit vermeldt de laatste commit die de agent heeft gezien: als iemand intussen iets heeft gepusht, wordt het schrijven geweigerd in plaats van zijn werk te overschrijven. En de grootte van het geschreven bestand wordt aan de serverkant beperkt. En als je helemaal niet wilt dat er geschreven wordt, blijft een token met alleen-lezenrechten de veiligste optie: Azure DevOps zal het zelf weigeren.

Onder de motorkap

Een paar technische keuzes die het gedrag van de API verklaren.

Jij geeft bij elke aanvraag aan welke organisatie bevraagd moet worden en met welke token. Dezelfde API werkt dus met om het even welke Azure DevOps-organisatie, en ze ziet niets meer dan wat jouw token toestaat.

De Digital3D-sleutel wordt eerst gecontroleerd. Een aanvraag wordt geteld zodra de sleutel aanvaard is, ongeacht wat Azure DevOps daarna antwoordt. Een verkeerde organisatienaam of een verlopen token kost dus een aanvraag: vandaar het belang om je configuratie eenmalig met WhoAmI te valideren, in plaats van maar wat rond te proberen.

Twee 401-fouten lijken op elkaar en hebben niet dezelfde oorzaak. De fout die de header WWW-Authenticate: Bearer bevat, komt van mij: de Digital3D-sleutel ontbreekt of is geweigerd, en er wordt niets geteld. De fout die deze header niet bevat, komt van Azure DevOps: kijk naar X-Ado-Org en X-Ado-Pat.

De antwoorden worden begrensd om behapbaar te blijven: 50 bestanden en ongeveer 2 MB per groepslezing, standaard 2000 items voor een bestandslijst, standaard 50 commits voor een logboek. Deze limieten stel je in met de parameters top en maxItems.

Je quotum volgen

Zodra de sleutel wordt geaccepteerd, bevat elk antwoord drie headers: X-RateLimit-Limit (je daglimiet), X-RateLimit-Remaining (wat je nog over hebt) en X-RateLimit-Reset (het tijdstip van de reset, in Unix-seconden). Een welopgevoede agent leest X-RateLimit-Remaining en doet het rustig aan voordat hij tegen de muur knalt.

• 429 : het dagquotum is op. De header Retry-After geeft het aantal seconden dat je moet wachten vóór de reset.
• 503 : de service kon de sleutel niet controleren. Dat probeer je 30 seconden later opnieuw.
• De andere fouten zijn een JSON-object met een veld error dat zegt wat er mis is.

Testen zonder een regel code te schrijven

Alles staat gedocumenteerd in de Swagger van de API. Klik op « Authorize », vul de drie velden in (de sleutel, de organisatie, het token), en probeer vervolgens elke aanroep uit met de knop « Try it out ». Let wel: deze tests tellen mee voor je quotum, net als elke andere aanvraag. Diezelfde Swagger dient als contract voor een AI: geef die het adres van het bestand https://devops.digital3d.com/swagger/v1/swagger.json en die ontdekt de aanroepen helemaal zelf.

Waarom een abonnement?

Omdat dit allemaal draait op een server die ik betaal. De gratis versie blijft beschikbaar om te testen en voor licht gebruik. Als een agent elke dag aan je repositories werkt, verhoogt het PRO-abonnement van € 12 per maand de limiet naar 1000 aanvragen per dag, bevat het de volledige tv-gids en al mijn software, en dat is wat de service in leven houdt. Commercieel gebruik zonder abonnement is niet toegestaan. En als je meer nodig hebt, schrijf me.