API de Artifacts: guía de integración

La API de Artifacts permite que tus sistemas produzcan y distribuyan entregables en Tess sin pasar por el chat. Un pipeline de BI puede generar el informe semanal para la dirección, un CRM puede publicar la propuesta para el equipo comercial y una rutina mensual puede actualizar el dashboard de indicadores, siempre en el mismo enlace y con historial de versiones. La API sigue las mismas reglas del panel: el dueño, los permisos por plan y rol y las restricciones de uso compartido definidas por el administrador. Nada de lo que hace la API evita la gobernanza del workspace. Para conocer la función, consulta Artifacts.

Antes de empezar

Clave de API: envíala como token Bearer en el header Authorization. Consulta Autenticación.
Workspace: el header x-workspace-id es obligatorio en todas las llamadas. Sin él, la respuesta es 403.
Permisos: las acciones dependen de que la función esté habilitada y del plan y del rol del usuario dueño de la clave.

Permiso	Qué habilita
Artifacts User	Crear, editar, restaurar, renombrar, compartir y eliminar tus propios Artifacts
Eliminación de contenido del workspace	Necesario, junto con Artifacts User, para eliminar un Artifact o una versión
Artifacts Manager	Leer cualquier Artifact del workspace (con registro en auditoría) y despublicar cualquiera de ellos

Conceptos

Dueño: quien crea el Artifact. Solo el dueño lo modifica, publica y comparte. Los demás reciben 404 (no saben que el Artifact existe) o 403 ARTIFACT_EDIT_FORBIDDEN (pueden leerlo, pero no modificarlo).
Versión más reciente (head_version): cada edición o restauración crea una nueva versión. Las ediciones siempre parten de la más reciente.
Versión compartida (shared_version): la versión que ve quien tiene acceso. Cambia cuando publicas otra versión, en el primer uso compartido (que publica la versión más reciente), cuando se elimina la versión compartida (pasa a la anterior más reciente) y al despublicar (queda nula). Las ediciones nunca la cambian, así puedes revisar antes de liberar.
Enlace (viewer_url): la dirección del Artifact en Tess. Se mantiene entre versiones y exige iniciar sesión en Tess, incluso para el acceso público.

Flujo de integración

Elige la plantilla (opcional)

Listar Plantillas de Artifact devuelve las plantillas globales y las propias del workspace; cuando el slug es el mismo, prevalece la del workspace. Sin elección, la creación usa default, con la identidad visual de Tess.

Crea el Artifact

Crear Artifact recibe el título y el HTML del cuerpo, con CSS y JavaScript opcionales. La respuesta devuelve universal_id, la versión 1 y el viewer_url. El Artifact nace privado.

curl --request POST \
  --url 'https://api.tess.im/artifacts' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'x-workspace-id: YOUR_WORKSPACE_ID' \
  --data '{"title": "Pipeline semanal", "lang": "es", "content": "<h1>Pipeline semanal</h1><p>Pipeline abierto: USD 1,2 M</p>"}'

Comparte con el público correcto

Compartir Artifact concede acceso a personas, equipos, al workspace o a cualquier persona con sesión en Tess. El primer acceso concedido publica la versión actual.

{ "grant": [{ "type": "team", "team_id": 87 }, { "type": "user", "email": "cfo@empresa.com" }] }

Actualiza sin cambiar el enlace

En el siguiente ciclo, usa Editar Artifact con base_version para aplicar los cambios. La nueva versión no llega a quien tiene acceso (solo el dueño y los gestores con Artifacts Manager ven la versión más reciente) hasta que llames a Publicar Versión del Artifact.

{ "base_version": 1, "operations": [{ "op": "replace", "old": "USD 1,2 M", "new": "USD 1,4 M" }] }

Controla el historial

Listar Versiones del Artifact muestra la versión más reciente y la compartida. Para volver atrás, usa Restaurar Versión del Artifact y publica la versión restaurada.

Para materiales recurrentes, guarda el universal_id y edita el mismo Artifact en cada ciclo. Así el enlace enviado a la dirección nunca cambia, y el historial muestra la evolución de los números.

Uso compartido y gobernanza

Conceder acceso respeta las restricciones del usuario, definidas por el administrador en la página de miembros. Por defecto, organización, workspace y equipos están habilitados y el acceso público no.
Solo se pueden agregar personas que sean miembros activos del workspace o de la organización.
Una llamada de uso compartido es todo o nada: si un destino es rechazado, no se guarda nada y la respuesta lista rejected_targets.
Despublicar Artifact elimina todos los accesos a la vez. Cuando un gestor despublica, el dueño no puede publicar de nuevo.
Los permisos se verifican en cada apertura: quien sale del workspace o pierde un nivel de uso compartido pierde el acceso al instante.
En el plan Enterprise, los cambios hechos por la API (crear, editar, publicar, compartir, eliminar) también aparecen en los Eventos de Auditoría, con entity_type igual a artifact.

Errores

Los errores específicos de Artifacts devuelven un código estable en error_code y una explicación en message. Los errores de validación, de workspace, de límite de solicitudes y de permiso de eliminación devuelven solo message (la validación también trae errors). Ejemplo:

{
  "error_code": "ARTIFACT_STALE",
  "message": "Artifact is at version 4, edit was based on 3."
}

Status	Significado
`403`	Sin permiso para la acción (función desactivada, plan, rol, eliminación de contenido), workspace ausente o del que no eres miembro, publicación revocada por un gestor (`ARTIFACT_PUBLICATION_REVOKED`), o puedes leer el Artifact pero no eres el dueño
`404`	El Artifact, la versión o la plantilla no existe, o no te pertenece; o el workspace indicado no existe
`409`	`ARTIFACT_STALE`: la versión más reciente cambió desde `base_version`. Lee de nuevo y reintenta
`422`	Datos inválidos, una edición que no se aplica o un destino de uso compartido rechazado
`429`	Límite de solicitudes alcanzado

Cada página de endpoint lista sus códigos. Para los status generales de la API, consulta Errores.

Límites

Elemento	Límite
Lecturas (`GET`)	600 por minuto por usuario, sumadas al uso en el panel
Escrituras	120 por minuto por usuario, sumadas al uso en el panel
Operaciones por edición	40
Texto de una edición	12.000 caracteres, sumando todos los campos de todas las operaciones (incluidos anclajes y selectores)
Contenido del Artifact	2.000.000 caracteres
`styles` y `script` en la creación	500.000 caracteres cada uno
Destinos por llamada de uso compartido	50 en `grant` y 50 en `revoke`

El contenido es estático: el script de la página no accede a la red. Para actualizar números, edita el Artifact con los datos nuevos y publica la versión.

Endpoints

Listar Artifacts

Tus Artifacts en el workspace, con paginación.

Crear Artifact

Versión 1 a partir de una plantilla.

Obtener Artifact

Versión más reciente con el HTML.

Editar Artifact

Operaciones de edición que crean una nueva versión.

Publicar versión

Define la versión que ve el público.

Compartir Artifact

Concede y revoca accesos.

Guía de API

Referencia de API

Integraciones

Protocolo de Contexto de Modelo (MCP)

API de Artifacts: guía de integración

Antes de empezar

Conceptos

Flujo de integración

Uso compartido y gobernanza

Errores

Límites

Endpoints

Listar Artifacts

Crear Artifact

Obtener Artifact

Editar Artifact

Publicar versión

Compartir Artifact

​Antes de empezar

​Conceptos

​Flujo de integración

​Uso compartido y gobernanza

​Errores

​Límites

​Endpoints

Listar Artifacts

Crear Artifact

Obtener Artifact

Editar Artifact

Publicar versión

Compartir Artifact

Antes de empezar

Conceptos

Flujo de integración

Uso compartido y gobernanza

Errores

Límites

Endpoints