API REST v1

Référence des endpoints publics de l'API gitrust v1. Pour tester interactivement, accède à l'interface Swagger de ton instance sur /api/docs.

Authentification

L'API accepte deux méthodes d'authentification :

JWT Bearer (session web)

Obtenu via POST /api/v1/auth/login. Durée de vie courte, renouvelable via /api/v1/auth/refresh.

Authorization: Bearer <jwt_token>

Personal Access Token (PAT)

Créé dans /settings/tokens. Durée de vie configurable, révocable à tout moment.

Authorization: Bearer gr_pat_xxxx...

Les deux méthodes utilisent le même header Authorization: Bearer. gitrust détecte automatiquement le type par le préfixe du token.

Pagination

Tous les endpoints de liste supportent la pagination par curseur de page :

Paramètre	Type	Défaut	Description
`page`	int	`1`	Numéro de page (commence à 1)
`limit`	int	`20`	Résultats par page (max `100`)

Exemple :

GET /api/v1/repos/owner/repo/issues?page=2&limit=50

Les réponses paginées incluent les headers :

X-Total-Count: 142
X-Page: 2
X-Per-Page: 50

Codes de réponse

Code	Signification
`200 OK`	Succès
`201 Created`	Ressource créée
`204 No Content`	Succès sans corps de réponse
`400 Bad Request`	Paramètres invalides
`401 Unauthorized`	Token absent ou expiré
`403 Forbidden`	Authentifié mais permissions insuffisantes
`404 Not Found`	Ressource introuvable ou non accessible
`422 Unprocessable Entity`	Validation échouée (corps JSON avec détails)
`429 Too Many Requests`	Rate limit atteint

Les erreurs retournent un corps JSON :

{
  "error": "repository not found",
  "code": "REPO_NOT_FOUND"
}

Endpoints — Authentification

Méthode	Endpoint	Description
`POST`	`/api/v1/auth/login`	Connexion email + password (+ code 2FA si activé)
`POST`	`/api/v1/auth/register`	Créer un compte
`POST`	`/api/v1/auth/refresh`	Renouveler le JWT
`POST`	`/api/v1/auth/logout`	Invalider la session
`GET`	`/api/v1/auth/me`	Infos de l'utilisateur connecté (alias de `/api/v1/user`)
`POST`	`/api/v1/auth/forgot-password`	Envoyer le lien de réinitialisation
`POST`	`/api/v1/auth/reset-password`	Changer le mot de passe via token email
`POST`	`/api/v1/auth/2fa/verify`	Vérifier le code TOTP lors de la connexion

Endpoints — Utilisateur

Méthode	Endpoint	Description
`GET`	`/api/v1/user`	Profil de l'utilisateur authentifié
`GET`	`/api/v1/user/repos`	Dépôts accessibles par l'utilisateur authentifié

Exemple de réponse GET /api/v1/user :

{
  "id": 42,
  "username": "tonpseudo",
  "email": "ton@email.com",
  "avatar_url": "https://gitrust.example.com/avatars/42.png",
  "created_at": "2026-01-15T10:30:00Z"
}

Endpoints — Dépôts

Méthode	Endpoint	Description
`GET`	`/api/v1/repos/{owner}/{repo}`	Détail d'un dépôt
`GET`	`/api/v1/repos/{owner}/{repo}/branches`	Liste des branches
`GET`	`/api/v1/repos/{owner}/{repo}/tags`	Liste des tags
`GET`	`/api/v1/repos/{owner}/{repo}/commits`	Liste des commits (paginée)

Exemple de réponse GET /api/v1/repos/owner/repo :

{
  "id": 7,
  "owner": "owner",
  "name": "repo",
  "full_name": "owner/repo",
  "description": "Mon dépôt",
  "private": false,
  "default_branch": "main",
  "stars_count": 3,
  "forks_count": 0,
  "created_at": "2026-02-01T09:00:00Z",
  "updated_at": "2026-04-15T14:22:00Z"
}

Endpoints — Issues

Méthode	Endpoint	Description
`GET`	`/api/v1/repos/{owner}/{repo}/issues`	Lister les issues (filtres : `state`, `labels`, `page`, `limit`)
`POST`	`/api/v1/repos/{owner}/{repo}/issues`	Créer une issue
`GET`	`/api/v1/repos/{owner}/{repo}/issues/{num}`	Détail d'une issue
`PATCH`	`/api/v1/repos/{owner}/{repo}/issues/{num}`	Modifier une issue
`POST`	`/api/v1/repos/{owner}/{repo}/issues/{num}/comments`	Ajouter un commentaire

Exemple POST /api/v1/repos/owner/repo/issues :

{
  "title": "Bug: validation email incorrecte",
  "body": "La validation rejette les adresses avec un + dans le local-part."
}

Endpoints — Pull Requests

Méthode	Endpoint	Description
`GET`	`/api/v1/repos/{owner}/{repo}/pulls`	Lister les PRs
`POST`	`/api/v1/repos/{owner}/{repo}/pulls`	Créer une PR
`GET`	`/api/v1/repos/{owner}/{repo}/pulls/{num}`	Détail d'une PR
`POST`	`/api/v1/repos/{owner}/{repo}/pulls/{num}/merge`	Fusionner une PR
`POST`	`/api/v1/repos/{owner}/{repo}/pulls/{num}/comments`	Commenter une PR

Exemple POST /api/v1/repos/owner/repo/pulls/{num}/merge :

{
  "merge_method": "squash",
  "commit_title": "feat: améliore la validation email (#5)"
}

Valeurs merge_method : merge (merge commit), squash, rebase (fast-forward).

Endpoints — CI

Méthode	Endpoint	Description
`GET`	`/api/v1/repos/{owner}/{repo}/ci/pipelines`	Lister les pipelines
`POST`	`/api/v1/repos/{owner}/{repo}/ci/pipelines/trigger`	Déclencher un pipeline manuellement
`GET`	`/api/v1/repos/{owner}/{repo}/ci/pipelines/{id}`	Détail d'un pipeline
`GET`	`/api/v1/repos/{owner}/{repo}/ci/pipelines/{id}/logs`	Logs d'un pipeline
`GET`	`/api/v1/repos/{owner}/{repo}/ci/config`	Lire la config CI
`PUT`	`/api/v1/repos/{owner}/{repo}/ci/config`	Mettre à jour la config CI
`GET`	`/api/v1/repos/{owner}/{repo}/ci/variables`	Lister les variables CI
`POST`	`/api/v1/repos/{owner}/{repo}/ci/variables`	Créer une variable CI
`DELETE`	`/api/v1/repos/{owner}/{repo}/ci/variables/{id}`	Supprimer une variable CI

Documentation interactive

L'interface Swagger complète est disponible sur ton instance à /api/docs. Elle permet de tester chaque endpoint directement depuis le navigateur avec ton token d'authentification.

La spécification OpenAPI brute (YAML) est disponible sur /api/docs/openapi.yaml.

Voir aussi

Créer un Personal Access Token : obtenir les credentials pour l'API
Référence des notifications : événements SSE disponibles

Eric / documentation