Fichiers, projets et connaissances

Ces ressources donnent au modèle de quoi travailler. Les fichiers sont des documents téléversés que vous joignez à un message ou à une exécution. Les projets regroupent des chats, des prompts et des fichiers autour d’instructions communes et d’un modèle par défaut. Les bases de connaissances sont des arborescences de dossiers dont les documents sont indexés pour la recherche et cités dans les réponses. Les équipes sont des groupes au sein de votre espace de travail, avec lesquels vous partagez des projets, des bases de connaissances et des conversations.

Tous les chemins sont relatifs à https://api.stickyprompts.com/api/v1. Chaque requête s’exécute en tant que l’utilisateur propriétaire de la clé API : tous les contrôles de propriété, de partage et de rôle dans l’espace de travail s’appliquent donc à cet utilisateur.

Conventions

• Les objets comportent les champs de base ID, CreatedAt, UpdatedAt et DeletedAt (null pour les enregistrements actifs), avec une majuscule initiale, à côté de champs en snake_case.
• Les endpoints paginés lisent page (par défaut 1) et size (par défaut 10) et renseignent les headers de réponse X-Total-Count, X-Page et X-Page-Size. Voir Erreurs, pagination et quotas.
• Les erreurs ont la forme {"error": "message"}. Les erreurs de quota ont la forme 429 {"error": "Quota exceeded", "reason": "<reason>"}.

Fichiers

L’objet File

Tous les endpoints de téléversement renvoient le même objet File.

{
  "ID": 4812,
  "CreatedAt": "2026-09-28T09:14:03.512Z",
  "UpdatedAt": "2026-09-28T09:14:03.512Z",
  "DeletedAt": null,
  "name": "northwind-q3-report.pdf",
  "path": "https://<storage-host>/<bucket>/231/k9Tq2vX8bLmN3pRs7wYz4cDf6gHj1kLm.pdf",
  "preview_path": "",
  "public_path": "",
  "user_id": 231,
  "workspace_id": 17,
  "project_id": null,
  "fileType": "file_search",
  "partial": false
}

Comment fileType est déduit. La correspondance des extensions est sensible à la casse : REPORT.PDF tombe donc dans code_interpreter.

• image : .png .jpg .jpeg .gif .webp .bmp .tiff .tif .ico .heic .heif .jfif .avif .svg
• file_search : .c .cc .cpp .h .hpp .cs .css .scss .less .doc .docx .go .html .java .js .jsx .ts .tsx .vue .json .md .pdf .php .pptx .py .rb .sh .bat .ps1 .tex .txt .xml .yaml .yml .toml .ini .log .rtf .odt .rst .sql .kt .swift .rs .r .m .lua .pl
• spreadsheet : .xlsx .xlsm .xlam .xltm .xltx .xls .csv .tsv .ods .ots .numbers
• code_interpreter : tout le reste

POST /file

Téléverse un ou plusieurs fichiers dans votre bibliothèque de fichiers personnelle. Le téléversement est synchrone : à l’arrivée de la réponse, chaque fichier est stocké et possède un identifiant. Il n’existe pas d’équivalent MCP pour le téléversement.

Le code de l’API n’impose ici ni limite de taille de fichier ni liste d’extensions autorisées ; toute limite que vous rencontrez provient de l’infrastructure placée devant l’API.

curl -X POST https://api.stickyprompts.com/api/v1/file \
  -H "Authorization: Bearer $STICKY_API_KEY" \
  -F "upload[]=@northwind-q3-report.pdf" \
  -F "upload[]=@pricing.xlsx"

import os, requests

with open("northwind-q3-report.pdf", "rb") as a, open("pricing.xlsx", "rb") as b:
    r = requests.post(
        "https://api.stickyprompts.com/api/v1/file",
        headers={"Authorization": f"Bearer {os.environ['STICKY_API_KEY']}"},
        files=[("upload[]", a), ("upload[]", b)],
    )
r.raise_for_status()
for f in r.json():
    print(f["ID"], f["name"], f["fileType"])

import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("upload[]", new Blob([await readFile("northwind-q3-report.pdf")]), "northwind-q3-report.pdf");
form.append("upload[]", new Blob([await readFile("pricing.xlsx")]), "pricing.xlsx");

const files = await fetch("https://api.stickyprompts.com/api/v1/file", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.STICKY_API_KEY}` },
  body: form,
}).then((r) => r.json());
console.log(files.map((f) => [f.ID, f.fileType]));

Réponse. 200 avec un tableau d’objets File, dans l’ordre de téléversement.

Erreurs. 500 {"error": "could not upload files"} lorsque le corps n’est pas un multipart valide ou que le stockage échoue.

Utiliser un fichier téléversé

• Dans un message de conversation ou une exécution : "attachments": [{"id": 4812, "type": "file"}]. Ajoutez "temp": true pour ne le joindre qu’à cet appel. Voir Conversations et messages.
• Sur un prompt : POST /prompt/:id/file avec {"file_ids": [4812]}. Voir Prompts et exécutions.
• Pour le traitement de feuilles de calcul : transmettez-le comme file_id à POST /xlsx/start-process. Voir Modèles et médias.

GET /file

Liste tous les fichiers que vous avez téléversés, y compris ceux téléversés dans des projets et des bases de connaissances, ainsi que les feuilles de calcul générées en sortie. Aucun ordre de tri explicite.

Réponse. 200 avec un tableau d’objets File.

DELETE /file/:id

Supprime un fichier que vous avez téléversé : le retire du stockage (avec son éventuel aperçu) et procède à une suppression logique (soft delete) de l’enregistrement.

Réponse. 204, sans corps.

Erreurs. 400 {"error": "Invalid file ID"}, 404 {"error": "File not found"}, 403 {"error": "You do not have permission to delete this file"} (vous n’êtes pas l’auteur du téléversement), 502 {"error": "Failed to delete file"}.

POST /file/:id/public

Crée ou remplace un slug de partage public pour un fichier que vous avez téléversé. Un nouvel appel génère un nouveau slug et invalide l’ancien. Toute personne disposant du slug peut appeler GET /public/file/:slug sans authentification ; cet appel renvoie l’objet File, path compris (et 404 {"error": "File not found"} une fois le partage révoqué). L’API ne définit pas de format d’URL de partage au-delà du slug.

Réponse. 200 avec l’objet File, dont public_path contient un nouveau slug de 32 caractères, par exemple "Qx7_mB2kLr9-TtZwP4nV8cHd3JfG6sYq".

Erreurs. 400 Invalid file ID, 404 File not found, 403 {"error": "You do not have permission to share this file"}.

DELETE /file/:id/public

Révoque le lien public en vidant public_path.

Réponse. 204. Erreurs. 400 Invalid file ID, 404 File not found, 403 {"error": "You do not have permission to modify this file"}.

Projets

Un projet regroupe des conversations, des prompts et des fichiers, et porte des instructions et un modèle par défaut : c’est le pendant API des Projets. Chaque :id accepte l’ID numérique ou le slug. Les fichiers téléversés dans un projet sont automatiquement joints, pour l’appel concerné uniquement, aux conversations démarrées dans le projet (utilisez le header X-Project-ID sur les endpoints de conversation).

Modèle d’accès

• Le propriétaire peut tout faire. Lui seul peut supprimer le projet ou modifier son partage.
• Les autres utilisateurs obtiennent l’accès par des partages avec tout l’espace de travail, avec des utilisateurs individuels ou avec des équipes ; les indicateurs (flags) effectifs correspondent à l’union de ces partages. Un partage donne un accès en lecture (voir le projet et ses fichiers, l’épingler). Indicateurs supplémentaires : prompt_management (gérer ses prompts), file_management (téléverser et supprimer des fichiers) et project_management (le modifier avec PATCH).

L’objet Project

{
  "ID": 305,
  "CreatedAt": "2026-09-01T12:00:00Z",
  "UpdatedAt": "2026-09-27T16:40:00Z",
  "DeletedAt": null,
  "slug": "k7Tq2vX",
  "name": "Northwind Launch",
  "description": "Everything for the Q4 launch",
  "instructions": "Answer in British English. Keep it short.",
  "color": "#3B82F6",
  "icon": "rocket",
  "ai_model_id": null,
  "auto_model_type": "best",
  "user_id": 231,
  "is_pinned": false,
  "has_files": true,
  "current_user_permission": { "prompt_management": false, "file_management": false, "project_management": false },
  "workspace_share": true,
  "workspace_share_flags": { "prompt_management": true, "file_management": false, "project_management": false },
  "user_shares": [
    { "user_id": 240, "user": { "ID": 240, "first_name": "Dora", "...": "..." },
      "flags": { "prompt_management": true, "file_management": true, "project_management": false } }
  ],
  "team_shares": [
    { "team_id": 12, "team": { "ID": 12, "name": "Marketing", "...": "..." },
      "flags": { "prompt_management": false, "file_management": true, "project_management": false } }
  ]
}

• icon doit être vide ou prendre l’une des valeurs folder rocket hat-glasses box flask-conical book-open briefcase circle-dollar-sign puzzle cpu plane cross database paw-print headset. color est une chaîne hexadécimale et n’est pas validée.
• Normalement, un seul des deux champs est renseigné : ai_model_id (un modèle fixe) ou auto_model_type (best, balanced, cheapest).
• ai_model, pin, files, conversations, prompts et has_files sont omis lorsqu’ils ne sont pas chargés.
• current_user_permission ne reflète que les indicateurs accordés par des partages ; le propriétaire dispose de tous les droits mais voit généralement toutes les valeurs à false.
• has_files, current_user_permission, user_shares et team_shares ne sont renseignés que par GET /project/:id. Ailleurs, has_files est omis, les indicateurs d’autorisation valent tous false et les listes de partage valent null.

POST /project

Crée un projet. Le modèle par défaut provient de vos préférences (modèle préféré ou mode automatique), ou à défaut du modèle par défaut de la plateforme. instructions ne peut pas être défini ici : utilisez PATCH.

curl -X POST https://api.stickyprompts.com/api/v1/project \
  -H "Authorization: Bearer $STICKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Northwind Launch", "description": "Everything for the Q4 launch", "icon": "rocket" }'

Réponse. 201 avec l’objet Project.

Erreurs. 400 ("Project name is required" ou une erreur de binding, "Invalid project icon"), 500 {"error": "Failed to create project"}.

GET /project

Liste les projets qui vous appartiennent ainsi que ceux partagés avec vous, du plus récent au plus ancien.

Réponse. 200 avec un tableau d’objets Project.

Le filtrage des accès est appliqué après la pagination : une page peut donc contenir moins de size éléments, et X-Total-Count peut dépasser ce que vous pouvez voir. is_pinned vaut toujours false dans cette liste : utilisez GET /project/pinned. Erreurs. 400 {"error": "Invalid is_shared parameter"}.

GET /project/pinned

Vos projets épinglés, du plus ancien épinglage au plus récent, avec is_pinned: true et pin renseigné. Sans pagination.

GET /project/:id

Renvoie l’objet Project complet.

Erreurs. 404 {"error": "Project not found"}, 403 {"error": "You don't have access to this project"}.

PATCH /project/:id

Met à jour un projet. Vous devez en être le propriétaire ou disposer de project_management. Tous les champs sont facultatifs, mais envoyez-en au moins un.

Réponse. 200 avec l’objet Project.

Erreurs. 400 pour Project name cannot be empty, only one of ai_model_id or auto_model_type may be set, invalid auto_model_type, Invalid project icon, No fields provided for update, ou un blocage lié aux données sensibles ({"error": "...", "code": "..."}) ; 404 Project not found ; 403 You don't have access to this project.

DELETE /project/:id

Supprime le projet ainsi que ses conversations, ses fichiers, ses épinglages, ses prompts et ses enregistrements de partage. Réservé au propriétaire.

Réponse. 204. Erreurs. 404 Project not found, 403 You don't have access to this project.

POST /project/:id/pin

Épingle ou désépingle un projet que vous pouvez consulter. 5 projets épinglés au maximum par utilisateur.

Réponse. 200 {"message": "Project pinned", "pinned": true} ou 200 {"message": "Project unpinned", "pinned": false}.

Erreurs. 400 {"error": "Maximum 5 projects can be pinned"}, 404, 403.

PATCH /project/:id/share_with_workspace

Partage le projet avec tout votre espace de travail, ou retire ce partage. Réservé au propriétaire ; vous devez appartenir à un espace de travail. Les indicateurs omis conservent leur valeur actuelle.

Réponse. 200 {"message": "Project shared with workspace"}, y compris lors du retrait du partage.

Erreurs. 403 {"error": "You don't have access to this project's share settings"}, 400 {"error": "User is not in a workspace"}, 404.

PATCH /project/:id/share_with_user

Partage le projet avec des utilisateurs individuels de votre espace de travail. Réservé au propriétaire.

{
  "shares": [
    { "user_id": 240, "share": true, "prompt_management": true, "file_management": true },
    { "user_id": 251, "share": false }
  ]
}

Les entrées sont appliquées dans l’ordre et la requête s’arrête à la première entrée en échec ; les entrées précédentes restent appliquées.

Réponse. 200 {"message": "Project sharing with users updated"}.

Erreurs. 404 {"error": "User not found"}, 400 {"error": "Target user is not in the same workspace"}, ainsi que les erreurs liées au propriétaire et à l’espace de travail indiquées plus haut.

PATCH /project/:id/share_with_team

Identique à share_with_user, mais les entrées utilisent team_id. L’équipe doit appartenir à votre espace de travail.

Réponse. 200 {"message": "Project sharing with teams updated"}.

Erreurs. 404 {"error": "Team not found"}, 400 {"error": "Target team is not in the same workspace"}.

POST /project/:id/file

Téléverse des fichiers dans un projet. Vous devez en être le propriétaire ou disposer de file_management. Même fonctionnement que POST /file : synchrone, multipart/form-data, aucune limite de taille ni liste d’extensions autorisées dans le code de l’API. Chaque objet File obtenu a project_id renseigné.

Réponse. 200 avec un tableau d’objets File.

Erreurs. 404 Project not found, 403 {"error": "You don't have access to this project"}, 500 {"error": "could not upload files"}.

GET /project/:id/file

Liste les fichiers d’un projet. Chacun est un objet File complété de can_delete (vrai si vous pouvez gérer les fichiers du projet ou si vous avez téléversé le fichier). preview_path reprend la valeur de path lorsqu’il n’y a pas d’aperçu.

[
  {
    "ID": 4820,
    "name": "brand-guidelines.pdf",
    "path": "https://<storage-host>/<bucket>/231/Hq3...pdf",
    "preview_path": "https://<storage-host>/<bucket>/231/Hq3...pdf",
    "project_id": 305,
    "fileType": "file_search",
    "partial": false,
    "can_delete": true
  }
]

DELETE /project/:id/file/:fileId

Retire un enregistrement de fichier du projet. Il vous faut l’accès en lecture et, en plus, soit file_management (ou la propriété du projet), soit être l’auteur du téléversement du fichier.

Réponse. 200 {"message": "File deleted successfully"}.

Erreurs. 400 Invalid file ID, 404 Project not found, 404 {"error": "File not found in project"}, 403 {"error": "You don't have access to delete this file"}.

Bases de connaissances

Une base de connaissances est une arborescence de dossiers dont les documents sont découpés en fragments et indexés pour la recherche : c’est le pendant API des Bases de connaissances. Pour en utiliser une dans une conversation ou une exécution, transmettez knowledge_base_ids, éventuellement avec knowledge_base_limit_node_ids pour limiter la recherche à certains dossiers ou fichiers, ainsi que world_knowledge. Les identifiants de bases de connaissances sont uniquement numériques (pas de slugs).

Niveaux d’accès (current_user_permission et access_type des partages) :

Le propriétaire dispose toujours de kb_edit. Seul le propriétaire peut supprimer la base de connaissances ou modifier son partage. Les auteurs d’un téléversement peuvent toujours supprimer leurs propres fichiers.

L’objet Knowledge base

{
  "ID": 44,
  "CreatedAt": "2026-09-10T08:30:00Z",
  "UpdatedAt": "2026-09-10T08:30:00Z",
  "DeletedAt": null,
  "user_id": 231,
  "user": { "ID": 0, "email": "", "first_name": "", "...": "zero values" },
  "name": "Northwind Help Center",
  "description": "Policies, onboarding and FAQs",
  "color": "#10B981",
  "icon": "book-open",
  "document_count": 18,
  "member_count": 6,
  "current_user_permission": "kb_edit",
  "user_shares": [
    { "user_id": 240, "user": { "ID": 240, "first_name": "Dora", "...": "..." }, "access_type": "kb_upload", "added_at": "2026-09-11T09:00:00Z" }
  ],
  "team_shares": [
    { "team_id": 12, "team": { "ID": 12, "name": "Customer Support", "...": "..." }, "access_type": "kb_access", "added_at": "2026-09-11T09:05:00Z" }
  ]
}

L’objet propriétaire user n’est jamais chargé et ne contient toujours que des valeurs vides : utilisez user_id. document_count compte les fichiers, pas les dossiers. member_count n’est renvoyé que par GET et PUT sur une base de connaissances individuelle.

POST /knowledge-bases

Crée une base de connaissances.

Réponse. 201 avec la base de connaissances, document_count: 0, member_count: 0 et des listes de partage vides.

Erreurs. 400 {"error": "Knowledge base name is required"}, 400 {"error": "Invalid knowledge base icon"}.

GET /knowledge-bases

Liste toutes les bases de connaissances qui vous appartiennent ou auxquelles vous avez accès par un partage. Sans pagination. Chaque élément comporte les champs de la base de connaissances, plus document_count et current_user_permission (ni member_count, ni listes de partage).

GET /knowledge-bases/:id

Renvoie la base de connaissances complète. Nécessite au moins kb_access.

Erreurs. 400 Invalid knowledge base ID, 404 Knowledge base not found, 403 {"error": "You don't have access to this knowledge base"}.

PUT /knowledge-bases/:id

Remplace name, description, color et icon, avec le même corps et la même validation que POST. Une description omise est effacée. Nécessite kb_edit.

Réponse. 200 avec la base de connaissances complète.

Erreurs. Les mêmes que pour POST, plus 403 {"error": "You are not authorized to update this knowledge base"} et 404.

DELETE /knowledge-bases/:id

Supprime la base de connaissances avec tous ses dossiers, fichiers, objets stockés et données d’index. Réservé au propriétaire.

Réponse. 204. Erreurs. 404 Knowledge base not found, 403 {"error": "You are not authorized to delete this knowledge base"}.

PATCH /knowledge-bases/:id/share_with_user

Partage une base de connaissances avec des utilisateurs de votre espace de travail. Réservé au propriétaire ; vous devez appartenir à un espace de travail. Le retrait d’un partage déclenche une nouvelle vérification des agents qui utilisent cette base de connaissances.

{
  "shares": [
    { "user_id": 240, "access_type": "kb_upload" },
    { "user_id": 251, "access_type": null }
  ]
}

Les entrées sont appliquées dans l’ordre et le traitement s’arrête à la première entrée en échec.

Réponse. 200 {"message": "Knowledge base sharing with users updated"}.

Erreurs. 400 {"error": "User is not in a workspace"}, 403 {"error": "You don't have access to this knowledge base's share settings"}, 404 User not found, 400 Target user is not in the same workspace, 400 {"error": "Invalid access_type"}.

PATCH /knowledge-bases/:id/share_with_team

Identique à share_with_user, avec team_id au lieu de user_id.

Réponse. 200 {"message": "Knowledge base sharing with teams updated"}.

GET /knowledge-bases/:id/folders

Liste les enfants directs (dossiers et fichiers) d’un niveau de l’arborescence. C’est aussi l’endpoint à interroger pour suivre l’état d’indexation d’un fichier.

{
  "folders": [
    { "ID": 501, "name": "Policies", "parent_id": null, "size": 2483112,
      "CreatedAt": "2026-09-10T08:31:00Z", "UpdatedAt": "2026-09-10T08:31:00Z" }
  ],
  "files": [
    {
      "ID": 502,
      "name": "Northwind Refund Policy.md",
      "parent_id": null,
      "file_data_id": 4830,
      "file_data": { "ID": 4830, "name": "Northwind Refund Policy.md", "fileType": "file_search", "...": "..." },
      "size": 912334,
      "download_url": "https://<storage-host>/<bucket>/231/Zp8...md",
      "preview_url": "https://<storage-host>/<bucket>/231/Zp8...md",
      "status": "done",
      "status_progress": 100,
      "can_delete": true,
      "CreatedAt": "2026-09-10T08:32:00Z",
      "UpdatedAt": "2026-09-10T08:33:10Z"
    }
  ]
}

POST /knowledge-bases/:id/folders

Crée un dossier. Nécessite kb_edit. Les noms doivent être uniques au sein d’un même niveau ; dossiers et fichiers partagent le même espace de noms.

Réponse. 201. L’implémentation actuelle renvoie le dossier avec des valeurs vides ("ID": 0, name vide) alors qu’il a bien été créé : relancez GET /knowledge-bases/:id/folders pour obtenir l’identifiant du nouveau dossier.

Erreurs. 403 {"error": "You don't have access to create folders in this knowledge base"}, 400 {"error": "Folder name is required"}, 404 {"error": "Parent folder not found"}, 400 {"error": "Folder or document with this name already exists"}.

GET /knowledge-bases/:id/folders/:folderId

Renvoie un dossier : ID, name, parent_id, size, CreatedAt, UpdatedAt. Nécessite kb_access.

Erreurs. 404 {"error": "Folder not found"}, 403.

PATCH /knowledge-bases/:id/folders/:folderId

Renomme un dossier. Les dossiers ne peuvent pas être déplacés. Nécessite kb_edit.

Réponse. 200 avec le dossier mis à jour. Erreurs. 400 {"error": "Folder or document with this name already exists"}.

DELETE /knowledge-bases/:id/folders/:folderId

Supprime le dossier et tout ce qu’il contient, y compris les fichiers stockés et les données d’index. Nécessite kb_edit.

Réponse. 204.

POST /knowledge-bases/:id/files

Téléverse un document par requête. Nécessite kb_upload ou un niveau supérieur ; le quota est vérifié en premier. Le fichier doit porter un nom unique dans le dossier cible. Le code de l’API n’impose aucune limite de taille de fichier.

curl -X POST https://api.stickyprompts.com/api/v1/knowledge-bases/44/files \
  -H "Authorization: Bearer $STICKY_API_KEY" \
  -F "file=@Northwind Refund Policy.md" \
  -F "folder_id=501"

import os, time, requests

BASE = "https://api.stickyprompts.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['STICKY_API_KEY']}"}

with open("Northwind Refund Policy.md", "rb") as f:
    node = requests.post(f"{BASE}/knowledge-bases/44/files", headers=H,
                         files={"file": f}, data={"folder_id": "501"}).json()

# Wait until the document is indexed before relying on it
while True:
    listing = requests.get(f"{BASE}/knowledge-bases/44/folders", headers=H,
                           params={"parent_id": 501}).json()
    status = next(x["status"] for x in listing["files"] if x["ID"] == node["ID"])
    if status in ("done", "error"):
        print(status)
        break
    time.sleep(3)

import { readFile } from "node:fs/promises";

const BASE = "https://api.stickyprompts.com/api/v1";
const headers = { Authorization: `Bearer ${process.env.STICKY_API_KEY}` };

const form = new FormData();
form.append("file", new Blob([await readFile("Northwind Refund Policy.md")]), "Northwind Refund Policy.md");
form.append("folder_id", "501");
const node = await fetch(`${BASE}/knowledge-bases/44/files`, { method: "POST", headers, body: form }).then((r) => r.json());

for (;;) {
  const { files } = await fetch(`${BASE}/knowledge-bases/44/folders?parent_id=501`, { headers }).then((r) => r.json());
  const { status } = files.find((x) => x.ID === node.ID);
  if (status === "done" || status === "error") { console.log(status); break; }
  await new Promise((r) => setTimeout(r, 3000));
}

Réponse. 201 avec un nœud de fichier (de même forme que les éléments files ci-dessus) à l’état status: "uploading", status_progress: 0. Le téléversement, l’extraction du texte et l’indexation s’exécutent ensuite en arrière-plan :

Interrogez GET /knowledge-bases/:id/folders?parent_id=<folder_id> jusqu’à ce que le fichier soit à l’état done avant de compter sur lui pour la recherche.

Erreurs. 403 {"error": "You don't have access to upload files to this knowledge base"}, 429 (quota dépassé), 400 {"error": "File is required"}, 400 {"error": "Invalid folder ID"}, 404 {"error": "Parent folder not found"}, 400 {"error": "File extension not allowed. Allowed extensions: .txt, .md, ..."}, 400 {"error": "Folder or document with this name already exists"}.

DELETE /knowledge-bases/:id/files/:fileId

Supprime un nœud de document, son fichier stocké et ses données d’index. Nécessite kb_edit, ou d’être l’auteur du téléversement du fichier.

Réponse. 204. Erreurs. 404 {"error": "File not found"}, 403 {"error": "You don't have access to delete this file"}.

Équipes

Les équipes existent au sein d’un espace de travail et servent de cibles de partage pour les projets, les bases de connaissances et les conversations. Les rôles d’équipe sont owner et member ; dans les listes à l’échelle de l’espace de travail, none signifie que vous ne faites pas partie de l’équipe. Pour la vue d’administration, consultez Utilisateurs et équipes.

L’objet Team

{
  "ID": 12,
  "CreatedAt": "2026-09-05T10:00:00Z",
  "UpdatedAt": "2026-09-05T10:00:00Z",
  "DeletedAt": null,
  "workspace_id": 17,
  "workspace": { "ID": 0, "name": "", "...": "zero values" },
  "name": "Marketing",
  "description": "Campaigns and content",
  "color": "#F472B6",
  "member_count": 0
}

workspace n’est jamais chargé et contient toujours un objet aux valeurs vides. member_count n’a de sens que dans les endpoints de liste.

Un membre d’équipe est un objet User (ID, email, first_name, last_name, status, workspace_id, entre autres) auquel s’ajoute, au premier niveau, le role du membre.

POST /teams

Crée une équipe et vous y ajoute en tant que owner. Réservé au propriétaire ou aux administrateurs de l’espace de travail.

Réponse. 201 avec l’objet Team.

Erreurs. 403 {"error": "You are not authorized to create a team"}, 400 {"error": "Team name is required"}.

GET /teams

Les équipes dont vous faites partie, chacune avec member_count et current_user_role. Sans pagination. Renvoie null, et non [], si vous n’appartenez à aucune équipe.

GET /teams/all

Toutes les équipes de votre espace de travail, avec member_count et current_user_role (none si vous n’en êtes pas membre). Réservé au propriétaire ou aux administrateurs de l’espace de travail. Renvoie null si l’espace de travail n’a aucune équipe.

Erreurs. 404 {"error": "User is not a member of a workspace"}, 403 {"error": "You are not authorized to view all teams in this workspace"}.

GET /teams/:id/members

Liste les membres d’une équipe. Réservé aux membres de l’équipe ainsi qu’au propriétaire et aux administrateurs de l’espace de travail.

Réponse. 200 avec un tableau de membres d’équipe.

Erreurs. 400 Invalid team ID, 404 {"error": "Team not found"}, 403 {"error": "You are not authorized to view the members of this team"}.

PUT /teams/:id

Remplace les champs name, description et color d’une équipe ; description et color sont effacés s’ils sont omis. Réservé au propriétaire de l’équipe, ou au propriétaire ou à un administrateur de l’espace de travail.

Réponse. 200 avec l’équipe mise à jour.

Erreurs. 403 {"error": "You are not authorized to update this team"}, 400 Team name is required, 404 Team not found.

DELETE /teams/:id

Supprime une équipe qui compte au plus un membre. Réservé au propriétaire de l’équipe, ou au propriétaire ou à un administrateur de l’espace de travail.

Réponse. 204. Erreurs. 409 {"error": "Cannot delete a team with other members"}, 403 {"error": "You are not authorized to delete this team"}.

POST /teams/:id/members

Ajoute un membre de l’espace de travail à une équipe. Réservé au propriétaire de l’équipe, ou au propriétaire ou à un administrateur de l’espace de travail ; ajouter quelqu’un en tant que owner exige d’être propriétaire ou administrateur de l’espace de travail.

Réponse. 201. Le corps ne contient actuellement que role, tous les champs de l’utilisateur ayant des valeurs vides : appelez GET /teams/:id/members pour relire le membre.

Erreurs. 403 {"error": "You are not authorized to add a team member"}, 403 en cas d’ajout d’un propriétaire sans droits d’administrateur de l’espace de travail, 409 {"error": "User is already a member of this team"}, 404 {"error": "User not found"}, 403 {"error": "User is not a member of this workspace"}.

PATCH /teams/:id/members/:memberUserId

Modifie le rôle d’un membre. Changer role exige d’être propriétaire ou administrateur de l’espace de travail.

Réponse. 200 avec le membre de l’équipe et son nouveau rôle.

Erreurs. 404 {"error": "Team member not found"}, 403 {"error": "You are not authorized to update this team member"}, 403 {"error": "Updating the role of this team member requires workspace admin permissions"}.

DELETE /teams/:id/members/:memberUserId

Retire un membre. Réservé au propriétaire de l’équipe, ou au propriétaire ou à un administrateur de l’espace de travail ; retirer un owner exige d’être propriétaire ou administrateur de l’espace de travail. Vous ne pouvez pas vous retirer vous-même.

Réponse. 204.

Erreurs. 403 {"error": "You cannot remove yourself from a team"}, 403 {"error": "You are not authorized to remove this team member"}, 404 Team member not found, 403 {"error": "Removing an owner requires workspace admin permissions"}.

Voir aussi

• Conversations et messages - joindre des fichiers et des bases de connaissances à un message.
• Modèles et médias - traitement de feuilles de calcul sur un fichier téléversé.
• Référence des outils MCP - list_files, get_file, les outils de projets, de bases de connaissances et d’équipes.