Fichiers générés

Une tâche, une conversation dans l’assistant ou une requête API peut produire un fichier : classeur Excel, document Word, CSV, texte, JSON ou HTML. Le fichier est stocké chiffré, téléchargeable là où il a été produit, et peut partir en pièce jointe de la livraison d’une tâche.

Deux façons de produire un fichier

Le choix n’est pas cosmétique : il décide de ce que coûte le fichier et de sa fiabilité.

	Ce que vous produisez	Quand
`create_file`	Le modèle rédige le contenu	Un rapport, une synthèse, une note
`miraca.file.write()` (dans un script)	Le script calcule le contenu	Un export, un tableau issu d’une base ou d’un connecteur

La règle : si les lignes viennent d’une source, passez par un script. Si les phrases viennent du modèle, create_file suffit.

Pourquoi c’est important : le contenu de create_file transite par la réponse du modèle, donc il est facturé en tokens de sortie et plafonné. Un tableau de plusieurs centaines de lignes dicté de cette manière sera coupé. Un script, lui, traite les données sans qu’elles n’entrent jamais dans le contexte du modèle : l’export est exact, et il ne coûte presque rien.

Depuis un script (exports, gros volumes)

Dans un script run_code, l’objet miraca.file écrit un fichier à partir de données récupérées par les autres ponts (miraca.kb, miraca.connector) :

const factures = [];
let cursor = null;
do {
  const page = await miraca.connector("pennylane").call("list-customer-invoices", { cursor });
  factures.push(...page.invoices);
  cursor = page.next_cursor;
} while (cursor);

const impayees = factures.filter((f) => f.status !== "paid");

await miraca.file.write({
  format: "xlsx",
  filename: "impayees-2026",
  sheets: [
    {
      name: "Impayées",
      columns: ["Numéro", "Client", "Montant HT", "Échéance"],
      rows: impayees.map((f) => [f.number, f.customer.name, Number(f.total_ht), f.due_date]),
    },
  ],
});

console.log(`${impayees.length} factures impayées exportées`);

Formats et contenus acceptés

Format	Champ à fournir	Nature
`xlsx`	`sheets: [{ name, columns, rows }]`, ou `rows` + `columns` pour une feuille unique	tableur
`csv`, `tsv`	`rows`, et `columns` pour l’en-tête	tableur
`docx`, `rtf`	`text` — du markdown (titres, listes, tableaux, gras) ; du HTML y est converti	document mis en forme
`html`	`text` — du HTML, écrit tel quel (styles compris), ou du markdown, mis en forme	page web
`pptx`	`slides: [{ title, bullets, notes }]`, ou `text` markdown (chaque titre ouvre une diapositive) ; du HTML y est converti	présentation
`md`, `txt`, `js`	`text`, écrit tel quel	texte ou code
`svg`	`text` — le balisage SVG complet, écrit tel quel	schéma ou illustration vectorielle
`json`	`data` (objet ou tableau)	données

Le html accepte les deux matières, et c’est voulu : demander « une page web » donne le plus souvent une page complète (<!DOCTYPE html>, styles compris), qui est alors écrite intégralement, sans rien réinterpréter. Un contenu en markdown reste mis en forme dans une page sobre. Un fichier HTML est toujours servi en téléchargement, jamais affiché sur nos domaines.

Le svg est la seule image qu’un modèle puisse produire, et c’est parce qu’il s’agit de balisage : un modèle écrit du texte, pas des pixels. Un schéma, un organigramme, un badge s’écrivent donc directement, s’ouvrent dans n’importe quel navigateur, s’importent dans un traitement de texte ou un logiciel de présentation, et ne pixellisent jamais. Un contenu qui ne comporte pas de balise <svg> est refusé plutôt que produit : un fichier .svg qui ne s’ouvre nulle part serait pire qu’une erreur. Le PNG et le JPEG ne sont pas proposés, pour la même raison que le PDF : ils demanderaient un moteur de rendu, et le rendu du texte y dépendrait des polices installées sur le serveur.

Le rtf s’ouvre partout sans rien installer (TextEdit, WordPad, outils métier anciens) : c’est le format de repli quand on ignore ce dont dispose le destinataire. Le js, comme md et txt, est écrit sans aucun reformatage — un script réindenté ne s’exécute plus.

Exemple de présentation :

{
  "format": "pptx",
  "filename": "bilan-2026",
  "slides": [
    { "title": "Bilan 2026", "bullets": ["Recettes en hausse", "Deux recrutements"],
      "notes": "Insister sur la trésorerie" },
    { "title": "Perspectives", "bullets": ["Nouveau marché"] }
  ]
}

Envoyez les montants et les quantités comme des nombres, pas comme des chaînes : sinon le destinataire ne peut ni trier ni sommer sa colonne dans Excel.

Le nom de fichier est assaini et l’extension est imposée par le format : un .xlsx qui contiendrait du CSV serait un piège pour la personne qui l’ouvre.

Livrer le fichier

Créer un fichier ne l’envoie pas. Pour le transmettre, l’agent appelle deliver en précisant les fichiers à joindre :

{ "content": "Voici l'export des impayés.", "file_ids": ["…"] }

Les fichiers partent alors vers les destinations configurées de la tâche (le modèle ne choisit jamais le destinataire), sous la forme adaptée à chaque canal :

Canal	Ce qui part
Email	pièce jointe
Slack	fichier téléversé dans le canal ou le message direct
Webhook	un lien signé dans `files[]`, valable 7 jours

Si l’agent ne livre rien de lui-même, le repli automatique envoie la réponse et les fichiers produits.

Au-delà d’environ 25 Mo cumulés, les fichiers ne sont pas joints à l’email : celui-ci le signale et ils restent téléchargeables depuis l’historique d’exécution.

Le webhook reçoit des liens plutôt que le contenu, pour ne pas gonfler le corps JSON :

{
  "task": { "slug": "impayes" },
  "run_id": "…",
  "output": "12 factures impayées.",
  "files": [
    {
      "filename": "impayees.xlsx",
      "url": "https://app.miraca.fr/api/files/…?token=…",
      "expires_at": "2026-09-11T08:00:00.000Z"
    }
  ]
}

Le lien porte un jeton signé : il n’ouvre que ce fichier, et il expire. Make et n8n savent télécharger une URL directement.

Dans Slack

Le bot peut lui aussi produire un fichier : demandez-lui un tableau, il le dépose dans le fil. Cela demande la même réinstallation que ci-dessus.

Le contenu du fichier transite alors par Slack, comme les messages du bot : c’est un canal de confort, pas la voie souveraine. Pour un livrable sensible, préférez l’assistant.

Dans l’assistant et le bac à sable

En mode « le plus réfléchi », l’assistant peut produire un fichier sans réglage préalable : demandez-lui un tableau ou un document, et une carte de téléchargement apparaît sous sa réponse. Elle réapparaît quand vous rouvrez la conversation.

Le mode « le plus rapide » ne le permet pas : il répond en une seule étape, sans outil.

Un fichier produit dans une conversation appartient à vous, pas à l’organisation : il suit la confidentialité de la conversation qui l’a fait naître, comme les messages.

Depuis l’API

Activez l’outil avec le jeton files :

{
  "model": "mistral-small",
  "messages": [{ "role": "user", "content": "Fais-moi un CSV des trois premiers mois." }],
  "tools_enabled": ["files"]
}

La réponse porte alors un champ miraca_files :

{
  "miraca_files": [
    { "id": "…", "filename": "mois.csv", "format": "csv", "bytes": 128 }
  ]
}

Le contenu se télécharge ensuite par GET /api/files/{id} avec la même clé.

Retrouver les fichiers

Assistant / bac à sable : la carte sous la réponse qui les a produits.
Portail : dans le tableau de bord de la tâche, ouvrez une exécution — la section « Fichiers produits » liste les fichiers avec un bouton de téléchargement.
Assistant, « Mes fichiers » : ce que vous avez produit dans vos conversations. Ces fichiers vous sont personnels — les autres membres de l’organisation n’y ont pas accès, y compris les administrateurs. C’est la vue disponible à tous les rôles, et la seule pour un membre cantonné à l’assistant.
Portail, page « Fichiers » : la liste de tout ce que vos conversations et vos tâches ont produit, avec son origine (un lien ramène à la conversation ou à la tâche), sa date, sa taille, et un bouton pour le supprimer. Les livrables de tâches appartiennent à l’organisation et sont visibles de ses membres : c’est ce qui permet à l’équipe de les consulter. C’est aussi là que se lit votre consommation de stockage.
API : GET /v1/files liste les fichiers du compte, GET /v1/tasks/{slug}/runs/{run_id} ceux d’une exécution précise.
Téléchargement direct : GET /api/files/{id}, avec votre clé sk- ou votre session.

curl -H "Authorization: Bearer sk-…" \
  https://app.miraca.fr/api/files/<id> -o export.xlsx

`GET /v1/files`

Les fichiers du compte, les plus récents d’abord. Paramètres : limit (1-200, défaut 50), offset, et run_id pour ne garder que ceux d’une exécution.

curl -H "Authorization: Bearer sk-…" \
  "https://app.miraca.fr/v1/files?limit=20"

{
  "files": [
    {
      "id": "8f3c…",
      "filename": "export-adherents.xlsx",
      "format": "xlsx",
      "mime": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "bytes": 48213,
      "created_at": "2026-09-04T09:12:00.000Z",
      "run_id": "b21e…",
      "conversation_id": null,
      "download_path": "/api/files/8f3c…"
    }
  ],
  "total": 37,
  "offset": 0,
  "page_size": 20,
  "has_more": true,
  "quota": {
    "storage_bytes": 481209,
    "storage_limit_bytes": 5368709120,
    "storage_peak_bytes": 902144,
    "egress_bytes": 0,
    "egress_limit_bytes": 107374182400,
    "compute_ms": 0,
    "compute_limit_ms": 144000000
  }
}

Le bloc quota répond à la question qui suit immédiatement « que contient mon espace ? ». Il ne porte aucun montant : ce sont des plafonds, pas des postes de facturation.

`GET /v1/files/{id}` et `DELETE /v1/files/{id}`

Le premier renvoie les métadonnées (le contenu reste sur /api/files/{id}, qui répond en binaire). Le second supprime le fichier, et réussit même s’il était déjà supprimé : une automatisation qui rejoue son nettoyage ne doit pas échouer sur un travail déjà fait.

curl -X DELETE -H "Authorization: Bearer sk-…" \
  https://app.miraca.fr/v1/files/<id>

Un fichier effacé répond 410 avec sa date, jamais 404 : vous avez prouvé votre accès, vous laisser croire à une erreur d’identifiant vous ferait chercher un lien qui n’existe plus. Un identifiant qui n’est pas à vous reste un 404.

Conservation

Les fichiers sont chiffrés au repos et ne sont lisibles que par le compte propriétaire.

Un administrateur fixe la durée de conservation des fichiers de l’organisation dans Réglages → Préférences & alertes : moins d’une heure, 1 jour, 7 jours, 30 jours, 3 mois, 6 mois, ou jamais. Passé ce délai, le fichier est effacé définitivement.

Trois durées peuvent s’appliquer à un même fichier — celle-ci, celle de la conversation ou de l’exécution qui le porte, et les 30 jours d’un fichier produit hors de tout contexte (appel API direct). La plus courte l’emporte : régler les fichiers sur 7 jours dans une organisation qui conserve ses conversations 30 jours donne bien 7 jours.

Le réglage « jamais » n’efface rien : l’espace de stockage se remplit alors au fil du temps, et c’est la cause la plus fréquente d’une saturation.

Un fichier effacé ne devient pas introuvable : le télécharger répond explicitement qu’il a été supprimé, avec la date (410 Gone). Pour quelqu’un qui n’y avait pas accès, la réponse reste un 404 — l’existence d’un identifiant n’est jamais révélée.

Stockage, téléchargement et calcul

Trois consommations sont bornées par compte. Ce ne sont pas des postes de facturation : elles ne débitent aucun crédit et n’apparaissent sur aucune facture. Ce sont des garde-fous.

Ressource	Plafond par défaut	Ce qu’elle mesure
Stockage	5 Go	Les fichiers actuellement conservés
Téléchargement	100 Go / mois	Les octets servis par `GET /api/files/{id}`
Calcul	40 h / mois	Le temps d’exécution cumulé des scripts du bac à sable

La page Fichiers du portail affiche les trois jauges, et prévient avant qu’un plafond soit atteint. Une fois le plafond franchi, la production de fichiers s’arrête : le modèle vous le dit dans sa réponse plutôt que d’échouer en silence.

Deux leviers pour repartir : supprimer des fichiers ou raccourcir la conservation (l’espace se libère immédiatement dans le premier cas, au prochain passage de la purge dans le second). Si votre usage dépasse durablement ces plafonds, contactez-nous : ils se relèvent par compte.

Limites

Un fichier ne dépasse pas 15 Mo, et une exécution en produit au plus 10.
Une feuille est plafonnée à 100 000 lignes. Au-delà, il s’agit d’un export de base de données, pas d’un livrable : filtrez ou agrégez en amont.
Un diaporama est plafonné à 100 diapositives et 20 puces par diapositive. Sa mise en page est sobre et fixe : appliquez votre thème dans PowerPoint si vous en avez un.
Le PDF n’est pas encore proposé. Un document Word s’exporte en PDF depuis Word ou LibreOffice.
Le .ppt binaire (Office 97-2003) non plus : plus aucune bibliothèque ne le produit, et PowerPoint ouvre le .pptx depuis 2007.