API Tâches

Les tâches représentent des éléments de travail qui peuvent être assignés à des agents ou des utilisateurs. Utilisez l’API Tâches pour gérer des workflows, suivre la progression et coordonner le travail au sein de votre organisation.

URL de base : https://us.teamday.ai/api/v1/tasks

Authentification : Jeton d’accès personnel requis

Aperçu des endpoints

Méthode	Endpoint	Description	Statut
GET	`/tasks`	Lister les tâches	🟡 Non testé
POST	`/tasks`	Créer une nouvelle tâche	🟡 Non testé

Statut d’implémentation : Complet mais non testé en production

Objet Tâche

Propriétés

{
  id: string              // ID de la tâche (format: task_xxx)
  title: string           // Titre de la tâche
  description: string     // Description détaillée
  status: string          // "pending" | "in_progress" | "completed" | "cancelled"
  priority: string        // "low" | "medium" | "high" | "urgent"
  assignedTo?: string     // ID de l'agent ou de l'utilisateur
  assigneeType: string    // "agent" | "user"
  spaceId?: string        // Espace de travail associé
  organizationId: string  // Organisation propriétaire
  createdBy: string       // ID de l'utilisateur créateur
  createdAt: string       // Horodatage ISO 8601
  updatedAt: string       // Horodatage ISO 8601
  dueDate?: string        // Horodatage ISO 8601
  completedAt?: string    // Horodatage ISO 8601
  metadata: object        // Contexte de tâche supplémentaire
}

Exemple d’objet

{
  "id": "task_abc123",
  "title": "Analyser les données de ventes T4",
  "description": "Examiner la performance des ventes T4 et identifier les tendances",
  "status": "in_progress",
  "priority": "high",
  "assignedTo": "agent_xyz789",
  "assigneeType": "agent",
  "spaceId": "space_456",
  "organizationId": "org_123",
  "createdBy": "user_789",
  "createdAt": "2025-12-09T09:00:00Z",
  "updatedAt": "2025-12-09T10:30:00Z",
  "dueDate": "2025-12-10T17:00:00Z",
  "metadata": {
    "tags": ["ventes", "analytique", "trimestriel"],
    "source": "api"
  }
}

Lister les tâches

Récupérer les tâches de votre organisation avec filtrage optionnel.

Requête

GET /api/v1/tasks

En-têtes :

Authorization: Bearer td_xxxxx...

Paramètres de requête :

status (string, optionnel) - Filtrer par statut : pending, in_progress, completed, cancelled
assignedTo (string, optionnel) - Filtrer par ID d’agent ou d’utilisateur
spaceId (string, optionnel) - Filtrer par espace de travail
priority (string, optionnel) - Filtrer par priorité : low, medium, high, urgent
limit (number, optionnel) - Nombre maximum de résultats (par défaut : 50, max : 100)

Réponse

Succès (200 OK) :

[
  {
    "id": "task_abc123",
    "title": "Analyser les données de ventes T4",
    "description": "Examiner la performance des ventes T4 et identifier les tendances",
    "status": "in_progress",
    "priority": "high",
    "assignedTo": "agent_xyz789",
    "assigneeType": "agent",
    "spaceId": "space_456",
    "organizationId": "org_123",
    "createdBy": "user_789",
    "createdAt": "2025-12-09T09:00:00Z",
    "updatedAt": "2025-12-09T10:30:00Z",
    "dueDate": "2025-12-10T17:00:00Z",
    "metadata": {
      "tags": ["ventes", "analytique", "trimestriel"]
    }
  },
  {
    "id": "task_def456",
    "title": "Examiner les retours clients",
    "description": "Résumer les retours clients de décembre",
    "status": "pending",
    "priority": "medium",
    "assignedTo": "user_456",
    "assigneeType": "user",
    "organizationId": "org_123",
    "createdBy": "user_789",
    "createdAt": "2025-12-09T11:00:00Z",
    "updatedAt": "2025-12-09T11:00:00Z",
    "dueDate": "2025-12-15T17:00:00Z",
    "metadata": {
      "tags": ["retours", "succès-client"]
    }
  }
]

Résultat vide :

[]

Erreur (401 Unauthorized) :

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Invalid or expired token"
}

Exemples

Lister toutes les tâches :

curl https://us.teamday.ai/api/v1/tasks \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Filtrer par statut :

curl "https://us.teamday.ai/api/v1/tasks?status=pending" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Filtrer par agent :

curl "https://us.teamday.ai/api/v1/tasks?assignedTo=agent_xyz789" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Filtrer par espace :

curl "https://us.teamday.ai/api/v1/tasks?spaceId=space_456" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Combiner les filtres :

curl "https://us.teamday.ai/api/v1/tasks?status=in_progress&spaceId=space_456&priority=high" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Limiter les résultats :

curl "https://us.teamday.ai/api/v1/tasks?limit=10" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Créer une tâche

Créer une nouvelle tâche pour votre organisation.

Requête

POST /api/v1/tasks

En-têtes :

Authorization: Bearer td_xxxxx...
Content-Type: application/json

Corps :

{
  "title": "Analyser les données de ventes T4",
  "description": "Examiner la performance des ventes T4 et identifier les tendances",
  "status": "pending",
  "priority": "high",
  "assignedTo": "agent_xyz789",
  "assigneeType": "agent",
  "spaceId": "space_456",
  "dueDate": "2025-12-10T17:00:00Z",
  "metadata": {
    "tags": ["ventes", "analytique", "trimestriel"],
    "source": "api"
  }
}

Champs requis :

title (string) - Titre de la tâche (max 200 caractères)

Champs optionnels :

description (string) - Description détaillée
status (string) - Statut initial (par défaut : "pending")
- Options : "pending", "in_progress", "completed", "cancelled"
priority (string) - Niveau de priorité (par défaut : "medium")
- Options : "low", "medium", "high", "urgent"
assignedTo (string) - ID de l’agent ou de l’utilisateur
assigneeType (string) - Type d’assigné (par défaut : "user")
- Options : "agent", "user"
spaceId (string) - ID de l’espace de travail
dueDate (string) - Horodatage ISO 8601
metadata (object) - Contexte supplémentaire (tags, champs personnalisés, etc.)

Réponse

Succès (201 Created) :

{
  "id": "task_abc123",
  "title": "Analyser les données de ventes T4",
  "description": "Examiner la performance des ventes T4 et identifier les tendances",
  "status": "pending",
  "priority": "high",
  "assignedTo": "agent_xyz789",
  "assigneeType": "agent",
  "spaceId": "space_456",
  "organizationId": "org_123",
  "createdBy": "user_789",
  "createdAt": "2025-12-09T09:00:00Z",
  "updatedAt": "2025-12-09T09:00:00Z",
  "dueDate": "2025-12-10T17:00:00Z",
  "metadata": {
    "tags": ["ventes", "analytique", "trimestriel"],
    "source": "api"
  }
}

Erreur (400 Bad Request) :

{
  "error": true,
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Missing required field: title"
}

Erreur (401 Unauthorized) :

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Invalid or expired token"
}

Exemples

Tâche minimale :

curl -X POST https://us.teamday.ai/api/v1/tasks \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Examiner les retours clients"
  }'

Tâche avec tous les champs :

curl -X POST https://us.teamday.ai/api/v1/tasks \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Analyser les données de ventes T4",
    "description": "Examiner la performance des ventes T4 et identifier les tendances. Se concentrer sur les différences régionales et la performance par catégorie de produit.",
    "status": "pending",
    "priority": "high",
    "assignedTo": "agent_xyz789",
    "assigneeType": "agent",
    "spaceId": "space_456",
    "dueDate": "2025-12-10T17:00:00Z",
    "metadata": {
      "tags": ["ventes", "analytique", "trimestriel"],
      "source": "api",
      "department": "ventes"
    }
  }'

Tâche assignée à un utilisateur :

curl -X POST https://us.teamday.ai/api/v1/tasks \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Mettre à jour la présentation T4",
    "description": "Ajouter les derniers chiffres de ventes à la présentation trimestrielle",
    "assignedTo": "user_456",
    "assigneeType": "user",
    "priority": "medium",
    "dueDate": "2025-12-11T12:00:00Z"
  }'

Workflow de statut de tâche

Les tâches progressent à travers les états suivants :

Pending

Statut : "pending"

Description : Tâche créée mais pas encore démarrée. État par défaut pour les nouvelles tâches.

États suivants : in_progress, cancelled

Cas d’utilisation :

Éléments du backlog
Travail en file d’attente
Tâches futures

In Progress

Statut : "in_progress"

Description : Tâche activement en cours de traitement.

États suivants : completed, cancelled, pending (si mis en pause)

Cas d’utilisation :

Éléments de travail actifs
Exécution d’agent
Tâches utilisateur en cours

Completed

Statut : "completed"

Description : Tâche terminée avec succès. Définit l’horodatage completedAt.

État terminal : Oui (typiquement pas de transitions ultérieures)

Cas d’utilisation :

Travail terminé
Exécution d’agent réussie
Tâches archivées

Cancelled

Statut : "cancelled"

Description : Tâche annulée avant achèvement.

État terminal : Oui (typiquement pas de transitions ultérieures)

Cas d’utilisation :

Travail dépriorisé
Tâches en double
Exigences modifiées

Niveaux de priorité

Les tâches supportent quatre niveaux de priorité :

Low

Priorité : "low"

Cas d’utilisation :

Améliorations souhaitables
Améliorations futures
Travail non urgent

SLA : Pas de deadline spécifique

Medium

Priorité : "medium"

Cas d’utilisation :

Éléments de travail réguliers
Tâches standard
Priorité par défaut

SLA : Dans le sprint/semaine

High

Priorité : "high"

Cas d’utilisation :

Fonctionnalités importantes
Demandes clients
Travail sensible au temps

SLA : Dans 1-2 jours

Urgent

Priorité : "urgent"

Cas d’utilisation :

Bugs critiques
Problèmes de production
Action immédiate requise

SLA : Le jour même

Types d’assigné

Les tâches peuvent être assignées à des agents ou des utilisateurs :

Affectation d’agent

Type : "agent"

Champ : assignedTo = ID de l’agent (format : agent_xxx)

Comportement :

La tâche peut être automatiquement exécutée par l’agent
Suivre via l’API Exécutions
L’agent peut mettre à jour le statut de la tâche

Exemple :

{
  "assignedTo": "agent_xyz789",
  "assigneeType": "agent"
}

Affectation d’utilisateur

Type : "user"

Champ : assignedTo = ID de l’utilisateur (format : user_xxx)

Comportement :

La tâche apparaît dans le tableau de bord de l’utilisateur
L’utilisateur met à jour le statut manuellement
Notifications par email (si activées)

Exemple :

{
  "assignedTo": "user_456",
  "assigneeType": "user"
}

Non assigné

Champ : assignedTo = null ou omis

Comportement :

Tâche visible par tous les membres de l’organisation
Peut être prise par n’importe quel utilisateur/agent
Apparaît dans le pool de tâches de l’organisation

Métadonnées et champs personnalisés

Utilisez l’objet metadata pour stocker des informations de tâche supplémentaires :

Modèles courants

Tags :

{
  "metadata": {
    "tags": ["urgent", "orienté-client", "bug"]
  }
}

Champs personnalisés :

{
  "metadata": {
    "department": "ingénierie",
    "project": "mise-à-niveau-plateforme-t4",
    "estimatedHours": 8,
    "complexity": "medium"
  }
}

Références externes :

{
  "metadata": {
    "jiraTicket": "PROJ-123",
    "githubIssue": "https://github.com/org/repo/issues/456",
    "slackThread": "https://workspace.slack.com/archives/C123/p123456"
  }
}

Contexte d’automation :

{
  "metadata": {
    "source": "api",
    "createdBy": "script-automation",
    "triggeredBy": "webhook",
    "webhookId": "hook_123"
  }
}

Considérations Firestore

Important : Les valeurs de métadonnées doivent être sérialisables en JSON :

✅ Chaînes, nombres, booléens, tableaux, objets
❌ undefined (utiliser null à la place)
❌ Fonctions
❌ Dates (utiliser des chaînes ISO 8601)

Filtrage et requêtes

Par statut

Obtenir toutes les tâches en attente :

curl "https://us.teamday.ai/api/v1/tasks?status=pending" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Obtenir les tâches terminées :

curl "https://us.teamday.ai/api/v1/tasks?status=completed" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Par assigné

Obtenir toutes les tâches pour un agent spécifique :

curl "https://us.teamday.ai/api/v1/tasks?assignedTo=agent_xyz789" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Obtenir toutes les tâches pour un utilisateur :

curl "https://us.teamday.ai/api/v1/tasks?assignedTo=user_456" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Par espace

Obtenir toutes les tâches dans un espace de travail :

curl "https://us.teamday.ai/api/v1/tasks?spaceId=space_456" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Par priorité

Obtenir les tâches haute priorité :

curl "https://us.teamday.ai/api/v1/tasks?priority=high" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Obtenir les tâches urgentes :

curl "https://us.teamday.ai/api/v1/tasks?priority=urgent" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Filtres combinés

Obtenir les tâches haute priorité en attente pour un agent spécifique :

curl "https://us.teamday.ai/api/v1/tasks?status=pending&priority=high&assignedTo=agent_xyz789" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Modèles courants

Créer une tâche pour un agent

curl -X POST https://us.teamday.ai/api/v1/tasks \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Analyser les tendances de ventes",
    "description": "Examiner les 30 derniers jours de données de ventes et identifier les tendances",
    "assignedTo": "agent_research123",
    "assigneeType": "agent",
    "priority": "high",
    "metadata": {
      "tags": ["analytique", "ventes"],
      "automatedTask": true
    }
  }'

Créer une tâche utilisateur

curl -X POST https://us.teamday.ai/api/v1/tasks \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Examiner l'\''analyse de l'\''agent",
    "description": "Examiner l'\''analyse des ventes fournie par l'\''Agent de recherche",
    "assignedTo": "user_manager456",
    "assigneeType": "user",
    "priority": "medium",
    "dueDate": "2025-12-11T17:00:00Z",
    "metadata": {
      "tags": ["examen"],
      "relatedTask": "task_abc123"
    }
  }'

Suivre le travail d’un agent

Créer une tâche lorsque l’agent démarre le travail :

# 1. Créer la tâche
TASK_ID=$(curl -X POST https://us.teamday.ai/api/v1/tasks \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Traiter les données client",
    "assignedTo": "agent_data789",
    "assigneeType": "agent",
    "status": "in_progress"
  }' | jq -r '.id')

# 2. Exécuter l'agent (lorsqu'il fonctionne)
# curl -X POST https://us.teamday.ai/api/v1/agents/agent_data789/execute ...

# 3. Mettre à jour la tâche à terminée (manuel pour l'instant)
# Futur : Mise à jour automatique via webhooks ou API exécutions

Automatisation de workflow

Créer des tâches dépendantes :

# 1. Tâche de recherche
curl -X POST https://us.teamday.ai/api/v1/tasks \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Rechercher les tendances du marché",
    "assignedTo": "agent_researcher",
    "assigneeType": "agent",
    "metadata": {
      "workflow": "analyse-marché",
      "step": 1
    }
  }'

# 2. Tâche d'analyse (dépend de l'étape 1)
curl -X POST https://us.teamday.ai/api/v1/tasks \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Analyser les résultats de recherche",
    "assignedTo": "agent_analyst",
    "assigneeType": "agent",
    "status": "pending",
    "metadata": {
      "workflow": "analyse-marché",
      "step": 2,
      "dependsOn": "task_step1_id"
    }
  }'

# 3. Tâche de rapport (dépend de l'étape 2)
curl -X POST https://us.teamday.ai/api/v1/tasks \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Générer le rapport de marché",
    "assignedTo": "agent_writer",
    "assigneeType": "agent",
    "status": "pending",
    "metadata": {
      "workflow": "analyse-marché",
      "step": 3,
      "dependsOn": "task_step2_id"
    }
  }'

Bonnes pratiques

Conception de tâches

Titres :

Être spécifique et actionnable
Commencer par un verbe (Analyser, Examiner, Créer, Mettre à jour)
Garder sous 100 caractères

Bons exemples :

“Analyser les données de ventes T4 pour les tendances”
“Examiner et résumer les retours clients”
“Mettre à jour la présentation trimestrielle avec les dernières métriques”

À éviter :

Titres vagues : “Trucs de ventes”, “Faire le truc”
Titres très longs qui se tronquent

Descriptions :

Fournir contexte et arrière-plan
Lister les exigences spécifiques ou critères d’acceptation
Inclure des liens vers les ressources pertinentes
Mentionner le résultat attendu

Gestion du statut

Mettre à jour le statut rapidement :

Marquer in_progress lors du démarrage du travail
Marquer completed lorsque terminé
Inclure l’horodatage completedAt pour les tâches terminées

Utiliser l’annulation judicieusement :

Annuler les doublons immédiatement
Annuler le travail dépriorisé
Ajouter la raison de l’annulation dans les métadonnées

Directives de priorité

Être cohérent :

La plupart des tâches devraient être medium ou low
Utiliser high avec parcimonie (< 20% des tâches)
Réserver urgent pour les vraies urgences (< 5% des tâches)

Éviter l’inflation de priorité :

Ne pas tout marquer comme urgent
Examiner et réduire les priorités régulièrement
Se concentrer sur le débit, pas seulement l’urgence

Stratégie d’affectation

Tâches d’agent :

Assigner aux agents pour le travail automatisable
Inclure des instructions claires dans la description
Utiliser les métadonnées pour le contexte spécifique à l’agent

Tâches utilisateur :

Assigner aux utilisateurs pour examen/approbation
Inclure tout le contexte nécessaire pour la décision
Définir des dates d’échéance réalistes

Tâches non assignées :

Utiliser pour les pools de tâches
Laisser les membres de l’équipe s’auto-assigner
Bon pour les charges de travail flexibles

Utilisation des métadonnées

Champs standard :

{
  "metadata": {
    "tags": ["tag1", "tag2"],
    "department": "ingénierie",
    "priority": "high",
    "estimatedHours": 4
  }
}

Garder les métadonnées propres :

Utiliser des conventions de nommage cohérentes
Documenter les champs personnalisés dans votre code
Éviter de stocker de gros objets (> 1KB)
Utiliser des références au lieu de dupliquer les données

Mettre à jour une tâche (Futur)

Bientôt disponible : Mettre à jour les tâches existantes via l’API

Endpoint attendu :

PATCH /api/v1/tasks/[id]

Cas d’utilisation :

Mettre à jour le statut de manière programmatique
Réassigner des tâches
Changer la priorité
Mettre à jour la description

Solution de contournement actuelle : Utiliser l’interface web pour mettre à jour les tâches

Supprimer une tâche (Futur)

Bientôt disponible : Supprimer des tâches via l’API

Endpoint attendu :

DELETE /api/v1/tasks/[id]

Cas d’utilisation :

Supprimer les tâches en double
Nettoyer les anciennes tâches
Annuler et supprimer en une action

Solution de contournement actuelle : Définir le statut à cancelled

Webhooks (Futur)

Bientôt disponible : Webhooks pour les événements de tâche

Événements prévus :

task.created
task.updated
task.status_changed
task.completed
task.assigned

Cas d’utilisation :

Déclencher l’automation lors de la création de tâche
Notifier les systèmes externes
Mettre à jour les tâches dépendantes
Envoyer des notifications

Gestion des erreurs

Erreurs courantes

400 Bad Request :

Champ requis manquant (title)
Valeur de statut invalide
Valeur de priorité invalide
Type d’assigné invalide

401 Unauthorized :

En-tête Authorization manquant
Jeton invalide ou expiré

404 Not Found :

L’ID de la tâche n’existe pas
La tâche appartient à une autre organisation

500 Internal Server Error :

Problèmes de connectivité de base de données
Service temporairement indisponible

Erreurs de validation

Titre manquant :

{
  "error": true,
  "statusCode": 400,
  "message": "Missing required field: title"
}

Statut invalide :

{
  "error": true,
  "statusCode": 400,
  "message": "Invalid status. Must be: pending, in_progress, completed, cancelled"
}

Priorité invalide :

{
  "error": true,
  "statusCode": 400,
  "message": "Invalid priority. Must be: low, medium, high, urgent"
}

Ressources associées

API Agents - Créer et gérer les agents
API Exécutions - Suivre l’historique d’exécution des agents
Authentification - Configuration du jeton PAT
Référence des erreurs - Documentation complète des erreurs

Besoin d’aide ?

Problèmes avec les tâches ?

Consultez la référence des erreurs pour le dépannage
Vérifier que les champs requis sont fournis
Valider les valeurs de statut et de priorité

Questions ?

📧 Email : support at teamday.ai
💬 Discord : Rejoindre la communauté
🐛 Signaler des bugs : Problèmes GitHub

Dernière mise à jour : 9 décembre 2025