API Missions TeamDay - Guide développeur

Vue d’ensemble

L’API Missions TeamDay vous permet de créer, gérer et déclencher des missions automatisées par programmation en utilisant des Personal Access Tokens (PAT) pour l’authentification.

URL de base : https://agent.teamday.ai/api/missions

Authentification

Toutes les requêtes API nécessitent un Personal Access Token (PAT) passé dans l’en-tête Authorization :

Authorization: Bearer YOUR_PAT_TOKEN

Obtenir votre PAT

1. Se connecter à TeamDay
2. Aller dans Paramètres → Tokens API
3. Cliquer sur Créer un nouveau token
4. Lui donner un nom descriptif (par exemple, “Automatisation CI/CD”)
5. Copier le token immédiatement - il ne sera affiché qu’une seule fois !

Démarrage rapide

Créer votre première mission

curl -X POST https://agent.teamday.ai/api/missions \
  -H "Authorization: Bearer YOUR_PAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Résumé quotidien d'\''équipe",
    "instructions": "Générer un résumé de l'\''activité d'\''hier",
    "schedule": {
      "type": "daily",
      "startDate": {"_seconds": 1738310400},
      "timeSpecs": [{"hour": 9, "minute": 0, "second": 0}]
    },
    "isActive": true
  }'

Réponse :

{
  "success": true,
  "mission": {
    "id": "mission_abc123",
    "title": "Résumé quotidien d'équipe",
    "isActive": true,
    "nextRunAt": {"_seconds": 1738483200}
  },
  "message": "Mission créée avec succès"
}

Endpoints API

1. Lister toutes les missions

Obtenir toutes les missions de votre organisation.

GET /api/missions

Exemple :

curl https://agent.teamday.ai/api/missions \
  -H "Authorization: Bearer YOUR_PAT_TOKEN"

Réponse :

{
  "success": true,
  "missions": [
    {
      "id": "mission_abc123",
      "title": "Résumé quotidien d'équipe",
      "instructions": "Générer un résumé...",
      "schedule": {...},
      "isActive": true,
      "nextRunAt": {"_seconds": 1738483200}
    }
  ]
}

---

2. Obtenir une mission par ID

Récupérer une mission spécifique.

GET /api/missions/:missionId

Exemple :

curl https://agent.teamday.ai/api/missions/mission_abc123 \
  -H "Authorization: Bearer YOUR_PAT_TOKEN"

---

3. Créer une mission

Créer une nouvelle mission automatisée.

POST /api/missions

Corps de la requête :

{
  "title": "string (requis)",
  "instructions": "string (requis)",
  "schedule": {
    "type": "daily|weekly|monthly|custom",
    "startDate": {"_seconds": number},
    "timeSpecs": [{"hour": number, "minute": number, "second": number}]
  },
  "isActive": boolean (défaut: true),
  "model": "string (optionnel)",
  "tools": ["string"] (optionnel)
}

Types de planning :

Quotidien

S’exécute chaque jour à l’heure (ou aux heures) spécifiée(s) :

{
  "type": "daily",
  "startDate": {"_seconds": 1738310400},
  "timeSpecs": [
    {"hour": 9, "minute": 0, "second": 0}
  ]
}

Hebdomadaire

S’exécute certains jours de la semaine :

{
  "type": "weekly",
  "startDate": {"_seconds": 1738310400},
  "timeSpecs": [{"hour": 9, "minute": 0}],
  "daysOfWeek": [1, 3, 5]  // Lundi, Mercredi, Vendredi (0=Dimanche)
}

Mensuel

S’exécute un jour spécifique de chaque mois :

{
  "type": "monthly",
  "startDate": {"_seconds": 1738310400},
  "timeSpecs": [{"hour": 9, "minute": 0}],
  "dayOfMonth": 1  // 1er de chaque mois
}

Personnalisé (Cron)

Utilisez des expressions cron pour une planification avancée :

{
  "type": "custom",
  "startDate": {"_seconds": 1738310400},
  "cronExpression": "0 9 * * 1-5",  // 9h, Lundi-Vendredi
  "timeSpecs": []
}

Exemple :

curl -X POST https://agent.teamday.ai/api/missions \
  -H "Authorization: Bearer YOUR_PAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Rapport hebdomadaire",
    "instructions": "Compiler les métriques hebdomadaires et envoyer à l'\''équipe",
    "schedule": {
      "type": "weekly",
      "startDate": {"_seconds": '$(date +%s)'},
      "timeSpecs": [{"hour": 10, "minute": 0}],
      "daysOfWeek": [5]
    },
    "isActive": true
  }'

---

4. Mettre à jour une mission

Modifier une mission existante.

PUT /api/missions/:missionId

Corps de la requête (tous les champs optionnels) :

{
  "title": "string",
  "instructions": "string",
  "schedule": {...},
  "isActive": boolean
}

Exemple :

curl -X PUT https://agent.teamday.ai/api/missions/mission_abc123 \
  -H "Authorization: Bearer YOUR_PAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "isActive": false
  }'

---

5. Supprimer une mission

Archiver une mission (suppression douce).

DELETE /api/missions/:missionId

Exemple :

curl -X DELETE https://agent.teamday.ai/api/missions/mission_abc123 \
  -H "Authorization: Bearer YOUR_PAT_TOKEN"

---

6. Déclencher manuellement une mission

Exécuter une mission immédiatement, en dehors de son planning.

POST /api/missions/:missionId/trigger

Exemple :

curl -X POST https://agent.teamday.ai/api/missions/mission_abc123/trigger \
  -H "Authorization: Bearer YOUR_PAT_TOKEN"

Cas d’usage :

• Tester une mission avant de la planifier
• Déclencher des rapports à la demande
• Intégrer avec des systèmes externes (webhooks, CI/CD)

---

7. Obtenir les logs d’exécution d’une mission

Voir l’historique d’exécution et les résultats.

GET /api/missions/:missionId/logs

Exemple :

curl https://agent.teamday.ai/api/missions/mission_abc123/logs \
  -H "Authorization: Bearer YOUR_PAT_TOKEN"

Réponse :

{
  "success": true,
  "logs": [
    {
      "id": "log_xyz789",
      "missionId": "mission_abc123",
      "triggeredAt": {"_seconds": 1738483200},
      "status": "success",
      "completedAt": {"_seconds": 1738483265}
    }
  ]
}

---

Gestion des erreurs

Format de réponse d’erreur

{
  "success": false,
  "error": "Message d'erreur",
  "details": [...] // Erreurs de validation optionnelles
}

Codes de statut HTTP

Code	Signification	Exemple
200	Succès	Mission récupérée
201	Créé	Mission créée
400	Mauvaise requête	Format de planning invalide
401	Non autorisé	PAT invalide/manquant
404	Non trouvé	La mission n’existe pas
500	Erreur serveur	Erreur interne

Erreurs de validation

Quand la validation échoue (réponse 400) :

{
  "success": false,
  "error": "Erreur de validation",
  "details": [
    {
      "path": ["title"],
      "message": "Le titre est requis"
    }
  ]
}

---

Exemples de SDK

JavaScript/TypeScript

class TeamDayMissionAPI {
    constructor(private apiKey: string) {}

    private async request(endpoint: string, options: RequestInit = {}) {
        const response = await fetch(
            `https://agent.teamday.ai/api/missions${endpoint}`,
            {
                ...options,
                headers: {
                    'Authorization': `Bearer ${this.apiKey}`,
                    'Content-Type': 'application/json',
                    ...options.headers,
                },
            }
        );

        const data = await response.json();

        if (!response.ok) {
            throw new Error(data.error || 'Échec de la requête API');
        }

        return data;
    }

    async listMissions() {
        return this.request('');
    }

    async createMission(mission: {
        title: string;
        instructions: string;
        schedule: any;
        isActive?: boolean;
    }) {
        return this.request('', {
            method: 'POST',
            body: JSON.stringify(mission),
        });
    }

    async triggerMission(missionId: string) {
        return this.request(`/${missionId}/trigger`, {
            method: 'POST',
        });
    }

    async getMissionLogs(missionId: string) {
        return this.request(`/${missionId}/logs`);
    }
}

// Utilisation
const api = new TeamDayMissionAPI('YOUR_PAT_TOKEN');

const missions = await api.listMissions();
console.log('Mes missions :', missions);

const newMission = await api.createMission({
    title: 'Rappel Standup quotidien',
    instructions: 'Envoyer un rappel de standup sur Slack',
    schedule: {
        type: 'daily',
        startDate: { _seconds: Math.floor(Date.now() / 1000) },
        timeSpecs: [{ hour: 9, minute: 0, second: 0 }]
    },
    isActive: true
});
console.log('Créé :', newMission);

Python

import requests
from datetime import datetime

class TeamDayMissionAPI:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = 'https://agent.teamday.ai/api/missions'
        self.headers = {
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        }

    def list_missions(self):
        response = requests.get(self.base_url, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def create_mission(self, mission: dict):
        response = requests.post(
            self.base_url,
            headers=self.headers,
            json=mission
        )
        response.raise_for_status()
        return response.json()

    def trigger_mission(self, mission_id: str):
        response = requests.post(
            f'{self.base_url}/{mission_id}/trigger',
            headers=self.headers
        )
        response.raise_for_status()
        return response.json()

# Utilisation
api = TeamDayMissionAPI('YOUR_PAT_TOKEN')

missions = api.list_missions()
print('Mes missions :', missions)

new_mission = api.create_mission({
    'title': 'Rapport hebdomadaire d\'équipe',
    'instructions': 'Générer les métriques hebdomadaires de l\'équipe',
    'schedule': {
        'type': 'weekly',
        'startDate': {'_seconds': int(datetime.now().timestamp())},
        'timeSpecs': [{'hour': 10, 'minute': 0}],
        'daysOfWeek': [5]  # Vendredi
    },
    'isActive': True
})
print('Créé :', new_mission)

---

Cas d’usage courants

1. Intégration CI/CD

Déclencher des missions après les déploiements :

# .github/missions/deploy.yml
- name: Déclencher le résumé de déploiement
  run: |
    curl -X POST \
      -H "Authorization: Bearer ${{ secrets.TEAMDAY_PAT }}" \
      https://agent.teamday.ai/api/missions/$WORKFLOW_ID/trigger

2. Rapports planifiés

# Créer une mission qui s'exécute tous les lundis à 9h
curl -X POST https://agent.teamday.ai/api/missions \
  -H "Authorization: Bearer $TEAMDAY_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Rapport de ventes hebdomadaire",
    "instructions": "Compiler les données de ventes de la semaine dernière et envoyer par email à l'\''équipe",
    "schedule": {
      "type": "weekly",
      "startDate": {"_seconds": '$(date +%s)'},
      "timeSpecs": [{"hour": 9, "minute": 0}],
      "daysOfWeek": [1]
    },
    "isActive": true
  }'

3. Automatisation webhook

// Gestionnaire webhook Express.js
app.post('/webhook/new-customer', async (req, res) => {
    const customer = req.body;

    await fetch('https://agent.teamday.ai/api/missions', {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${process.env.TEAMDAY_PAT}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            title: `Onboarding : ${customer.name}`,
            instructions: `Envoyer un email d'onboarding à ${customer.email}`,
            schedule: {
                type: 'daily',
                startDate: { _seconds: Math.floor(Date.now() / 1000) + 3600 },
                timeSpecs: [{ hour: 10, minute: 0 }]
            },
            isActive: true
        })
    });

    res.json({ success: true });
});

---

Bonnes pratiques

Sécurité

1. Ne jamais committer les PAT dans le contrôle de version

   # Utiliser des variables d'environnement
   export TEAMDAY_PAT="your_token_here"

2. Faire tourner les tokens régulièrement

   • Créer un nouveau token
   • Mettre à jour les applications
   • Révoquer l’ancien token

3. Utiliser des tokens séparés par application

   • Plus facile de suivre l’utilisation
   • Révoquer des applications individuelles sans affecter les autres

Planification

1. Utiliser des timestamps Unix pour startDate

   const startDate = { _seconds: Math.floor(Date.now() / 1000) };

2. Tester les missions avant de les planifier

   • Créer avec isActive: false
   • Utiliser l’endpoint /trigger pour tester
   • Activer quand prêt

3. Définir les fuseaux horaires appropriés

   • Toutes les heures sont en UTC par défaut
   • Tenir compte de l’heure d’été

Gestion des erreurs

async function createMissionSafely(mission) {
    try {
        const response = await fetch('https://agent.teamday.ai/api/missions', {
            method: 'POST',
            headers: {
                'Authorization': `Bearer ${process.env.TEAMDAY_PAT}`,
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(mission)
        });

        if (!response.ok) {
            const error = await response.json();
            console.error('Échec de création de mission :', error);

            if (error.details) {
                // Gérer les erreurs de validation
                error.details.forEach(detail => {
                    console.error(`${detail.path.join('.')}: ${detail.message}`);
                });
            }

            return null;
        }

        return await response.json();
    } catch (error) {
        console.error('Erreur réseau :', error);
        return null;
    }
}

---

Résolution de problèmes

401 Unauthorized

Problème : PAT invalide ou manquant

Solutions :

• Vérifier que l’en-tête Authorization est inclus
• Vérifier le format du token : Bearer YOUR_TOKEN
• S’assurer que le token n’a pas expiré
• Vérifier que le token est pour la bonne organisation

400 Bad Request

Problème : Format de requête invalide

Solutions :

• Valider la syntaxe JSON
• Vérifier que les champs requis sont présents
• Vérifier que le format de planning correspond au type
• Examiner les détails d’erreur dans la réponse

500 Internal Server Error

Problème : Erreur côté serveur

Solutions :

• Vérifier que les instructions de mission sont valides
• Réessayer la requête après un moment
• Contacter le support si cela persiste

---

Support

• Statut de l’API : https://status.teamday.ai
• Email de support : support at teamday.ai
• Documentation : /docs

---

Historique des modifications

v1.0.0 (2025-10-04)

• Version initiale
• Authentification basée sur PAT
• Opérations CRUD complètes pour les missions
• Endpoint de déclenchement manuel
• Endpoint de logs d’exécution
• Validation PAT basée sur hash sécurisé