Archivos, proyectos y conocimiento

Estos son los recursos que le dan a un modelo material con el que trabajar. Los archivos son elementos subidos que adjuntas a un mensaje o a una ejecución. Los proyectos agrupan chats, prompts y archivos con instrucciones compartidas y un modelo predeterminado. Las bases de conocimiento son árboles de carpetas con documentos que se indexan para la recuperación y se citan en las respuestas. Los equipos son grupos dentro de tu espacio de trabajo con los que compartes proyectos, bases de conocimiento y conversaciones.

Todas las rutas son relativas a https://api.stickyprompts.com/api/v1. Cada petición se ejecuta como el usuario propietario de la clave de API, así que todas las comprobaciones de propiedad, uso compartido y rol en el espacio de trabajo se aplican a ese usuario.

Convenciones

• Los objetos incluyen los campos base con mayúscula inicial ID, CreatedAt, UpdatedAt y DeletedAt (null en los registros activos) junto a campos en snake_case.
• Los endpoints paginados leen page (valor predeterminado 1) y size (valor predeterminado 10), y devuelven los headers de respuesta X-Total-Count, X-Page y X-Page-Size. Consulta Errores, paginación y cuotas.
• Los errores tienen la forma {"error": "message"}. Los errores de cuota son 429 {"error": "Quota exceeded", "reason": "<reason>"}.

Archivos

El objeto File

Todos los endpoints de subida devuelven el mismo objeto 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
}

Cómo se deduce fileType. La comparación de la extensión distingue entre mayúsculas y minúsculas, así que REPORT.PDF acaba en 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: cualquier otra

POST /file

Sube uno o varios archivos a tu biblioteca personal de archivos. La subida es síncrona: cuando llega la respuesta, cada archivo ya está almacenado y tiene un ID. No hay ningún equivalente en MCP para subir archivos.

Aquí el código de la API no impone ningún límite de tamaño ni ninguna lista de extensiones permitidas; cualquier límite con el que te encuentres procede de la infraestructura que hay delante de la 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]));

Respuesta. 200 con un array de objetos File, en el orden de subida.

Errores. 500 {"error": "could not upload files"} cuando el cuerpo no es un multipart válido o falla el almacenamiento.

Cómo usar un archivo subido

• En un mensaje de conversación o en una ejecución: "attachments": [{"id": 4812, "type": "file"}]. Añade "temp": true para adjuntarlo solo en esa llamada. Consulta Conversaciones y mensajes.
• En un prompt: POST /prompt/:id/file con {"file_ids": [4812]}. Consulta Prompts y ejecuciones.
• Para el procesamiento de hojas de cálculo: pásalo como file_id a POST /xlsx/start-process. Consulta Modelos y multimedia.

GET /file

Lista todos los archivos que has subido, incluidos los subidos a proyectos y bases de conocimiento y los resultados generados del procesamiento de hojas de cálculo. No tienen un orden explícito.

Respuesta. 200 con un array de objetos File.

DELETE /file/:id

Elimina un archivo que has subido: lo borra del almacenamiento (junto con su vista previa, si la tiene) y aplica un borrado lógico al registro.

Respuesta. 204, sin cuerpo.

Errores. 400 {"error": "Invalid file ID"}, 404 {"error": "File not found"}, 403 {"error": "You do not have permission to delete this file"} (no eres quien lo subió), 502 {"error": "Failed to delete file"}.

POST /file/:id/public

Crea o sustituye un slug público para compartir un archivo que has subido. Si vuelves a llamarlo, se genera un slug nuevo y el anterior deja de ser válido. Cualquiera que tenga el slug puede llamar a GET /public/file/:slug sin autenticación; esa llamada devuelve el objeto File, incluido path (y 404 {"error": "File not found"} una vez revocado). La API no define ningún formato de URL para compartir aparte del slug.

Respuesta. 200 con el objeto File y con public_path rellenado con un nuevo slug de 32 caracteres, como "Qx7_mB2kLr9-TtZwP4nV8cHd3JfG6sYq".

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

DELETE /file/:id/public

Revoca el enlace público vaciando public_path.

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

Proyectos

Un proyecto agrupa conversaciones, prompts y archivos, y lleva asociados unas instrucciones y un modelo predeterminados: es la versión en la API de los Proyectos. Cada :id acepta el ID numérico o el slug. Los archivos subidos a un proyecto se adjuntan automáticamente, solo para esa llamada, a las conversaciones iniciadas en el proyecto (usa el header X-Project-ID en los endpoints de conversación).

Modelo de acceso

• El propietario puede hacerlo todo. Solo el propietario puede eliminar el proyecto o cambiar cómo se comparte.
• Los demás obtienen acceso cuando el proyecto se comparte con todo el espacio de trabajo, con usuarios concretos o con equipos; los indicadores efectivos son la unión de todos ellos. Que te compartan un proyecto te da acceso de lectura (ver el proyecto y sus archivos, y fijarlo). Indicadores adicionales: prompt_management (gestionar sus prompts), file_management (subir y eliminar archivos) y project_management (editarlo con PATCH).

El objeto 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 debe estar vacío o ser uno de estos valores: folder rocket hat-glasses box flask-conical book-open briefcase circle-dollar-sign puzzle cpu plane cross database paw-print headset. color es una cadena hexadecimal y no se valida.
• Normalmente se rellena exactamente uno de los dos: ai_model_id (un modelo fijo) o auto_model_type (best, balanced, cheapest).
• ai_model, pin, files, conversations, prompts y has_files se omiten cuando no se cargan.
• current_user_permission solo refleja los indicadores concedidos al compartir; el propietario tiene todos los derechos, pero normalmente ve todos los valores en false.
• has_files, current_user_permission, user_shares y team_shares solo los rellena GET /project/:id. En los demás casos, has_files se omite, los indicadores de permiso son todos false y las listas de uso compartido son null.

POST /project

Crea un proyecto. El modelo predeterminado se toma de tus preferencias (modelo preferido o modo automático) y, si no hay ninguno, del modelo predeterminado de la plataforma. Aquí no se puede definir 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" }'

Respuesta. 201 con el objeto Project.

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

GET /project

Lista los proyectos de los que eres propietario y los que se han compartido contigo, empezando por los más recientes.

Respuesta. 200 con un array de objetos Project.

El filtrado por acceso se aplica después de la paginación, así que una página puede contener menos de size elementos y X-Total-Count puede ser mayor que lo que puedes ver. En esta lista, is_pinned es siempre false: usa GET /project/pinned. Errores. 400 {"error": "Invalid is_shared parameter"}.

GET /project/pinned

Tus proyectos fijados, empezando por el que fijaste primero, con is_pinned: true y pin rellenado. Sin paginación.

GET /project/:id

Devuelve el objeto Project completo.

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

PATCH /project/:id

Actualiza un proyecto. Tienes que ser el propietario o tener project_management. Todos los campos son opcionales, pero envía al menos uno.

Respuesta. 200 con el objeto Project.

Errores. 400 por 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 bloqueo por datos sensibles ({"error": "...", "code": "..."}); 404 Project not found; 403 You don't have access to this project.

DELETE /project/:id

Elimina el proyecto junto con sus conversaciones, archivos del proyecto, fijaciones, prompts y registros de uso compartido. Solo puede hacerlo el propietario.

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

POST /project/:id/pin

Fija o deja de fijar (alterna) un proyecto que puedes ver. Cada usuario puede tener como máximo 5 proyectos fijados.

Respuesta. 200 {"message": "Project pinned", "pinned": true} o 200 {"message": "Project unpinned", "pinned": false}.

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

PATCH /project/:id/share_with_workspace

Comparte el proyecto con todo tu espacio de trabajo o retira ese uso compartido. Solo puede hacerlo el propietario, y tiene que pertenecer a un espacio de trabajo. Los indicadores que omitas conservan su valor actual.

Respuesta. 200 {"message": "Project shared with workspace"}, también al dejar de compartir.

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

Comparte el proyecto con usuarios concretos de tu espacio de trabajo. Solo puede hacerlo el propietario.

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

Las entradas se aplican en orden y la petición se detiene en la primera entrada que falla; las entradas anteriores siguen aplicadas.

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

Errores. 404 {"error": "User not found"}, 400 {"error": "Target user is not in the same workspace"}, además de los errores de propietario y de espacio de trabajo anteriores.

PATCH /project/:id/share_with_team

Igual que share_with_user, pero las entradas usan team_id. El equipo debe pertenecer a tu espacio de trabajo.

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

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

POST /project/:id/file

Sube archivos a un proyecto. Tienes que ser el propietario o tener file_management. Funciona igual que POST /file: síncrono, multipart/form-data y sin límite de tamaño ni lista de extensiones permitidas en el código de la API. Cada File resultante tiene project_id rellenado.

Respuesta. 200 con un array de objetos File.

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

GET /project/:id/file

Lista los archivos de un proyecto. Cada uno es un objeto File más can_delete (true si puedes gestionar los archivos del proyecto o si subiste tú el archivo). preview_path toma el valor de path cuando no hay vista previa.

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

Quita un registro de archivo del proyecto. Necesitas acceso de lectura y, además, tener file_management (o ser el propietario del proyecto) o haber subido el archivo.

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

Errores. 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 conocimiento

Una base de conocimiento es un árbol de carpetas con documentos que se dividen en fragmentos y se indexan para la recuperación: es la versión en la API de las Bases de conocimiento. Para usar una en una conversación o en una ejecución, pasa knowledge_base_ids, opcionalmente con knowledge_base_limit_node_ids para limitar la recuperación a carpetas o archivos concretos, y world_knowledge. Los ID de las bases de conocimiento son solo numéricos (no hay slugs).

Niveles de acceso (current_user_permission y el access_type de cada uso compartido):

El propietario siempre tiene kb_edit. Solo el propietario puede eliminar la base de conocimiento o cambiar cómo se comparte. Quien sube un archivo siempre puede eliminarlo.

El objeto 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" }
  ]
}

El objeto del propietario, user, nunca se carga y siempre tiene valores vacíos: usa user_id. document_count cuenta archivos, no carpetas. member_count solo lo devuelven GET y PUT sobre una base de conocimiento concreta.

POST /knowledge-bases

Crea una base de conocimiento.

Respuesta. 201 con la base de conocimiento, document_count: 0, member_count: 0 y listas de uso compartido vacías.

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

GET /knowledge-bases

Lista todas las bases de conocimiento de las que eres propietario o a las que puedes acceder porque se han compartido contigo. Sin paginación. Cada elemento incluye los campos de la base de conocimiento más document_count y current_user_permission (sin member_count ni listas de uso compartido).

GET /knowledge-bases/:id

Devuelve la base de conocimiento completa. Requiere al menos kb_access.

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

Sustituye name, description, color e icon, con el mismo cuerpo y la misma validación que POST. Si se omite description, se vacía. Requiere kb_edit.

Respuesta. 200 con la base de conocimiento completa.

Errores. Los mismos que en POST, además de 403 {"error": "You are not authorized to update this knowledge base"} y 404.

DELETE /knowledge-bases/:id

Elimina la base de conocimiento con todas sus carpetas, archivos, objetos almacenados y datos del índice. Solo puede hacerlo el propietario.

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

PATCH /knowledge-bases/:id/share_with_user

Comparte una base de conocimiento con usuarios de tu espacio de trabajo. Solo puede hacerlo el propietario, y tiene que estar en un espacio de trabajo. Al retirar un uso compartido, se vuelven a comprobar los agentes que usan esta base de conocimiento.

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

Las entradas se aplican en orden y el procesamiento se detiene en la primera entrada que falla.

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

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

Igual que share_with_user, con team_id en lugar de user_id.

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

GET /knowledge-bases/:id/folders

Lista los elementos que cuelgan directamente de un nivel del árbol, tanto carpetas como archivos. También es el endpoint que debes consultar para conocer el estado de indexación de un archivo.

{
  "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 carpeta. Requiere kb_edit. Los nombres deben ser únicos entre los elementos del mismo nivel; carpetas y archivos comparten el mismo espacio de nombres.

Respuesta. 201. La implementación actual devuelve la carpeta con valores vacíos ("ID": 0, name vacío) aunque se haya creado: vuelve a listar con GET /knowledge-bases/:id/folders para obtener el ID de la nueva carpeta.

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

Devuelve una carpeta: ID, name, parent_id, size, CreatedAt, UpdatedAt. Requiere kb_access.

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

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

Cambia el nombre de una carpeta. Las carpetas no se pueden mover. Requiere kb_edit.

Respuesta. 200 con la carpeta actualizada. Errores. 400 {"error": "Folder or document with this name already exists"}.

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

Elimina la carpeta y todo lo que contiene, incluidos los archivos almacenados y los datos del índice. Requiere kb_edit.

Respuesta. 204.

POST /knowledge-bases/:id/files

Sube un documento por petición. Requiere kb_upload o un nivel superior; antes se comprueba la cuota. El archivo debe tener un nombre único dentro de la carpeta de destino. El código de la API no impone ningún límite de tamaño.

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

Respuesta. 201 con un nodo de archivo (con la misma estructura que los elementos de files de arriba) en status: "uploading", status_progress: 0. Después, la subida, la extracción de texto y la indexación se ejecutan en segundo plano:

Consulta GET /knowledge-bases/:id/folders?parent_id=<folder_id> hasta que el archivo esté en done antes de usarlo en la recuperación.

Errores. 403 {"error": "You don't have access to upload files to this knowledge base"}, 429 por cuota superada, 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 de documento, su archivo almacenado y sus datos del índice. Requiere kb_edit o haber subido el archivo.

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

Equipos

Los equipos existen dentro de un espacio de trabajo y sirven como destinatarios con los que compartir proyectos, bases de conocimiento y conversaciones. Los roles de equipo son owner y member; en los listados de todo el espacio de trabajo, none significa que no estás en el equipo. Consulta Usuarios y equipos para ver la parte de administración.

El objeto 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 nunca se carga y siempre es un objeto con valores vacíos. member_count solo tiene sentido en los endpoints de listado.

Un miembro del equipo es un objeto User (ID, email, first_name, last_name, status, workspace_id y otros campos) con el role del miembro añadido en el nivel superior.

POST /teams

Crea un equipo y te añade como su owner. Solo puede hacerlo el propietario o un administrador del espacio de trabajo.

Respuesta. 201 con el objeto Team.

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

GET /teams

Los equipos a los que perteneces, cada uno con member_count y current_user_role. Sin paginación. Devuelve null, no [], cuando no estás en ningún equipo.

GET /teams/all

Todos los equipos de tu espacio de trabajo, con member_count y current_user_role (none si no eres miembro). Solo para el propietario o los administradores del espacio de trabajo. Devuelve null cuando el espacio de trabajo no tiene equipos.

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

Lista los miembros de un equipo. Solo para los miembros del equipo y para el propietario o los administradores del espacio de trabajo.

Respuesta. 200 con un array de miembros del equipo.

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

Sustituye el name, la description y el color de un equipo; si se omiten description y color, se vacían. Puede hacerlo el propietario del equipo, o el propietario o un administrador del espacio de trabajo.

Respuesta. 200 con el Team actualizado.

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

DELETE /teams/:id

Elimina un equipo que tiene como máximo un miembro. Puede hacerlo el propietario del equipo, o el propietario o un administrador del espacio de trabajo.

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

POST /teams/:id/members

Añade un miembro del espacio de trabajo a un equipo. Puede hacerlo el propietario del equipo, o el propietario o un administrador del espacio de trabajo; para añadir a alguien como owner hace falta ser propietario o administrador del espacio de trabajo.

Respuesta. 201. Actualmente el cuerpo solo contiene role, con todos los campos del usuario con valores vacíos: llama a GET /teams/:id/members para leer los datos del miembro.

Errores. 403 {"error": "You are not authorized to add a team member"}, 403 al añadir un propietario sin derechos de administrador del espacio de trabajo, 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 el rol de un miembro. Para cambiar role hace falta ser propietario o administrador del espacio de trabajo.

Respuesta. 200 con el miembro del equipo y el nuevo rol.

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

Quita a un miembro. Puede hacerlo el propietario del equipo, o el propietario o un administrador del espacio de trabajo; para quitar a un owner hace falta ser propietario o administrador del espacio de trabajo. No puedes quitarte a ti mismo.

Respuesta. 204.

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

Páginas relacionadas

• Conversaciones y mensajes: adjunta archivos y bases de conocimiento a un mensaje.
• Modelos y multimedia: procesamiento de hojas de cálculo sobre un archivo subido.
• Referencia de herramientas MCP: list_files, get_file y las herramientas de proyectos, bases de conocimiento y equipos.