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
L'API Documents permet de gérer le cycle de vie complet des documents :
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.
Toutes les requêtes nécessitent une clé API dans le header Authorization :
Authorization: Bearer YOUR_API_KEY
Les permissions sont vérifiées au niveau du dossier contenant le document.
Récupère le payload complet d'un document incluant le texte extrait, la structure et les métadonnées.
| Paramètre | Type | Requis | Description |
|---|---|---|---|
id | String (CUID) | Oui | Identifiant unique du document |
GET /v1/documents/cm4doc123abc456def
Authorization: Bearer YOUR_API_KEY
{
"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...",
"tables": [],
"images": []
}
],
"metadata": {
"author": "John Doe"
{
"success": true,
"data": {
"documentId": "cm4doc789xyz123abc",
"status": "DONE",
"text": "Contenu textuel du document...",
"words": 500,
"title": "document.txt",
"metadata": {
"mimetype": "text/plain",
"size": 15678
}
}
}
curl -X GET https://api.devana.ai/v1/documents/cm4doc123abc456def \
-H "Authorization: Bearer YOUR_API_KEY"
Récupère uniquement le statut d'extraction d'un document sans le contenu complet.
| Paramètre | Type | Requis | Description |
|---|---|---|---|
id | String (CUID) | Oui | Identifiant unique du document |
GET /v1/documents/cm4doc123abc456def/status
Authorization: Bearer YOUR_API_KEY
{
"success": true,
"data": "DONE"
}
Statuts possibles :
PENDING : En attente de traitementIN_PROGRESS : Extraction en coursDONE : Extraction terminée avec succèsERROR : Erreur lors de l'extractioncurl -X GET https://api.devana.ai/v1/documents/cm4doc123abc456def/status \
-H "Authorization: Bearer YOUR_API_KEY"
# 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
sleep 2
fi
done
echo "Extraction terminée, récupération du contenu..."
curl -X GET "https://api.devana.ai/v1/documents/$DOCUMENT_ID" \
-H "Authorization: Bearer YOUR_API_KEY"
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.
| Header | Type | Requis | Description |
|---|---|---|---|
Authorization | String | Oui | Token Bearer avec API Key |
Content-Type | String | Oui | multipart/form-data |
| Paramètre | Type | Requis | Description |
|---|---|---|---|
file | File | Oui | Le fichier à uploader |
folderId | String (CUID) | Oui | ID du dossier de destination |
POST /v1/documents
Authorization: Bearer YOUR_API_KEY
Content-Type: multipart/form-data
Le système attend la fin de l'extraction avant de répondre :
{
"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...",
"images": [
{
"url": "https://storage.devana.ai/images/chart1.png",
"caption": "Graphique des ventes"
}
]
}
],
Pour les fichiers texte simples, la réponse est immédiate :
{
"success": true,
"data": {
"text": "Contenu du fichier texte...",
"words": 250,
"title": "readme.md",
"metadata": {
"mimetype": "text/markdown",
"size": 5678
}
}
}
curl -X POST https://api.devana.ai/v1/documents \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@presentation.pdf" \
-F "folderId=cm4folder123abc"
curl -X POST https://api.devana.ai/v1/documents \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@diagram.png" \
-F "folderId=cm4folder123abc"
Les documents traités par Odin retournent un payload structuré :
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;
creationDate?: string;
modificationDate?: string;
pageCount?: number;
language?: string;
format?: string;
extractionTime?: number;
}
Les fichiers texte retournent un payload simplifié :
interface TextPayload {
text: string;
words: number;
title: string;
metadata: {
mimetype: string;
size: number;
};
}
| 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 |
Pour la liste complète, consultez Formats supportés.
| 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 | Request Timeout | Extraction trop longue | Réessayer ou utiliser l'API Jobs |
500 | Internal Server Error | Erreur serveur | Contacter le support |
En cas d'erreur lors de l'extraction :
{
"success": false,
"error": {
"code": "EXTRACTION_FAILED",
"message": "Failed to extract content from PDF",
"details": "Corrupted file or unsupported format"
}
}
async function uploadDocumentWithRetry(file, folderId, maxRetries = 3) {
const formData = new FormData();
formData.append("file", file);
formData.append("folderId", folderId);
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
const response = await fetch("https://api.devana.ai/v1/documents", {
method: "POST",
headers: {
Authorization: `Bearer ${API_KEY}`,
},
body: formData,
});
if (response.ok) {
const data = await response.json();
// Si le document est en cours de traitement
if (data.data.status === "IN_PROGRESS") {
return await waitForExtraction(data.data.documentId);
}
return data.data;
}
if (response.status === && 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.()).;
}
();
}
#!/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 "folderId=$FOLDER_ID")
DOC_ID=$(echo $RESPONSE | jq -r '.data.documentId')
DOCUMENT_IDS+=($DOC_ID)
echo "Document $FILE uploaded with ID: $DOC_ID"
done
echo "Checking extraction status..."
# Wait for all documents to be processed
ALL_DONE=false
while [ "$ALL_DONE" = false ]; do
ALL_DONE=true
for DOC_ID in "${DOCUMENT_IDS[@]}"; do
STATUS=$(curl -s -X GET "https://api.devana.ai/v1/documents/$DOC_ID/status" \
-H | jq -r )
[ != ] && [ != ];
ALL_DONE=
[ = ];
3
DOC_ID ;
curl -X GET \
-H \
-o
import requests
import json
from typing import Dict, List
class DocumentProcessor:
def __init__(self, api_key: str):
self.api_key = api_key
self.base_url = "https://api.devana.ai/v1"
self.headers = {"Authorization": f"Bearer {api_key}"}
def upload_and_analyze(self, file_path: str, folder_id: str) -> Dict:
"""Upload un document et analyse son contenu"""
# Upload du document
with open(file_path, 'rb') as f:
files = {'file': f}
data = {'folderId': folder_id}
response = requests.post(
f"{self.base_url}/documents",
headers=self.headers,
files=files,
data=data
)
if response.status_code != 200:
raise Exception(f"Upload failed: {response.text}")
document = response.json()['data']
# Analyser le contenu
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[])
()
Pour les documents volumineux ou les traitements batch, utilisez l'API Jobs pour suivre l'extraction :
# 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"
Gestion des timeouts
Optimisation des performances
Gestion des erreurs
Sécurité
Pour toute question ou problème concernant l'API Documents :