> ## Documentation Index
> Fetch the complete documentation index at: https://testhunch.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# L'API HTTP

> Envoyer des rapports et demander un classement depuis une CI qui n'est pas GitHub Actions.

L'API sert à une chose : garder l'historique d'un côté et lancer les tests de l'autre. Utile si votre
CI n'est pas GitHub Actions, ou si plusieurs dépôts partagent une même base.

```bash theme={"system"}
docker run -p 8000:8000 \
  -e TESTHUNCH_DATABASE_URL=postgresql://user@host/testhunch \
  -e TESTHUNCH_API_TOKEN=... \
  ghcr.io/amazing-source/testhunch:0.6.0
```

## Authentification

Un jeton *bearer*, lu dans `TESTHUNCH_API_TOKEN` :

```bash theme={"system"}
curl -H "Authorization: Bearer $TOKEN" https://testhunch.example.com/v1/report?repo=acme/shop
```

> [!WARNING]
>
> **Sans `TESTHUNCH_API_TOKEN`, l'API n'authentifie rien.** C'est voulu pour le développement local, et
> c'est une erreur en production. Le jeton est comparé en temps constant, mais un jeton absent ne se
> compare à rien du tout.

### Un jeton par dépôt

Le jeton de `TESTHUNCH_API_TOKEN` ouvre tous les dépôts : c'est celui de l'exploitant. Pour un
client, une CI par exemple, on frappe un jeton qui n'ouvre qu'un dépôt, depuis la machine qui a la
base :

```bash theme={"system"}
testhunch token create --repo acme/shop --label "github actions"
testhunch token list --repo acme/shop
testhunch token revoke 3
```

Le secret n'est affiché qu'à sa création ; seule son empreinte SHA-256 est conservée. **Aucune route
de l'API ne crée de jeton** : il faut la base pour en fabriquer un, donc aucune suite de requêtes,
avec n'importe quel jeton, n'en produit un nouveau ni n'élargit un existant.

Un jeton présenté sur un autre dépôt que le sien reçoit un `403`, un jeton inconnu ou révoqué un
`401`. Le raisonnement est dans l'[ADR 0022](https://github.com/amazing-source/testhunch/blob/main/docs/adr/0022-a-token-opens-one-repository.md).

## Vivacité et disponibilité

| Route | Ce qu'elle dit |
| - | - |
| `GET /healthz` | Le processus répond. Ne dit **rien** sur la base. |
| `GET /readyz` | La base répond aussi. Renvoie 503 sinon. |

Les deux sont ouvertes, sans jeton, pour qu'un orchestrateur puisse les interroger.

## Envoyer une exécution

`POST /v1/runs`, en multipart : un champ `metadata` qui contient le JSON de l'exécution, et un ou
plusieurs fichiers `reports`.

```bash theme={"system"}
curl -X POST https://testhunch.example.com/v1/runs \
  -H "Authorization: Bearer $TOKEN" \
  -F 'metadata={"repo":"acme/shop","commit_sha":"a1b2c3d"}' \
  -F reports=@junit.xml
```

`metadata` prend `repo` et `commit_sha`, tous deux obligatoires, et accepte en plus `branch`,
`base_sha` et `changes`, la liste des fichiers modifiés. Sans `changes`, le classement reste possible
mais ne sait rien du diff.

**201** quand l'exécution est enregistrée, **200** quand les mêmes rapports pour le même commit
l'étaient déjà : l'ingestion est idempotente, rejouer un job ne double pas l'historique.

Les limites sont posées et renvoient 413 : **50 rapports** par exécution au plus, **10 Mio** par
rapport. Un JSON de métadonnées invalide donne 422, un rapport illisible 400.

## Demander un classement

`POST /v1/prioritize`, avec le dépôt et les chemins modifiés :

```bash theme={"system"}
curl -X POST https://testhunch.example.com/v1/prioritize \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"repo":"acme/shop","changed_paths":["src/panier.py"],"commit_sha":"a1b2c3d","limit":20}'
```

`commit_sha` n'est pas décoratif : c'est lui qui départage les scores égaux, exactement comme en
ligne de commande. Le passer donne le même ordre que `testhunch prioritize` pour ce commit.

La réponse est un objet : `ranked`, les tests que `limit` a gardés ; `total`, combien il y en avait
en tout ; et `prediction_id`, non nul quand le serveur a gardé ce classement.

### Faire garder le classement au serveur

Avec `"record": true`, le serveur conserve le classement qu'il vient de servir, pour que le mode
fantôme puisse le comparer au run qui suivra. Il faut alors `commit_sha` : un classement qui ne dit
pas ce qu'il prédit ne se compare à rien, et sans lui la réponse est 422.

**Le client n'envoie jamais de classement.** Le serveur enregistre ce qu'il a servi, et lui seul.
Autrement, n'importe quel client pourrait enregistrer une prédiction que le serveur n'a pas faite,
et un rapport de mode fantôme ne vaut que si personne n'a pu écrire la prédiction après avoir vu le
résultat ([ADR 0023](https://github.com/amazing-source/testhunch/blob/main/docs/adr/0023-the-server-keeps-the-ranking-it-served.md)).

## Lire le rapport

`GET /v1/report?repo=acme/shop` renvoie les tests instables, lents et en échec, comme la commande du
même nom, plus le nombre d'exécutions enregistrées. Deux paramètres facultatifs : `last_runs`, le
nombre d'exécutions récentes couvertes (50 par défaut), et `limit`, le nombre de lignes par section
(10 par défaut).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.