> For the complete documentation index, see [llms.txt](https://prometheo.gitbook.io/prometheo-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://prometheo.gitbook.io/prometheo-api/smart-tags.md).

# Smart Tags

## Obtener lista paginada de smart tags

> Devuelve los smart tags visibles para la organización autenticada (propios y heredados de una org padre vía seats), con paginación offset y filtros opcionales.

```json
{"openapi":"3.0.3","info":{"title":"Prometheo External API","version":"1.0.0"},"tags":[{"name":"Smart Tags"}],"servers":[{"url":"https://api.prometheo.ai/public/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key"}},"schemas":{"SmartTagThemeName":{"type":"string","description":"Nombre en inglés de un theme preset (mismos 6 colores del selector de Moderabot). No se aceptan hex personalizados.","enum":["blue","purple","red","orange","yellow","green"]},"SmartTagListResponse":{"type":"object","properties":{"success":{"type":"boolean"},"smart_tags":{"type":"array","items":{"$ref":"#/components/schemas/SmartTagDetail"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"total_pages":{"type":"integer"}}}}},"SmartTagDetail":{"type":"object","description":"Smart tag de la organización (detalle completo para CRUD)","properties":{"id":{"type":"string"},"name":{"type":"string"},"theme":{"allOf":[{"$ref":"#/components/schemas/SmartTagThemeColors"}],"nullable":true},"prompt":{"type":"string","description":"Instrucciones de asignación automática (AI)"},"bot_action":{"type":"string","enum":["none","activate","deactivate"]},"assignment_mode":{"$ref":"#/components/schemas/SmartTagAssignmentMode"},"exclusive_group":{"type":"string","nullable":true,"description":"Grupo de exclusión. Los smart tags de la misma organización que comparten el mismo grupo son mutuamente excluyentes: un lead puede tener como máximo uno de ellos a la vez. null = sin grupo."},"inherited":{"type":"boolean","description":"true si el tag es heredado (read-only) de una org padre"},"created_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"SmartTagThemeColors":{"type":"object","description":"Colores del theme persistido en el smart tag","required":["bg","color"],"properties":{"bg":{"type":"string","description":"Color de fondo (hex)"},"color":{"type":"string","description":"Color de texto (hex)"}}},"SmartTagAssignmentMode":{"type":"string","description":"Comportamiento del smart tag una vez asignado a un lead. `dynamic` (default): la IA puede asignarlo y quitarlo libremente según la conversación. `fixed`: una vez asignado, la IA no puede quitarlo ni reemplazarlo por otro tag de su mismo grupo de exclusión; solo un moderador o la API externa pueden removerlo del lead.","enum":["dynamic","fixed"],"default":"dynamic"},"ApiError":{"type":"object","required":["success","message"],"properties":{"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"string"}}}}},"paths":{"/smart-tags":{"get":{"tags":["Smart Tags"],"summary":"Obtener lista paginada de smart tags","description":"Devuelve los smart tags visibles para la organización autenticada (propios y heredados de una org padre vía seats), con paginación offset y filtros opcionales.","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1},"description":"Página actual (1-based)"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Cantidad de smart tags por página (máx. 100)"},{"name":"search","in":"query","schema":{"type":"string"},"description":"Filtro case-insensitive por nombre"},{"name":"bot_action","in":"query","schema":{"type":"string","enum":["none","activate","deactivate"]},"description":"Filtrar por bot_action"},{"name":"theme","in":"query","schema":{"$ref":"#/components/schemas/SmartTagThemeName"},"description":"Filtrar por nombre de theme en inglés. Debe ser uno de los presets disponibles (mismos colores que Moderabot)."},{"name":"inherited","in":"query","schema":{"type":"boolean"},"description":"true = solo tags heredados (read-only de org padre); false = solo tags propios de la organización."}],"responses":{"200":{"description":"Lista de smart tags","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartTagListResponse"}}}},"400":{"description":"Parámetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"No autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}
```

## Crear un smart tag

> Crea un smart tag para la organización. El campo \`theme\` debe ser uno de los nombres en inglés de los presets disponibles (mismos colores que el selector de Moderabot). No se aceptan colores personalizados. Si se omite, se usa \`blue\`.

```json
{"openapi":"3.0.3","info":{"title":"Prometheo External API","version":"1.0.0"},"tags":[{"name":"Smart Tags"}],"servers":[{"url":"https://api.prometheo.ai/public/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key"}},"schemas":{"CreateSmartTagRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Nombre del smart tag"},"theme":{"$ref":"#/components/schemas/SmartTagThemeName"},"prompt":{"type":"string","description":"Instrucciones de asignación automática (AI)","default":""},"bot_action":{"type":"string","enum":["none","activate","deactivate"],"default":"none"},"assignment_mode":{"$ref":"#/components/schemas/SmartTagAssignmentMode"},"exclusive_group":{"type":"string","nullable":true,"description":"Grupo de exclusión (ver SmartTagDetail). Omitir o null = sin grupo."}}},"SmartTagThemeName":{"type":"string","description":"Nombre en inglés de un theme preset (mismos 6 colores del selector de Moderabot). No se aceptan hex personalizados.","enum":["blue","purple","red","orange","yellow","green"]},"SmartTagAssignmentMode":{"type":"string","description":"Comportamiento del smart tag una vez asignado a un lead. `dynamic` (default): la IA puede asignarlo y quitarlo libremente según la conversación. `fixed`: una vez asignado, la IA no puede quitarlo ni reemplazarlo por otro tag de su mismo grupo de exclusión; solo un moderador o la API externa pueden removerlo del lead.","enum":["dynamic","fixed"],"default":"dynamic"},"SmartTagDetailResponse":{"type":"object","properties":{"success":{"type":"boolean"},"smart_tag":{"$ref":"#/components/schemas/SmartTagDetail"}}},"SmartTagDetail":{"type":"object","description":"Smart tag de la organización (detalle completo para CRUD)","properties":{"id":{"type":"string"},"name":{"type":"string"},"theme":{"allOf":[{"$ref":"#/components/schemas/SmartTagThemeColors"}],"nullable":true},"prompt":{"type":"string","description":"Instrucciones de asignación automática (AI)"},"bot_action":{"type":"string","enum":["none","activate","deactivate"]},"assignment_mode":{"$ref":"#/components/schemas/SmartTagAssignmentMode"},"exclusive_group":{"type":"string","nullable":true,"description":"Grupo de exclusión. Los smart tags de la misma organización que comparten el mismo grupo son mutuamente excluyentes: un lead puede tener como máximo uno de ellos a la vez. null = sin grupo."},"inherited":{"type":"boolean","description":"true si el tag es heredado (read-only) de una org padre"},"created_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"SmartTagThemeColors":{"type":"object","description":"Colores del theme persistido en el smart tag","required":["bg","color"],"properties":{"bg":{"type":"string","description":"Color de fondo (hex)"},"color":{"type":"string","description":"Color de texto (hex)"}}},"ApiError":{"type":"object","required":["success","message"],"properties":{"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"string"}}}}},"paths":{"/smart-tags":{"post":{"tags":["Smart Tags"],"summary":"Crear un smart tag","description":"Crea un smart tag para la organización. El campo `theme` debe ser uno de los nombres en inglés de los presets disponibles (mismos colores que el selector de Moderabot). No se aceptan colores personalizados. Si se omite, se usa `blue`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSmartTagRequest"}}}},"responses":{"201":{"description":"Smart tag creado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartTagDetailResponse"}}}},"400":{"description":"Validación fallida (nombre vacío, theme o bot_action inválido)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"No autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}
```

## GET /smart-tags/{id}

> Obtener un smart tag por ID

```json
{"openapi":"3.0.3","info":{"title":"Prometheo External API","version":"1.0.0"},"tags":[{"name":"Smart Tags"}],"servers":[{"url":"https://api.prometheo.ai/public/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key"}},"schemas":{"SmartTagDetailResponse":{"type":"object","properties":{"success":{"type":"boolean"},"smart_tag":{"$ref":"#/components/schemas/SmartTagDetail"}}},"SmartTagDetail":{"type":"object","description":"Smart tag de la organización (detalle completo para CRUD)","properties":{"id":{"type":"string"},"name":{"type":"string"},"theme":{"allOf":[{"$ref":"#/components/schemas/SmartTagThemeColors"}],"nullable":true},"prompt":{"type":"string","description":"Instrucciones de asignación automática (AI)"},"bot_action":{"type":"string","enum":["none","activate","deactivate"]},"assignment_mode":{"$ref":"#/components/schemas/SmartTagAssignmentMode"},"exclusive_group":{"type":"string","nullable":true,"description":"Grupo de exclusión. Los smart tags de la misma organización que comparten el mismo grupo son mutuamente excluyentes: un lead puede tener como máximo uno de ellos a la vez. null = sin grupo."},"inherited":{"type":"boolean","description":"true si el tag es heredado (read-only) de una org padre"},"created_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"SmartTagThemeColors":{"type":"object","description":"Colores del theme persistido en el smart tag","required":["bg","color"],"properties":{"bg":{"type":"string","description":"Color de fondo (hex)"},"color":{"type":"string","description":"Color de texto (hex)"}}},"SmartTagAssignmentMode":{"type":"string","description":"Comportamiento del smart tag una vez asignado a un lead. `dynamic` (default): la IA puede asignarlo y quitarlo libremente según la conversación. `fixed`: una vez asignado, la IA no puede quitarlo ni reemplazarlo por otro tag de su mismo grupo de exclusión; solo un moderador o la API externa pueden removerlo del lead.","enum":["dynamic","fixed"],"default":"dynamic"},"ApiError":{"type":"object","required":["success","message"],"properties":{"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"string"}}}}},"paths":{"/smart-tags/{id}":{"get":{"tags":["Smart Tags"],"summary":"Obtener un smart tag por ID","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Id de la etiqueta."}],"responses":{"200":{"description":"Smart tag encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartTagDetailResponse"}}}},"400":{"description":"ID inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"No autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Smart tag no encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}
```

## Eliminar un smart tag

> Elimina un smart tag propio de la organización. También limpia referencias en leads, funnels y agentes. Los tags heredados no se pueden eliminar (403).

```json
{"openapi":"3.0.3","info":{"title":"Prometheo External API","version":"1.0.0"},"tags":[{"name":"Smart Tags"}],"servers":[{"url":"https://api.prometheo.ai/public/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key"}},"schemas":{"ApiError":{"type":"object","required":["success","message"],"properties":{"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"string"}}}}},"paths":{"/smart-tags/{id}":{"delete":{"tags":["Smart Tags"],"summary":"Eliminar un smart tag","description":"Elimina un smart tag propio de la organización. También limpia referencias en leads, funnels y agentes. Los tags heredados no se pueden eliminar (403).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Id de la etiqueta."}],"responses":{"200":{"description":"Smart tag eliminado","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"description":"ID inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"No autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Tag heredado (no eliminable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Smart tag no encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}
```

## Actualizar un smart tag

> Actualización parcial de un smart tag propio de la organización. Los tags heredados (shared desde una org padre) no se pueden editar (403). El \`theme\` debe ser un nombre de preset en inglés.

```json
{"openapi":"3.0.3","info":{"title":"Prometheo External API","version":"1.0.0"},"tags":[{"name":"Smart Tags"}],"servers":[{"url":"https://api.prometheo.ai/public/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key"}},"schemas":{"UpdateSmartTagRequest":{"type":"object","description":"Campos opcionales para actualización parcial","properties":{"name":{"type":"string"},"theme":{"$ref":"#/components/schemas/SmartTagThemeName"},"prompt":{"type":"string"},"bot_action":{"type":"string","enum":["none","activate","deactivate"]},"assignment_mode":{"$ref":"#/components/schemas/SmartTagAssignmentMode"},"exclusive_group":{"type":"string","nullable":true,"description":"Grupo de exclusión. Enviar null para quitar el tag del grupo."}}},"SmartTagThemeName":{"type":"string","description":"Nombre en inglés de un theme preset (mismos 6 colores del selector de Moderabot). No se aceptan hex personalizados.","enum":["blue","purple","red","orange","yellow","green"]},"SmartTagAssignmentMode":{"type":"string","description":"Comportamiento del smart tag una vez asignado a un lead. `dynamic` (default): la IA puede asignarlo y quitarlo libremente según la conversación. `fixed`: una vez asignado, la IA no puede quitarlo ni reemplazarlo por otro tag de su mismo grupo de exclusión; solo un moderador o la API externa pueden removerlo del lead.","enum":["dynamic","fixed"],"default":"dynamic"},"SmartTagDetailResponse":{"type":"object","properties":{"success":{"type":"boolean"},"smart_tag":{"$ref":"#/components/schemas/SmartTagDetail"}}},"SmartTagDetail":{"type":"object","description":"Smart tag de la organización (detalle completo para CRUD)","properties":{"id":{"type":"string"},"name":{"type":"string"},"theme":{"allOf":[{"$ref":"#/components/schemas/SmartTagThemeColors"}],"nullable":true},"prompt":{"type":"string","description":"Instrucciones de asignación automática (AI)"},"bot_action":{"type":"string","enum":["none","activate","deactivate"]},"assignment_mode":{"$ref":"#/components/schemas/SmartTagAssignmentMode"},"exclusive_group":{"type":"string","nullable":true,"description":"Grupo de exclusión. Los smart tags de la misma organización que comparten el mismo grupo son mutuamente excluyentes: un lead puede tener como máximo uno de ellos a la vez. null = sin grupo."},"inherited":{"type":"boolean","description":"true si el tag es heredado (read-only) de una org padre"},"created_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"SmartTagThemeColors":{"type":"object","description":"Colores del theme persistido en el smart tag","required":["bg","color"],"properties":{"bg":{"type":"string","description":"Color de fondo (hex)"},"color":{"type":"string","description":"Color de texto (hex)"}}},"ApiError":{"type":"object","required":["success","message"],"properties":{"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"string"}}}}},"paths":{"/smart-tags/{id}":{"patch":{"tags":["Smart Tags"],"summary":"Actualizar un smart tag","description":"Actualización parcial de un smart tag propio de la organización. Los tags heredados (shared desde una org padre) no se pueden editar (403). El `theme` debe ser un nombre de preset en inglés.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Id de la etiqueta."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSmartTagRequest"}}}},"responses":{"200":{"description":"Smart tag actualizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartTagDetailResponse"}}}},"400":{"description":"Validación fallida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"No autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Tag heredado (no editable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Smart tag no encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}
```

## Reordenar smart tags

> Guarda el orden de los smart tags propios. \`order\` es la lista de ids.

```json
{"openapi":"3.0.3","info":{"title":"Prometheo External API","version":"1.0.0"},"tags":[{"name":"Smart Tags"}],"servers":[{"url":"https://api.prometheo.ai/public/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key"}},"responses":{"BadRequest":{"description":"Datos inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Unauthorized":{"description":"No autorizado (API Key ausente o inválida)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"InternalError":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"schemas":{"ApiError":{"type":"object","required":["success","message"],"properties":{"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"string"}}}}},"paths":{"/smart-tags/order":{"put":{"tags":["Smart Tags"],"summary":"Reordenar smart tags","description":"Guarda el orden de los smart tags propios. `order` es la lista de ids.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["order"],"properties":{"order":{"type":"array","items":{"type":"string"},"description":"Ids de smart tags en el orden deseado."}}}}}},"responses":{"200":{"description":"Orden guardado","content":{"application/json":{"schema":{"type":"object","required":["success","order"],"properties":{"success":{"type":"boolean"},"order":{"type":"array","items":{"type":"string"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```