Guide de l’API Files

Les fichiers (appelés ressources dans certains schémas) contiennent les éléments probants joints aux fiches : images, PDF, documents et artefacts de scan. Un fichier peut être joint directement à une fiche ou utilisé comme valeur d’un champ de type ressource.

Deux méthodes de chargement sont disponibles : une simple requête POST unique pour les petits fichiers et le protocole tus reprenable pour les fichiers volumineux. Schémas complets : référence de l’API.

Vue d’ensemble des points de terminaison

Opération	Méthode et chemin
Chargement simple	POST /api/v1/files
Chargement reprenable (tus)	POST /api/v1/files/upload, puis PATCH /api/v1/files/upload/{id}
Finaliser les chargements tus	POST /api/v1/files/finalize
Télécharger	GET /api/v1/files/{resource_id}/download
URL signées	POST /api/v1/files/urls
Rechercher des fichiers	GET /api/v1/files/search
Répertorier les fichiers (curseur)	GET /api/v1/files
Répertorier les fichiers d’une fiche	GET /api/v1/threads/{thread_id}/files

Les requêtes portant sur des fichiers nécessitent une appartenance actuelle à l’équipe sélectionnée, laquelle doit appartenir à l’organisation sélectionnée. Cette exigence s’applique aux personnes et aux comptes de service. Le chargement vers une fiche nécessite un accès en modification ; les chargements privés doivent cibler une fiche et nécessitent l’autorisation de gérer ses ressources privées. Les fichiers non joints ne sont lisibles par leur équipe propriétaire que s’ils ne sont pas privés.

Chargement simple

Pour les fichiers qu’une seule requête peut facilement transporter, envoyez une requête POST multipart/form-data contenant file et, éventuellement, les cibles de rattachement. La réponse comprend la ressource créée ainsi qu’une URL signée :

curl

curl -fsS "$APID_URL/api/v1/files" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -F "file=@inspection-report.pdf" \
  -F "threadId=$THREAD_ID"

TypeScript

const resources = await client.files.upload({
  file,               // a File
  threadId,           // optional: attach to a Thread
  // fieldId,         // optional: attach as a field value
  // isPrivate: true, // optional
});

fieldId joint le fichier en tant que valeur d’un champ de type ressource ; isPrivate en restreint la visibilité.

Chargement reprenable (tus)

Les fichiers volumineux utilisent le protocole de chargement reprenable tus 1.0 au point de terminaison /api/v1/files/upload, suivi d’un appel de finalisation qui transforme le chargement terminé en enregistrement de ressource. Le processus est le suivant : chargement → finalisation → déjà joint, ou rattachement au moyen de champs.

1. Créez le chargement. Envoyez une requête POST avec les en-têtes tus ; les valeurs de Upload-Metadata sont encodées en base64 et filename est obligatoire (fieldId, threadId et isPrivate sont facultatifs) :

   curl -i -X POST "$APID_URL/api/v1/files/upload" \
     -H "Authorization: Bearer $DUST_TOKEN" \
     -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
     -H "Tus-Resumable: 1.0.0" \
     -H "Upload-Length: 52428800" \
     -H "Upload-Metadata: filename $(printf 'video.mp4' | base64),threadId $(printf %s "$THREAD_ID" | base64)"
   # → 201 Created
   # → Location: …/api/v1/files/upload/<upload-id>

   Conservez l’<upload-id> fourni dans Location pour la finalisation. La réponse finale fournit l’identifiant permanent de la ressource, qui peut être différent. Déclarez la fiche, le champ et le caractère privé prévus lors de la création ; ces éléments ne peuvent pas être modifiés pendant la finalisation. Upload-Length doit correspondre à un nombre d’octets positif et connu.

2. Envoyez les octets (opération reprenable — des requêtes PATCH répétées reprennent à partir de Upload-Offset) :

   curl -i -X PATCH "$APID_URL/api/v1/files/upload/$UPLOAD_ID" \
     -H "Authorization: Bearer $DUST_TOKEN" \
     -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
     -H "Tus-Resumable: 1.0.0" \
     -H "Upload-Offset: 0" \
     -H "Content-Type: application/offset+octet-stream" \
     --data-binary @video.mp4

   Les requêtes de chargement tolèrent des périodes d’inactivité prolongées. Pour reprendre après une interruption, envoyez une requête HEAD à la même URL afin de lire la valeur actuelle de Upload-Offset, puis reprenez les requêtes PATCH à partir de cette position. Toute bibliothèque cliente tus 1.0 (par exemple tus-js-client) peut gérer ce protocole pour vous.

3. Finalisez. Les chargements ne deviennent des enregistrements de ressource qu’après leur finalisation :

   curl -fsS "$APID_URL/api/v1/files/finalize" \
     -H "Authorization: Bearer $DUST_TOKEN" \
     -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
     -H "Content-Type: application/json" \
     -d '{
       "threadId": "'"$THREAD_ID"'",
       "requests": [
         { "resId": "'"$UPLOAD_ID"'", "filename": "video.mp4", "size": 52428800 }
       ]
     }'

   POST /api/v1/files/finalize accepte plusieurs chargements à la fois ; chaque élément de la requête reçoit l’identifiant de chargement tus dans resId, ainsi que filename et size (fieldId et isPrivate sont facultatifs). Le nom du fichier, sa taille, la fiche, le champ et le caractère privé doivent correspondre à la requête de création du chargement. Utilisez la même identité authentifiée ainsi que le même contexte d’organisation et d’équipe pour la création, les fragments, les requêtes HEAD et DELETE, et la finalisation. Les sessions de chargement expirent sept jours après leur création. Seuls les chargements terminés peuvent être finalisés.

   Une nouvelle tentative de finalisation identique effectuée pendant cette période renvoie les ressources d’origine avec de nouvelles URL signées. Un lot doit contenir soit uniquement de nouveaux chargements terminés, soit uniquement des chargements déjà finalisés. Les chargements finalisés ne peuvent plus être modifiés par une requête PATCH ni interrompus au moyen de tus.

Note

Les points de terminaison tus utilisent le protocole filaire tus plutôt que JSON ; ils ne figurent donc que de manière synthétique dans la référence de l’API. Le comportement décrit ci-dessus est défini par la configuration tus du serveur (/upload et /upload/{id} sous /api/v1/files).

Téléchargements et URL signées

• GET /api/v1/files/{resource_id}/download — redirige vers une URL signée permettant de télécharger le fichier.
• POST /api/v1/files/urls?ids=<id>&ids=<id> — génère des URL signées de courte durée pour un accès direct au stockage d’objets ; utilisez-les lorsqu’un navigateur ou un système en aval doit accéder aux octets sans passer par un proxy.

Attention

Les URL signées expirent. Stockez les identifiants des ressources, jamais les URL signées — demandez de nouvelles URL lorsque vous avez besoin d’un nouvel accès.

Recherche et listes

Deux types de requêtes sont disponibles :

• GET /api/v1/files/search — recherche indexée par page avec q, threadId, mimeFilters et includeArchived.
• GET /api/v1/files — liste paginée par curseur (cursor, pageSize ; includeArchived est obligatoire), filtrée par threadId ou createdBy.

Pour les fichiers associés à une seule fiche, privilégiez GET /api/v1/threads/{thread_id}/files (consultez le guide des fiches).

Pages connexes

• Guide de l’API Threads — joindre des fichiers aux champs et aux miniatures des fiches
• Modèle fondamental — place des fichiers dans le domaine
• Référence de l’API — détails complets des paramètres et des schémas