Vue d'ensemble de l'API

L'API GitScrum fournit un accès programmatique aux données de votre workspace. Construisez des intégrations personnalisées, automatisez les flux de travail, créez des rapports, ou créez des interfaces entièrement nouvelles sur GitScrum.

Pour Commencer

URL de Base

https://services.gitscrum.com/v1

Authentification

Toutes les requêtes nécessitent une clé API dans l'en-tête :

Authorization: Bearer votre_cle_api_ici

Générer une Clé API

Allez dans Paramètres du Workspace > API
Cliquez sur "Générer une Clé API"
Nommez la clé de manière descriptive
Copiez immédiatement (affichée une seule fois)
Stockez en sécurité

Limites de Débit

Plan	Requêtes/Heure	Burst
Gratuit	1 000	100/min
Pro	10 000	500/min
Enterprise	Personnalisé	Personnalisé

En-têtes de limite de débit dans chaque réponse :

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9847
X-RateLimit-Reset: 1705320000

Format de Réponse

Toutes les réponses sont en JSON :

{
  "data": { ... },
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 150
  }
}

Réponses d'Erreur

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Tâche non trouvée",
    "details": { ... }
  }
}

Codes de Statut HTTP

Code	Signification
200	Succès
201	Créé
400	Mauvaise Requête
401	Non Autorisé
403	Interdit
404	Non Trouvé
422	Erreur de Validation
429	Limite de Débit Atteinte
500	Erreur Serveur

Endpoints Principaux

Workspaces

GET    /workspaces              # Liste de vos workspaces
GET    /workspaces/:id          # Détails du workspace
PUT    /workspaces/:id          # Modifier le workspace

Projets

GET    /workspaces/:id/projects         # Liste des projets
POST   /workspaces/:id/projects         # Créer un projet
GET    /projects/:id                     # Obtenir un projet
PUT    /projects/:id                     # Modifier un projet
DELETE /projects/:id                     # Supprimer un projet

Tâches

GET    /projects/:id/tasks      # Liste des tâches
POST   /projects/:id/tasks      # Créer une tâche
GET    /tasks/:id               # Obtenir une tâche
PUT    /tasks/:id               # Modifier une tâche
DELETE /tasks/:id               # Supprimer une tâche
PATCH  /tasks/:id/move          # Déplacer une tâche (changer le statut)

Membres de l'Équipe

GET    /workspaces/:id/members  # Liste des membres
POST   /workspaces/:id/members  # Inviter un membre
DELETE /members/:id             # Retirer un membre

Entrées de Temps

GET    /tasks/:id/time-entries  # Liste des temps pour une tâche
POST   /time-entries            # Créer une entrée de temps
PUT    /time-entries/:id        # Modifier une entrée
DELETE /time-entries/:id        # Supprimer une entrée

Sprints

GET    /projects/:id/sprints    # Liste des sprints
POST   /projects/:id/sprints    # Créer un sprint
PUT    /sprints/:id             # Modifier un sprint
POST   /sprints/:id/start       # Démarrer un sprint
POST   /sprints/:id/end         # Terminer un sprint

Paramètres de Requête

Pagination

GET /projects/:id/tasks?page=2&per_page=50

page : Numéro de page (défaut : 1)
per_page : Éléments par page (défaut : 25, max : 100)

Filtrage

GET /tasks?status=open&assignee=user_123&label=bug

Filtres courants :

status : Statut de la tâche
assignee : ID de l'utilisateur
label : Nom du label
priority : Niveau de priorité
created_after : Date ISO
created_before : Date ISO
updated_after : Date ISO

Tri

GET /tasks?sort=created_at&order=desc

sort : Champ de tri
order : asc ou desc

Inclure les Relations

GET /tasks/:id?include=comments,time_entries,attachments

Réduit les requêtes multiples en intégrant les données liées.

Webhooks

Enregistrez des webhooks pour recevoir des mises à jour en temps réel :

POST /webhooks
{
  "url": "https://votre-serveur.com/webhook",
  "events": ["task.created", "task.updated"],
  "secret": "votre_secret_de_signature"
}

Voir Vue d'ensemble des Intégrations pour les types d'événements.

Exemple : Créer une Tâche

curl -X POST https://services.gitscrum.com/v1/projects/proj_123/tasks \
  -H "Authorization: Bearer votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Implémenter la fonctionnalité de connexion",
    "description": "Ajouter le support de connexion OAuth2",
    "priority": "high",
    "labels": ["feature", "auth"],
    "assignee_id": "user_456"
  }'

Réponse :

{
  "data": {
    "id": "task_789",
    "number": 42,
    "title": "Implémenter la fonctionnalité de connexion",
    "status": "backlog",
    "priority": "high",
    "created_at": "2026-01-15T10:00:00Z",
    ...
  }
}

Exemple : Enregistrer du Temps

curl -X POST https://services.gitscrum.com/v1/time-entries \
  -H "Authorization: Bearer votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "task_789",
    "duration_minutes": 90,
    "description": "Implémentation du flux OAuth",
    "billable": true,
    "date": "2026-01-15"
  }'

Exemple : Déplacer une Tâche

curl -X PATCH https://services.gitscrum.com/v1/tasks/task_789/move \
  -H "Authorization: Bearer votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "in_progress"
  }'

SDKs et Bibliothèques

Officiels

JavaScript/TypeScript : npm install @gitscrum/sdk
Python : pip install gitscrum

Communauté

Consultez notre GitHub pour les bibliothèques maintenues par la communauté.

Spec OpenAPI

Téléchargez la spécification OpenAPI :

GET /openapi.json

Importez dans Postman, Insomnia, ou générez des clients.

Bonnes Pratiques

Utilisez la Pagination

Ne supposez jamais que vous pouvez récupérer tous les éléments. Paginez toujours.

Gérez les Limites de Débit

Vérifiez X-RateLimit-Remaining et ralentissez quand il est bas.

Mettez en Cache Quand Possible

Utilisez les en-têtes ETag pour les requêtes conditionnelles.

Opérations par Lots

Là où disponible, utilisez les endpoints par lots pour réduire les requêtes.

Sécurisez Vos Clés

Ne committez jamais les clés dans le contrôle de version
Utilisez les variables d'environnement
Faites tourner les clés périodiquement
Utilisez des clés séparées par intégration

Versioning

L'API utilise le versioning d'URL (/v1/). Les changements cassants n'interviennent que dans les nouvelles versions. Les avis de dépréciation sont fournis 6 mois à l'avance.

Support

Statut de l'API

Vérifiez le statut en temps réel : status.gitscrum.com

Changelog

Mises à jour et changements : docs.gitscrum.com/changelog

Support

Pour les problèmes d'API, incluez :

Requête/réponse (masquez les clés)
Endpoint appelé
Horodatage
Message d'erreur

Comment Signaler un Problème ou Demander une Fonctionnalité

Si vous rencontrez des problèmes d'API ou avez besoin d'endpoints supplémentaires, soumettez vos commentaires via GitScrum Studio. Dans la barre latérale, cliquez sur Tickets de Support et ouvrez un ticket.