Documents API

Documentation complète de l'API de gestion et d'extraction de documents dans Devana.ai.

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

📑 Table des matières

Vue d'ensemble
Authentification
Endpoints disponibles
Format des payloads
Statuts d'extraction
Types de fichiers supportés
Gestion des erreurs
Exemples avancés

Vue d'ensemble

L'API Documents permet de gérer le cycle de vie complet des documents :

Upload de documents avec extraction automatique du contenu
Récupération du contenu extrait et structuré
Suivi du statut d'extraction en temps réel
Support de multiples formats (PDF, DOCX, images, etc.)

Cette API utilise un système d'extraction avancé (Odin) pour traiter les documents complexes et extraire leur structure, texte, tableaux et métadonnées.

Authentification

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

http

Authorization: Bearer YOUR_API_KEY

Les permissions sont vérifiées au niveau du dossier contenant le document.

Endpoints disponibles

GET /v1/documents/:id - Récupérer le contenu d'un document

Récupère le payload complet d'un document incluant le texte extrait, la structure et les métadonnées.

Paramètres

Paramètre	Type	Requis	Description
`id`	String (CUID)	Oui	Identifiant unique du document

Requête

http

GET /v1/documents/cm4doc123abc456def
Authorization: Bearer YOUR_API_KEY

Réponse (200 OK) - Document traité par Odin

json

{
  "success": true,
  "data": {
    "documentId": "cm4doc123abc456def",
    "status": "DONE",
    "title": "Rapport Annuel 2024",
    "content": "Contenu extrait du document...",
    "pages": [
      {
        "pageNumber": 1,
        "text": "Texte de la première page...",

Réponse (200 OK) - Document texte simple

json

{
  "success": true,
  "data": {
    "documentId": "cm4doc789xyz123abc",
    "status": "DONE",
    "text": "Contenu textuel du document...",
    "words": 500,
    "title": "document.txt",
    "metadata": {
      "mimetype": "text/plain",
      "size": 15678
    }
  }
}

Exemple avec curl

bash

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

GET /v1/documents/:id/status - Statut d'extraction

Récupère uniquement le statut d'extraction d'un document sans le contenu complet.

Paramètres

Paramètre	Type	Requis	Description
`id`	String (CUID)	Oui	Identifiant unique du document

Requête

http

GET /v1/documents/cm4doc123abc456def/status
Authorization: Bearer YOUR_API_KEY

Réponse (200 OK)

json

{
  "success": true,
  "data": "DONE"
}

Statuts possibles :

PENDING : En attente de traitement
IN_PROGRESS : Extraction en cours
DONE : Extraction terminée avec succès
ERROR : Erreur lors de l'extraction

Exemple avec curl

bash

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

Utilisation pour le polling

bash

# Script de polling pour attendre la fin de l'extraction
DOCUMENT_ID="cm4doc123abc456def"
STATUS="PENDING"

while [ "$STATUS" != "DONE" ] && [ "$STATUS" != "ERROR" ]; do
  STATUS=$(curl -s -X GET "https://api.devana.ai/v1/documents/$DOCUMENT_ID/status" \
    -H "Authorization: Bearer YOUR_API_KEY" | jq -r '.data')

  echo "Status: $STATUS"

  if [ "$STATUS" = "ERROR" ]; then
    echo "Erreur lors de l'extraction"
    exit 1
  fi

  if [ "$STATUS" != "DONE" ]; then
     2
  


 
curl -X GET  \
  -H

POST /v1/documents - Upload et extraction de document

Upload un document et lance automatiquement l'extraction du contenu. Retourne immédiatement le payload pour les fichiers simples ou après traitement pour les documents complexes.

Headers

Header	Type	Requis	Description
`Authorization`	String	Oui	Token Bearer avec API Key
`Content-Type`	String	Oui	`multipart/form-data`

Body Parameters (multipart/form-data)

Paramètre	Type	Requis	Description
`file`	File	Oui	Le fichier à uploader
`folderId`	String (CUID)	Oui	ID du dossier de destination

Requête

http

POST /v1/documents
Authorization: Bearer YOUR_API_KEY
Content-Type: multipart/form-data

Réponse (200 OK) - Document complexe (PDF, DOCX, Images)

Le système attend la fin de l'extraction avant de répondre :

json

{
  "success": true,
  "data": {
    "documentId": "cm4newdoc456xyz789",
    "status": "DONE",
    "title": "Présentation Q4 2024",
    "content": "Contenu extrait structuré...",
    "pages": [
      {
        "pageNumber": 1,
        "text": "Slide 1: Résultats Q4 2024..."

Réponse (200 OK) - Document texte simple

Pour les fichiers texte simples, la réponse est immédiate :

json

{
  "success": true,
  "data": {
    "text": "Contenu du fichier texte...",
    "words": 250,
    "title": "readme.md",
    "metadata": {
      "mimetype": "text/markdown",
      "size": 5678
    }
  }
}

Exemple avec curl - Upload PDF

bash

curl -X POST https://api.devana.ai/v1/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@presentation.pdf" \
  -F "folderId=cm4folder123abc"

Exemple avec curl - Upload image

bash

curl -X POST https://api.devana.ai/v1/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@diagram.png" \
  -F "folderId=cm4folder123abc"

Format des payloads

Payload Odin (documents complexes)

Les documents traités par Odin retournent un payload structuré :

typescript

interface OdinPayload {
  documentId: string;
  status: ExtractStatus;
  title?: string;
  content?: string;
  pages?: Page[];
  metadata?: DocumentMetadata;
  summary?: string;
  keywords?: string[];
  totalWords?: number;
  error?: string;
}

interface Page {
  pageNumber: number;
  text: string;
  tables?: Table[];
  images?: Image[];
}

interface DocumentMetadata {
  author?: string;
  ?: ;
  ?: ;
  ?: ;
  ?: ;
  ?: ;
  ?: ;
}

Payload texte simple

Les fichiers texte retournent un payload simplifié :

typescript

interface TextPayload {
  text: string;
  words: number;
  title: string;
  metadata: {
    mimetype: string;
    size: number;
  };
}

Statuts d'extraction

Statut	Description	Actions recommandées
`PENDING`	Document en file d'attente	Attendre et vérifier régulièrement
`IN_PROGRESS`	Extraction en cours	Continuer le polling
`DONE`	Extraction réussie	Récupérer le payload complet
`ERROR`	Échec de l'extraction	Vérifier les logs, réessayer si nécessaire

Types de fichiers supportés

Documents avec extraction Odin

PDF : Extraction complète avec structure, images, tableaux
DOCX/DOC : Documents Word avec formatage préservé
PPTX/PPT : Présentations PowerPoint
Images : PNG, JPG, JPEG (avec OCR si nécessaire)

Documents avec extraction simple

Texte : TXT, MD, CSV
Code : JS, PY, JSON, XML, HTML
Tableurs : XLSX, XLS (extraction basique)

Pour la liste complète, consultez Formats supportés.

Gestion des erreurs

Code	Message	Description	Solution
`400`	Bad Request	Paramètres invalides	Vérifier le format des paramètres
`400`	No file uploaded	Aucun fichier fourni	Inclure un fichier dans la requête
`401`	Unauthorized	Permissions insuffisantes	Vérifier les droits sur le dossier
`404`	File/Folder not found	Ressource introuvable	Vérifier l'ID fourni
`408`

Gestion des erreurs d'extraction

En cas d'erreur lors de l'extraction :

json

{
  "success": false,
  "error": {
    "code": "EXTRACTION_FAILED",
    "message": "Failed to extract content from PDF",
    "details": "Corrupted file or unsupported format"
  }
}

Exemples avancés

Upload et traitement de document avec retry

javascript

async function uploadDocumentWithRetry(file, folderId, maxRetries = 3) {
  const formData = new ();
  formData.(, file);
  formData.(, folderId);

   ( attempt = ; attempt <= maxRetries; attempt++) {
     {
       response =  (, {
        : ,
        : {
          : ,
        },
        : formData,
      });

       (response.) {
         data =  response.();

        
         (data.. === ) {
            (data..);
        }

         data.;
      }

       (response. ===  && attempt < maxRetries) {
        .();
          ( (resolve,  * attempt));
        ;
      }

        ();
    }  (error) {
       (attempt === maxRetries)  error;
      .();
    }
  }
}

  () {
   status = ;
   attempts = ;
   maxAttempts = ; 

   (status !==  && status !==  && attempts < maxAttempts) {
      ( (resolve, ));

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

     data =  response.();
    status = data.;
    attempts++;

    .();
  }

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

     ( response.()).;
  }

    ();
}

Batch processing de documents

bash

#!/bin/bash

# Upload multiple documents to a folder
FOLDER_ID="cm4folder123abc"
FILES=("report.pdf" "presentation.pptx" "data.xlsx")
DOCUMENT_IDS=()

echo "Uploading documents..."

for FILE in "${FILES[@]}"; do
  echo "Uploading $FILE..."

  RESPONSE=$(curl -s -X POST https://api.devana.ai/v1/documents \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -F "file=@$FILE" \
    -F )

  DOC_ID=$(  | jq -r )
  DOCUMENT_IDS+=()

   


 


ALL_DONE=
 [  =  ]; 
  ALL_DONE=

   DOC_ID  ; 
    STATUS=$(curl -s -X GET  \
      -H  | jq -r )

     

     [  !=  ] && [  !=  ]; 
      ALL_DONE=
    
  

   [  =  ]; 
     3
  


 


 DOC_ID  ; 
   
  curl -X GET  \
    -H  \
    -o

Extraction avec analyse du contenu

python

 requests
 json
 typing  , 

 :
     ():
        .api_key = api_key
        .base_url = 
        .headers = {: }

     () -> :
        

        
         (file_path, )  f:
            files = {: f}
            data = {: folder_id}

            response = requests.post(
                ,
                headers=.headers,
                files=files,
                data=data
            )

         response.status_code != :
             Exception()

        document = response.json()[]

        
        analysis = .analyze_content(document)

         {
            : document,
            : analysis
        }

     () -> :
        

        analysis = {
            : document.get(, ),
            : (document.get(, [])),
            : ,
            : ,
            : document.get(, []),
            : document.get(, {}).get(),
            :   document
        }

        
         page  document.get(, []):
             page.get():
                analysis[] = 
             page.get():
                analysis[] = 

         analysis

     () -> []:
        

        tables = []
         page  document.get(, []):
             table  page.get(, []):
                tables.append({
                    : page[],
                    : table
                })

         tables


processor = DocumentProcessor()

result = processor.upload_and_analyze(
    ,
    
)

()
()


 result[][]:
    tables = processor.extract_tables(result[])
    ()

Intégration avec l'API Jobs

Pour les documents volumineux ou les traitements batch, utilisez l'API Jobs pour suivre l'extraction :

bash

# Vérifier le job d'extraction
curl -X GET "https://api.devana.ai/v1/jobs?targetId=cm4doc123abc&type=EXTRACTION" \
  -H "Authorization: Bearer YOUR_API_KEY"

Bonnes pratiques

Gestion des timeouts
- Implémenter un système de retry pour les uploads
- Utiliser le polling pour les documents complexes
- Définir un timeout maximum (ex: 5 minutes)
Optimisation des performances
- Grouper les uploads en batch quand possible
- Utiliser l'API Jobs pour le suivi asynchrone
- Mettre en cache les payloads extraits
Gestion des erreurs
- Toujours vérifier le statut d'extraction
- Logger les erreurs pour le debugging
- Prévoir un fallback pour les échecs d'extraction
Sécurité
- Vérifier les permissions avant l'upload
- Valider les types de fichiers côté client
- Limiter la taille des uploads

Support et assistance

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

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é

Documents API

📑 Table des matières

Vue d'ensemble

Authentification

Endpoints disponibles

GET /v1/documents/:id - Récupérer le contenu d'un document

Paramètres

Requête

Réponse (200 OK) - Document traité par Odin

Réponse (200 OK) - Document texte simple

Exemple avec curl

GET /v1/documents/:id/status - Statut d'extraction

Paramètres

Requête

Réponse (200 OK)

Exemple avec curl

Utilisation pour le polling

POST /v1/documents - Upload et extraction de document

Headers

Body Parameters (multipart/form-data)

Requête

Réponse (200 OK) - Document complexe (PDF, DOCX, Images)

Réponse (200 OK) - Document texte simple

Exemple avec curl - Upload PDF

Exemple avec curl - Upload image

Format des payloads

Payload Odin (documents complexes)

Payload texte simple

Statuts d'extraction

Types de fichiers supportés

Documents avec extraction Odin

Documents avec extraction simple

Gestion des erreurs

Gestion des erreurs d'extraction

Exemples avancés

Upload et traitement de document avec retry

Batch processing de documents

Extraction avec analyse du contenu

Intégration avec l'API Jobs

Bonnes pratiques

Support et assistance