Jobs API

Documentation de l'API de gestion des tâches asynchrones (Jobs) dans Devana.ai.

Base URL: https://api.devana.ai Préfixe: /v1/jobs Authentification: API Key requise

📑 Table des matières

Vue d'ensemble
Authentification
Endpoint disponible
- GET /v1/jobs
Types de jobs
Statuts des jobs
Filtrage et pagination
Structure des jobs
Exemples d'utilisation
Cas d'usage avancés

Vue d'ensemble

L'API Jobs permet de suivre l'état des tâches asynchrones dans Devana.ai. Ces tâches incluent :

Extraction de contenu de documents
Génération d'embeddings
Synchronisation de dossiers
Import de données externes
Traitement batch de fichiers

Caractéristiques principales :

Suivi en temps réel des tâches
Filtrage par type et statut
Historique limité aux dernières 24 heures
Pagination pour les grandes listes

Authentification

Toutes les requêtes nécessitent une clé API dans le header Authorization :

http

Authorization: Bearer YOUR_API_KEY

Endpoint disponible

GET /v1/jobs - Lister les tâches

Récupère la liste des tâches asynchrones de l'utilisateur avec possibilité de filtrage.

Query Parameters

Paramètre	Type	Requis	Description	Valeur par défaut
`targetId`	String	Non	ID de la ressource cible (document, dossier, etc.)	-
`type`	String (Enum)	Non	Filtrer par statut : `PENDING`, `IN_PROGRESS`, `DONE`, `ERROR`	-
`limit`	Number	Non	Nombre maximum de résultats

Requête

http

GET /v1/jobs?targetId=cm4doc123&type=IN_PROGRESS&limit=10
Authorization: Bearer YOUR_API_KEY

Réponse (200 OK)

json

{
  "success": true,
  "data": [
    {
      "id": "cm4job789xyz123",
      "userId": "cm4user456abc",
      "targetId": "cm4doc123abc456",
      "type": "EXTRACTION",
      "status": "IN_PROGRESS",

Exemples avec curl

Récupérer toutes les tâches récentes :

bash

curl -X GET https://api.devana.ai/v1/jobs \
  -H "Authorization: Bearer YOUR_API_KEY"

Filtrer par document spécifique :

bash

curl -X GET "https://api.devana.ai/v1/jobs?targetId=cm4doc123abc456" \
  -H "Authorization: Bearer YOUR_API_KEY"

Récupérer les tâches en erreur :

bash

curl -X GET "https://api.devana.ai/v1/jobs?type=ERROR" \
  -H "Authorization: Bearer YOUR_API_KEY"

Pagination des résultats :

bash

curl -X GET "https://api.devana.ai/v1/jobs?limit=50&offset=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Types de jobs

Les différents types de tâches trackées par le système :

Type	Description	Durée typique
`EXTRACTION`	Extraction de contenu de documents (PDF, DOCX, etc.)	5s - 5min
`EMBEDDING`	Génération de vecteurs pour la recherche sémantique	10s - 10min
`SYNC`	Synchronisation de dossiers externes (SharePoint, etc.)	1min - 30min
`IMPORT`	Import batch de fichiers	30s - 15min
`TRANSCRIPTION`	Transcription audio (STT)	10s - 5min
`GENERATION`

Statuts des jobs

Statut	Description	Action recommandée
`PENDING`	Tâche en attente dans la queue	Attendre, vérifier régulièrement
`IN_PROGRESS`	Tâche en cours d'exécution	Continuer le polling
`DONE`	Tâche terminée avec succès	Récupérer les résultats
`ERROR`	Échec de la tâche	Vérifier les logs, réessayer
`KILLED`	Tâche annulée (non retourné par l'API)	-

Note : Les jobs avec statut KILLED sont automatiquement filtrés et ne sont jamais retournés.

Filtrage et pagination

Filtrage par date

Seuls les jobs des dernières 24 heures sont retournés
Pour un historique plus ancien, utilisez l'interface web

Limitations

Maximum 100 résultats par requête
Offset maximum : 1000
Les jobs sont triés par date de création (plus récent en premier)

Exemples de filtrage complexe

javascript

// Récupérer les jobs d'un dossier spécifique
async function getFolderJobs(folderId) {
  const response = await fetch(
    `https://api.devana.ai/v1/jobs?targetId=${folderId}`,
    {
      headers: {
        Authorization: `Bearer ${API_KEY}`,
      },
    }
  );

  const data = await response.json();
  return data.data;
}

// Filtrer les jobs par multiple critères
async function getFilteredJobs(filters) {
  const params = new URLSearchParams();

   (filters.) params.(, filters.);
   (filters.) params.(, filters.);
   (filters.) params.(, filters.);
   (filters.) params.(, filters.);

   response =  (
    ,
    {
      : {
        : ,
      },
    }
  );

   response.();
}

Structure des jobs

Objet Job complet

typescript

interface Job {
  id: string; // Identifiant unique du job
  userId: string; // ID de l'utilisateur propriétaire
  targetId: string; // ID de la ressource cible
  type: JobType; // Type de tâche
  status: JobStatus; // Statut actuel
  progress?: number; // Progression (0-100)
  metadata?: {
    // Métadonnées spécifiques au type
    [key: string]: any;
  };
  error?: string; // Message d'erreur si échec
  startedAt?: Date; // Début de l'exécution
  completedAt?: Date; 
  : ; 
  : ; 
}

Métadonnées par type

EXTRACTION:

json

{
  "fileName": "document.pdf",
  "fileSize": 1234567,
  "mimeType": "application/pdf",
  "pageCount": 10,
  "extractionMethod": "ODIN"
}

EMBEDDING:

json

{
  "folderName": "Knowledge Base",
  "filesProcessed": 15,
  "totalChunks": 450,
  "chunkSize": 500,
  "model": "text-embedding-ada-002"
}

Exemples d'utilisation

Monitoring d'extraction de document

bash

#!/bin/bash

# Upload un document et suivre son extraction
DOCUMENT_ID="cm4doc123abc456"

# Fonction pour vérifier le statut
check_job_status() {
  local doc_id=$1

  while true; do
    # Récupérer le job d'extraction
    JOB=$(curl -s -X GET "https://api.devana.ai/v1/jobs?targetId=$doc_id&type=EXTRACTION" \
      -H "Authorization: Bearer YOUR_API_KEY" | jq -r '.data[0]')

    if [ "$JOB" = "null" ]; then
      echo "Aucun job trouvé pour le document $doc_id"
      break
    

    STATUS=$(  | jq -r )
    PROGRESS=$(  | jq -r )

     

      
      )
         
        
        ;;
      )
        ERROR=$(  | jq -r )
         
         1
        ;;
      *)
         2
        ;;
    
  
}

check_job_status

Suivi de synchronisation de dossier

python

Cas d'usage avancés

Dashboard de monitoring

javascript

Retry automatique des jobs en échec

bash

#!/bin/bash

# Script de retry automatique pour les jobs en échec

API_KEY="YOUR_API_KEY"
MAX_RETRIES=3

retry_failed_jobs() {
  echo "Recherche des jobs en échec..."

  # Récupérer les jobs en erreur
  FAILED_JOBS=$(curl -s -X GET "https://api.devana.ai/v1/jobs?type=ERROR" \
    -H "Authorization: Bearer $API_KEY" | jq -r '.data[]')

  if [ -z "$FAILED_JOBS" ]; then
    echo "Aucun job en échec trouvé"
    return
  

    | jq -c  |   -r job; 
    JOB_ID=$(  | jq -r )
    TARGET_ID=$(  | jq -r )
    JOB_TYPE=$(  | jq -r )

     

      
      )
        
        curl -X POST  \
          -H 
        ;;
      )
        
        curl -X POST  \
          -H 
        ;;
      *)
         
        ;;
    

     2
  
}


 ; 
  retry_failed_jobs
   
   300

Intégration avec webhooks

Pour recevoir des notifications en temps réel sur les changements de statut des jobs, configurez des webhooks :

javascript

// Exemple de webhook handler
app.post("/webhook/job-status", (req, res) => {
  const { jobId, status, targetId, type, metadata } = req.body;

  console.log(`Job ${jobId} updated: ${status}`);

  switch (status) {
    case "DONE":
      // Traiter la fin du job
      handleJobComplete(targetId, type, metadata);
      break;
    case "ERROR":
      // Gérer l'erreur
      handleJobError(jobId, metadata.error);
      break;
  }

  res.status(200).send("OK");
});

Limitations et considérations

Rétention des données
- Les jobs sont conservés seulement 24 heures
- Pour un historique long terme, stockez les résultats localement
Rate limiting
- Maximum 100 requêtes par minute
- Utilisez le polling intelligent avec backoff exponentiel
Performance
- Évitez les requêtes trop fréquentes (minimum 2 secondes entre les polls)
- Utilisez les filtres pour réduire la charge

Support et assistance

Pour toute question ou problème concernant l'API Jobs :

Consultez la documentation générale de l'API
Contactez le support technique : support@devana.ai
Reportez les bugs sur notre GitHub

SDK

Notes de version

Conformité

Jobs API

📑 Table des matières

Vue d'ensemble

Authentification

Endpoint disponible

GET /v1/jobs - Lister les tâches

Query Parameters

Requête

Réponse (200 OK)

Exemples avec curl

Types de jobs

Statuts des jobs

Filtrage par date

Limitations

Exemples de filtrage complexe

Structure des jobs

Objet Job complet

Métadonnées par type

Exemples d'utilisation

Monitoring d'extraction de document

Suivi de synchronisation de dossier

Cas d'usage avancés

Dashboard de monitoring

Retry automatique des jobs en échec

Intégration avec webhooks

Limitations et considérations

Support et assistance