File, progetti e conoscenza

Queste sono le risorse che danno a un modello materiale su cui lavorare. I file sono i caricamenti che alleghi a un messaggio o a un’esecuzione. I progetti raggruppano chat, prompt e file con istruzioni condivise e un modello predefinito. Le knowledge base sono alberi di cartelle con documenti indicizzati per il recupero e citati nelle risposte. I team sono gruppi all’interno del tuo workspace con cui condividi progetti, knowledge base e conversazioni.

Tutti i percorsi sono relativi a https://api.stickyprompts.com/api/v1. Ogni richiesta viene eseguita come l’utente proprietario della chiave API, quindi tutti i controlli su proprietà, condivisione e ruoli nel workspace si applicano a quell’utente.

Convenzioni

• Gli oggetti hanno i campi di base con l’iniziale maiuscola ID, CreatedAt, UpdatedAt e DeletedAt (null nei record attivi) accanto ai campi in snake_case.
• Gli endpoint paginati leggono page (predefinito 1) e size (predefinito 10) e impostano gli header di risposta X-Total-Count, X-Page e X-Page-Size. Consulta Errori, paginazione e quote.
• Gli errori hanno la forma {"error": "message"}. Gli errori di quota sono 429 {"error": "Quota exceeded", "reason": "<reason>"}.

File

L’oggetto File

Tutti gli endpoint di caricamento restituiscono lo stesso oggetto 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
}

Come viene ricavato fileType. Il confronto sull’estensione distingue tra maiuscole e minuscole, quindi REPORT.PDF ricade in 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: qualsiasi altra estensione

POST /file

Carica uno o più file nella tua libreria personale di file. Il caricamento è sincrono: quando arriva la risposta, ogni file è già salvato e ha un ID. Non esiste un equivalente MCP per il caricamento.

Qui il codice dell’API non impone limiti di dimensione né un elenco di estensioni consentite; qualsiasi limite tu incontri deriva dall’infrastruttura che sta davanti all’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]));

Risposta. 200 con un array di oggetti File, nell’ordine di caricamento.

Errori. 500 {"error": "could not upload files"} quando il corpo non è un multipart valido o il salvataggio nello storage non riesce.

Usare un file caricato

• In un messaggio di conversazione o in un’esecuzione: "attachments": [{"id": 4812, "type": "file"}]. Aggiungi "temp": true per allegarlo solo per quella chiamata. Consulta Conversazioni.
• Su un prompt: POST /prompt/:id/file con {"file_ids": [4812]}. Consulta Prompt ed esecuzioni.
• Per l’elaborazione di fogli di calcolo: passalo come file_id a POST /xlsx/start-process. Consulta Modelli e media.

GET /file

Elenca tutti i file che hai caricato, compresi quelli caricati in progetti e knowledge base e gli output generati dall’elaborazione dei fogli di calcolo. Non c’è un ordinamento esplicito.

Risposta. 200 con un array di oggetti File.

DELETE /file/:id

Elimina un file che hai caricato: lo rimuove dallo storage (insieme all’eventuale anteprima) ed esegue una soft delete del record.

Risposta. 204, senza corpo.

Errori. 400 {"error": "Invalid file ID"}, 404 {"error": "File not found"}, 403 {"error": "You do not have permission to delete this file"} (non sei tu ad averlo caricato), 502 {"error": "Failed to delete file"}.

POST /file/:id/public

Crea o sostituisce lo slug di condivisione pubblica di un file che hai caricato. Chiamandolo di nuovo si genera un nuovo slug e quello vecchio non è più valido. Chiunque abbia lo slug può chiamare GET /public/file/:slug senza autenticazione; la chiamata restituisce l’oggetto File, compreso path (e 404 {"error": "File not found"} dopo la revoca). L’API non definisce un formato di URL di condivisione a partire dallo slug.

Risposta. 200 con l’oggetto File, con public_path impostato su un nuovo slug di 32 caratteri come "Qx7_mB2kLr9-TtZwP4nV8cHd3JfG6sYq".

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

DELETE /file/:id/public

Revoca il link pubblico svuotando public_path.

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

Progetti

Un progetto raggruppa conversazioni, prompt e file, e porta con sé istruzioni predefinite e un modello predefinito: è il lato API dei Progetti. Ogni :id accetta l’ID numerico o lo slug. I file caricati in un progetto vengono allegati automaticamente, solo per quella chiamata, alle conversazioni avviate nel progetto (usa l’header X-Project-ID sugli endpoint delle conversazioni).

Modello di accesso

• Il proprietario può fare tutto. Solo il proprietario può eliminare il progetto o modificarne la condivisione.
• Gli altri ottengono l’accesso tramite condivisioni con l’intero workspace, con singoli utenti o con team; i flag effettivi sono l’unione di tutti. La condivisione dà accesso in visualizzazione (vedere il progetto e i suoi file, fissarlo). Flag aggiuntivi: prompt_management (gestire i suoi prompt), file_management (caricare ed eliminare file) e project_management (modificarlo con PATCH).

L’oggetto 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 deve essere vuoto oppure uno tra folder rocket hat-glasses box flask-conical book-open briefcase circle-dollar-sign puzzle cpu plane cross database paw-print headset. color è una stringa esadecimale e non viene validato.
• Di norma è impostato uno solo tra ai_model_id (un modello fisso) e auto_model_type (best, balanced, cheapest).
• ai_model, pin, files, conversations, prompts e has_files vengono omessi quando non sono caricati.
• current_user_permission riflette solo i flag concessi tramite condivisione; il proprietario ha pieni diritti ma di solito vede tutti i valori a false.
• has_files, current_user_permission, user_shares e team_shares vengono valorizzati solo da GET /project/:id. Altrove has_files viene omesso, i flag di autorizzazione sono tutti false e gli elenchi di condivisione sono null.

POST /project

Crea un progetto. Il modello predefinito deriva dalle tue preferenze (modello preferito o modalità automatica), altrimenti si usa il predefinito della piattaforma. Qui non puoi impostare instructions: usa 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" }'

Risposta. 201 con l’oggetto Project.

Errori. 400 ("Project name is required" o un errore di binding, "Invalid project icon"), 500 {"error": "Failed to create project"}.

GET /project

Elenca i progetti di cui sei proprietario più quelli condivisi con te, dal più recente.

Risposta. 200 con un array di oggetti Project.

Il filtro sugli accessi viene applicato dopo la paginazione, quindi una pagina può contenere meno di size elementi e X-Total-Count può essere superiore a quanto puoi vedere. In questo elenco is_pinned è sempre false: usa GET /project/pinned. Errori. 400 {"error": "Invalid is_shared parameter"}.

GET /project/pinned

I tuoi progetti fissati, a partire da quello fissato per primo, con is_pinned: true e pin valorizzato. Senza paginazione.

GET /project/:id

Restituisce l’oggetto Project completo.

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

PATCH /project/:id

Aggiorna un progetto. Devi esserne il proprietario o avere project_management. Tutti i campi sono facoltativi, ma inviane almeno uno.

Risposta. 200 con l’oggetto Project.

Errori. 400 per 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 o un blocco per dati sensibili ({"error": "...", "code": "..."}); 404 Project not found; 403 You don't have access to this project.

DELETE /project/:id

Elimina il progetto insieme alle sue conversazioni, ai file del progetto, ai pin, ai prompt e ai record di condivisione. Solo il proprietario.

Risposta. 204. Errori. 404 Project not found, 403 You don't have access to this project.

POST /project/:id/pin

Aggiunge o rimuove il tuo pin su un progetto che puoi visualizzare: ogni chiamata inverte lo stato. Ogni utente può fissare al massimo 5 progetti.

Risposta. 200 {"message": "Project pinned", "pinned": true} oppure 200 {"message": "Project unpinned", "pinned": false}.

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

PATCH /project/:id/share_with_workspace

Condivide il progetto con l’intero workspace o rimuove questa condivisione. Solo il proprietario; devi appartenere a un workspace. I flag che ometti mantengono il valore attuale.

Risposta. 200 {"message": "Project shared with workspace"}, anche quando rimuovi la condivisione.

Errori. 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

Condivide il progetto con singoli utenti del tuo workspace. Solo il proprietario.

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

Le voci vengono applicate in ordine e la richiesta si interrompe alla prima voce che fallisce; le voci precedenti restano applicate.

Risposta. 200 {"message": "Project sharing with users updated"}.

Errori. 404 {"error": "User not found"}, 400 {"error": "Target user is not in the same workspace"}, più gli errori su proprietario e workspace descritti sopra.

PATCH /project/:id/share_with_team

Uguale a share_with_user, ma le voci usano team_id. Il team deve appartenere al tuo workspace.

Risposta. 200 {"message": "Project sharing with teams updated"}.

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

POST /project/:id/file

Carica file in un progetto. Devi esserne il proprietario o avere file_management. Funziona come POST /file: sincrono, multipart/form-data, senza limiti di dimensione né elenco di estensioni consentite nel codice dell’API. Ogni File risultante ha project_id valorizzato.

Risposta. 200 con un array di oggetti File.

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

GET /project/:id/file

Elenca i file di un progetto. Ognuno è un oggetto File con in più can_delete (true se puoi gestire i file del progetto o se hai caricato tu il file). In assenza di anteprima, preview_path assume il valore di path.

[
  {
    "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

Rimuove il record di un file dal progetto. Ti serve l’accesso in visualizzazione e, in aggiunta, file_management (o la proprietà del progetto) oppure essere chi ha caricato il file.

Risposta. 200 {"message": "File deleted successfully"}.

Errori. 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"}.

Knowledge base

Una knowledge base è un albero di cartelle con documenti suddivisi in chunk e indicizzati per il recupero: è il lato API delle Knowledge base. Per usarne una in una conversazione o in un’esecuzione, passa knowledge_base_ids, eventualmente insieme a knowledge_base_limit_node_ids per limitare il recupero a cartelle o file specifici, e a world_knowledge. Gli ID delle knowledge base sono solo numerici (niente slug).

Livelli di accesso (current_user_permission e access_type delle condivisioni):

Il proprietario ha sempre kb_edit. Solo il proprietario può eliminare la knowledge base o modificarne la condivisione. Chi ha caricato un file può sempre eliminarlo.

L’oggetto 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’oggetto user del proprietario non viene mai caricato e contiene sempre valori zero: usa user_id. document_count conta i file, non le cartelle. member_count viene restituito solo da GET e PUT su una singola knowledge base.

POST /knowledge-bases

Crea una knowledge base.

Risposta. 201 con la knowledge base, document_count: 0, member_count: 0 ed elenchi di condivisione vuoti.

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

GET /knowledge-bases

Elenca tutte le knowledge base di cui sei proprietario o a cui puoi accedere tramite una condivisione. Senza paginazione. Ogni elemento contiene i campi della knowledge base più document_count e current_user_permission (niente member_count né elenchi di condivisione).

GET /knowledge-bases/:id

Restituisce la knowledge base completa. Richiede almeno kb_access.

Errori. 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

Sostituisce name, description, color e icon, con lo stesso corpo e la stessa validazione di POST. Una description omessa viene svuotata. Richiede kb_edit.

Risposta. 200 con la knowledge base completa.

Errori. Come per POST, più 403 {"error": "You are not authorized to update this knowledge base"} e 404.

DELETE /knowledge-bases/:id

Elimina la knowledge base con tutte le sue cartelle, i file, gli oggetti salvati e i dati di indice. Solo il proprietario.

Risposta. 204. Errori. 404 Knowledge base not found, 403 {"error": "You are not authorized to delete this knowledge base"}.

PATCH /knowledge-bases/:id/share_with_user

Condivide una knowledge base con utenti del tuo workspace. Solo il proprietario; devi appartenere a un workspace. La rimozione di una condivisione avvia una nuova verifica degli agenti che usano questa knowledge base.

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

Le voci vengono applicate in ordine e l’elaborazione si interrompe alla prima voce che fallisce.

Risposta. 200 {"message": "Knowledge base sharing with users updated"}.

Errori. 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

Uguale a share_with_user, con team_id al posto di user_id.

Risposta. 200 {"message": "Knowledge base sharing with teams updated"}.

GET /knowledge-bases/:id/folders

Elenca i figli diretti, cartelle e file, di un livello dell’albero. È anche l’endpoint da interrogare per conoscere lo stato di indicizzazione di un file.

{
  "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

Crea una cartella. Richiede kb_edit. I nomi devono essere univoci tra elementi dello stesso livello; cartelle e file condividono lo stesso spazio dei nomi.

Risposta. 201. L’implementazione attuale restituisce la cartella con valori zero ("ID": 0, name vuoto) anche se è stata creata: richiedi di nuovo l’elenco con GET /knowledge-bases/:id/folders per ottenere l’ID della nuova cartella.

Errori. 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

Restituisce una cartella: ID, name, parent_id, size, CreatedAt, UpdatedAt. Richiede kb_access.

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

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

Rinomina una cartella. Le cartelle non si possono spostare. Richiede kb_edit.

Risposta. 200 con la cartella aggiornata. Errori. 400 {"error": "Folder or document with this name already exists"}.

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

Elimina la cartella e tutto ciò che contiene, compresi i file salvati e i dati di indice. Richiede kb_edit.

Risposta. 204.

POST /knowledge-bases/:id/files

Carica un documento per richiesta. Richiede kb_upload o superiore; prima viene verificata la quota. Il file deve avere un nome univoco all’interno della cartella di destinazione. Il codice dell’API non impone limiti di dimensione.

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));
}

Risposta. 201 con un nodo file (la stessa forma degli elementi files qui sopra) con status: "uploading", status_progress: 0. Caricamento, estrazione del testo e indicizzazione proseguono poi in background:

Interroga GET /knowledge-bases/:id/folders?parent_id=<folder_id> finché il file non è done, prima di farvi affidamento nel recupero.

Errori. 403 {"error": "You don't have access to upload files to this knowledge base"}, 429 quota superata, 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

Elimina un nodo documento, il file salvato e i suoi dati di indice. Richiede kb_edit, oppure essere chi ha caricato il file.

Risposta. 204. Errori. 404 {"error": "File not found"}, 403 {"error": "You don't have access to delete this file"}.

Team

I team esistono all’interno di un workspace e sono destinatari di condivisione per progetti, knowledge base e conversazioni. I ruoli di team sono owner (proprietario) e member (membro); negli elenchi a livello di workspace, none significa che non fai parte del team. Per la vista da amministratore, consulta Utenti e team.

L’oggetto 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 non viene mai caricato ed è sempre un oggetto con valori zero. member_count ha senso solo negli endpoint di elenco.

Un membro del team è un oggetto User (ID, email, first_name, last_name, status, workspace_id e altro) con in più, al primo livello, il role del membro.

POST /teams

Crea un team e ti aggiunge come suo owner. Solo il proprietario o un amministratore del workspace.

Risposta. 201 con l’oggetto Team.

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

GET /teams

I team di cui fai parte, ognuno con member_count e current_user_role. Senza paginazione. Se non fai parte di alcun team restituisce null, non [].

GET /teams/all

Tutti i team del tuo workspace, con member_count e current_user_role (none se non ne sei membro). Solo il proprietario o un amministratore del workspace. Restituisce null se il workspace non ha team.

Errori. 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

Elenca i membri di un team. Solo i membri del team e i proprietari o amministratori del workspace.

Risposta. 200 con un array di membri del team.

Errori. 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

Sostituisce name, description e color di un team; description e color omessi vengono svuotati. Proprietario del team, oppure proprietario o amministratore del workspace.

Risposta. 200 con il Team aggiornato.

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

DELETE /teams/:id

Elimina un team che ha al massimo un membro. Proprietario del team, oppure proprietario o amministratore del workspace.

Risposta. 204. Errori. 409 {"error": "Cannot delete a team with other members"}, 403 {"error": "You are not authorized to delete this team"}.

POST /teams/:id/members

Aggiunge un membro del workspace a un team. Proprietario del team, oppure proprietario o amministratore del workspace; per aggiungere qualcuno come owner servono i diritti di proprietario o amministratore del workspace.

Risposta. 201. Al momento il corpo contiene solo role, con tutti i campi dell’utente a valori zero: chiama GET /teams/:id/members per rileggere il membro.

Errori. 403 {"error": "You are not authorized to add a team member"}, 403 quando aggiungi un proprietario senza diritti di amministratore del workspace, 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

Cambia il ruolo di un membro. Per cambiare role servono i diritti di proprietario o amministratore del workspace.

Risposta. 200 con il membro del team e il nuovo ruolo.

Errori. 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

Rimuove un membro. Proprietario del team, oppure proprietario o amministratore del workspace; per rimuovere un owner servono i diritti di proprietario o amministratore del workspace. Non puoi rimuovere te stesso.

Risposta. 204.

Errori. 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"}.

Pagine correlate

• Conversazioni e messaggi: allegare file e knowledge base a un messaggio.
• Modelli e media: elaborazione di fogli di calcolo su un file caricato.
• Riferimento degli strumenti MCP: list_files, get_file e gli strumenti per progetti, knowledge base e team.