{"components":{"schemas":{"AssignedAgent":{"additionalProperties":false,"properties":{"id":{"description":"Identificador p\u00fablico hexadecimal de Bulest.","pattern":"^[0-9a-f]{32}$","type":"string"},"name":{"type":"string"}},"required":["id","name"],"type":"object"},"CatalogProduct":{"additionalProperties":true,"properties":{"available_for_sale":{"const":true},"category":{"type":"string"},"currency":{"type":"string"},"description":{"type":"string"},"final_price":{"type":"string"},"fragment_template":{"additionalProperties":false,"properties":{"active":{"type":"boolean"},"content":{"type":"string"},"id":{"description":"Identificador p\u00fablico hexadecimal de Bulest.","pattern":"^[0-9a-f]{32}$","type":"string"},"meta":{"additionalProperties":true,"properties":{"attachments":{"description":"Lista can\u00f3nica y ordenada de recursos del fragmento. Al editar meta.attachments se reemplaza la lista completa.","items":{"$ref":"#/components/schemas/FragmentAttachment"},"type":"array"}},"type":"object"},"title":{"maxLength":240,"minLength":1,"type":"string"},"type":{"enum":["text","file","product","image","other"],"type":"string"}},"required":["title"],"type":"object"},"id":{"type":"string"},"image":{"format":"uri","type":["string","null"]},"max_price":{"type":"string"},"min_price":{"type":"string"},"product_id":{"description":"ID num\u00e9rico can\u00f3nico del producto en Shopify.","type":"string"},"shopify_product_gid":{"type":"string"},"title":{"type":"string"},"url":{"format":"uri","type":["string","null"]},"variants":{"items":{"additionalProperties":true,"properties":{"available_for_sale":{"const":true},"currency":{"type":"string"},"final_price":{"type":"string"},"fragment_meta_patch":{"additionalProperties":false,"properties":{"variant_id":{"type":"string"},"variant_title":{"type":"string"}},"required":["variant_id","variant_title"],"type":"object"},"id":{"type":"string"},"inventory":{"type":["integer","null"]},"price":{"type":"string"},"product_id":{"type":"string"},"shopify_variant_gid":{"type":"string"},"title":{"type":"string"},"variant_id":{"description":"ID num\u00e9rico de la variante; es el ID usado para compra.","type":"string"}},"required":["id","variant_id","shopify_variant_gid","product_id"],"type":"object"},"type":"array"}},"required":["id","product_id","shopify_product_gid","title","variants","fragment_template"],"type":"object"},"CatalogResponse":{"additionalProperties":false,"properties":{"agent":{"additionalProperties":false,"properties":{"id":{"description":"Identificador p\u00fablico hexadecimal de Bulest.","pattern":"^[0-9a-f]{32}$","type":"string"},"name":{"type":"string"},"store_id":{"type":"string"}},"required":["id","name","store_id"],"type":"object"},"categories":{"items":{"type":"string"},"type":"array"},"collections":{"items":{"type":"object"},"type":"array"},"currency":{"type":"string"},"fragment_usage":{"type":"object"},"page_info":{"additionalProperties":false,"properties":{"end_cursor":{"type":["string","null"]},"has_next_page":{"type":"boolean"}},"required":["has_next_page","end_cursor"],"type":"object"},"products":{"items":{"$ref":"#/components/schemas/CatalogProduct"},"type":"array"},"store":{"additionalProperties":false,"properties":{"domain":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name","domain"],"type":"object"},"success":{"const":true}},"required":["success","agent","store","products","currency","page_info","fragment_usage"],"type":"object"},"CatalogVariant":{"additionalProperties":true,"properties":{"available_for_sale":{"const":true},"currency":{"type":"string"},"final_price":{"type":"string"},"fragment_meta_patch":{"additionalProperties":false,"properties":{"variant_id":{"type":"string"},"variant_title":{"type":"string"}},"required":["variant_id","variant_title"],"type":"object"},"id":{"type":"string"},"inventory":{"type":["integer","null"]},"price":{"type":"string"},"product_id":{"type":"string"},"shopify_variant_gid":{"type":"string"},"title":{"type":"string"},"variant_id":{"description":"ID num\u00e9rico de la variante; es el ID usado para compra.","type":"string"}},"required":["id","variant_id","shopify_variant_gid","product_id"],"type":"object"},"ConfigurationContext":{"additionalProperties":false,"properties":{"agent":{"additionalProperties":false,"properties":{"id":{"description":"Identificador p\u00fablico hexadecimal de Bulest.","pattern":"^[0-9a-f]{32}$","type":"string"},"name":{"type":"string"}},"required":["id","name"],"type":"object"},"assessment":{"additionalProperties":false,"properties":{"configuration_consistent":{"type":"boolean"},"issue_counts":{"type":"object"},"review_before_prompt_edit":{"type":"boolean"},"status":{"enum":["ready","attention_required","inconsistent"],"type":"string"},"summary":{"type":"string"}},"required":["status","summary","configuration_consistent","review_before_prompt_edit","issue_counts"],"type":"object"},"calendars":{"items":{"type":"object"},"type":"array"},"capabilities":{"type":"object"},"departments":{"items":{"type":"object"},"type":"array"},"human_attention":{"type":"object"},"instances":{"items":{"type":"object"},"type":"array"},"issues":{"items":{"additionalProperties":false,"properties":{"code":{"type":"string"},"message":{"type":"string"},"relation":{"type":"string"},"relation_ids":{"items":{"type":"string"},"type":"array"},"severity":{"enum":["error","warning","info"],"type":"string"}},"required":["severity","code","message"],"type":"object"},"type":"array"},"store":{"type":"object"},"success":{"const":true}},"required":["success","agent","assessment","instances","store","departments","capabilities","calendars","human_attention","issues"],"type":"object"},"DraftWrite":{"additionalProperties":false,"properties":{"agent":{"additionalProperties":true,"type":"object"},"base_revision":{"description":"Revisi\u00f3n devuelta al leer el recurso; protege de escrituras concurrentes.","minLength":1,"type":"string"},"expires_at":{"format":"date-time","type":"string"},"fragments":{"items":{"additionalProperties":false,"properties":{"active":{"type":"boolean"},"content":{"type":"string"},"id":{"description":"Identificador p\u00fablico hexadecimal de Bulest.","pattern":"^[0-9a-f]{32}$","type":"string"},"meta":{"additionalProperties":true,"properties":{"attachments":{"description":"Lista can\u00f3nica y ordenada de recursos del fragmento. Al editar meta.attachments se reemplaza la lista completa.","items":{"$ref":"#/components/schemas/FragmentAttachment"},"type":"array"}},"type":"object"},"title":{"maxLength":240,"minLength":1,"type":"string"},"type":{"enum":["text","file","product","image","other"],"type":"string"}},"required":["title"],"type":"object"},"type":"array"},"summary":{"maxLength":1000,"type":"string"}},"required":["base_revision"],"type":"object"},"Error":{"properties":{"error":{"type":"string"},"error_code":{"type":"string"},"success":{"const":false}},"required":["success","error_code","error"],"type":"object"},"ExternalFileResponse":{"additionalProperties":false,"properties":{"attachment":{"$ref":"#/components/schemas/FragmentAttachment"},"file":{"$ref":"#/components/schemas/UploadedFile"},"success":{"const":true},"usage":{"additionalProperties":false,"properties":{"meta_path":{"const":"meta.attachments"},"order":{"type":"string"}},"required":["meta_path","order"],"type":"object"}},"required":["success","file","attachment","usage"],"type":"object"},"ExternalInstance":{"additionalProperties":false,"properties":{"active":{"type":"boolean"},"assigned_agent":{"oneOf":[{"$ref":"#/components/schemas/AssignedAgent"},{"type":"null"}]},"assignment_editable":{"description":"False cuando el canal est\u00e1 vinculado a un agente fuera del alcance de esta integraci\u00f3n.","type":"boolean"},"id":{"minLength":1,"type":"string"},"name":{"type":"string"}},"required":["id","name","active","assigned_agent"],"type":"object"},"ExternalInstanceAssignmentResponse":{"additionalProperties":false,"properties":{"assignment_changed":{"type":"boolean"},"instance":{"$ref":"#/components/schemas/ExternalInstance"},"previous_agent":{"oneOf":[{"$ref":"#/components/schemas/AssignedAgent"},{"type":"null"}]},"success":{"const":true}},"required":["success","instance","previous_agent","assignment_changed"],"type":"object"},"ExternalInstancesResponse":{"additionalProperties":false,"properties":{"instances":{"items":{"$ref":"#/components/schemas/ExternalInstance"},"type":"array"},"success":{"const":true}},"required":["success","instances"],"type":"object"},"Fragment":{"additionalProperties":false,"properties":{"active":{"type":"boolean"},"content":{"type":"string"},"id":{"description":"Identificador p\u00fablico hexadecimal de Bulest.","pattern":"^[0-9a-f]{32}$","type":"string"},"meta":{"additionalProperties":true,"properties":{"attachments":{"description":"Lista can\u00f3nica y ordenada de recursos del fragmento. Al editar meta.attachments se reemplaza la lista completa.","items":{"$ref":"#/components/schemas/FragmentAttachment"},"type":"array"}},"type":"object"},"title":{"maxLength":240,"minLength":1,"type":"string"},"type":{"enum":["text","file","product","image","other"],"type":"string"}},"required":["title"],"type":"object"},"FragmentAttachment":{"additionalProperties":false,"description":"Recurso de un fragmento. Para archivos subidos usa el objeto attachment devuelto por POST /files sin modificar sus campos. El orden del arreglo es el orden en que Bulest entrega el recurso al agente.","properties":{"ai_description":{"maxLength":5000,"type":["string","null"]},"file_id":{"description":"ID del archivo de Bulest; puede ser nulo para un recurso remoto de cat\u00e1logo.","type":["string","null"]},"filename":{"type":["string","null"]},"filepath":{"type":["string","null"]},"filetype":{"type":["string","null"]},"image_url":{"format":"uri","type":["string","null"]}},"type":"object"},"PublicId":{"description":"Identificador p\u00fablico hexadecimal de Bulest.","pattern":"^[0-9a-f]{32}$","type":"string"},"Revision":{"description":"Revisi\u00f3n devuelta al leer el recurso; protege de escrituras concurrentes.","minLength":1,"type":"string"},"TestChatMessage":{"additionalProperties":false,"properties":{"agent_id":{"description":"Identificador p\u00fablico hexadecimal de Bulest.","pattern":"^[0-9a-f]{32}$","type":"string"},"client_message_id":{"description":"Llave de idempotencia \u00fanica dentro de la sesi\u00f3n.","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,99}$","type":"string"},"draft_id":{"description":"Identificador p\u00fablico hexadecimal de Bulest.","pattern":"^[0-9a-f]{32}$","type":"string"},"message":{"oneOf":[{"additionalProperties":false,"properties":{"content":{"minLength":1,"type":"string"},"type":{"const":"text"}},"required":["type","content"],"type":"object"},{"additionalProperties":false,"properties":{"base64":{"description":"Base64 crudo o data URL.","type":"string"},"caption":{"type":"string"},"filename":{"maxLength":160,"type":"string"},"mime_type":{"maxLength":120,"type":"string"},"type":{"enum":["image","audio","video","file"],"type":"string"}},"required":["type","base64","mime_type"],"type":"object"}]},"session_id":{"maxLength":160,"minLength":1,"type":"string"}},"required":["message"],"type":"object"},"TurnStatus":{"enum":["queued","generating","waiting_for_tool","processing_tool_result","completed","failed","cancelled","reset"],"type":"string"},"UploadedFile":{"additionalProperties":false,"properties":{"filename":{"type":"string"},"filetype":{"type":"string"},"id":{"type":"string"},"size_bytes":{"minimum":0,"type":"integer"},"url":{"format":"uri","type":"string"}},"required":["id","filename","filetype","size_bytes","url"],"type":"object"}},"securitySchemes":{"bearerAuth":{"bearerFormat":"Bulest integration token","description":"Token generado en Perfil > Integraciones externas.","scheme":"bearer","type":"http"}}},"externalDocs":{"description":"Gu\u00eda completa en espa\u00f1ol","url":"https://bulest.co/docs/integraciones-externas"},"info":{"description":"API p\u00fablica y aislada por cuenta para consultar agentes, subir recursos de fragmentos, asignar agentes a canales, consultar cat\u00e1logos, preparar borradores, usar el Chat de pruebas y leer la actividad. La cuenta se deriva siempre del token Bearer.","title":"API de Integraciones externas de Bulest","version":"1.3.0"},"openapi":"3.1.0","paths":{"/activity":{"get":{"description":"Consultar la actividad de la integraci\u00f3n Permiso requerido: `activity.read`.","responses":{"200":{"description":"Solicitud procesada correctamente."},"400":{"description":"Solicitud inv\u00e1lida."},"401":{"description":"Token ausente o inv\u00e1lido."},"403":{"description":"Permiso, alcance o pol\u00edtica insuficiente."},"409":{"description":"Conflicto de versi\u00f3n o estado."},"410":{"description":"El borrador o la sesi\u00f3n ya venci\u00f3."},"413":{"description":"El cuerpo o archivo excede el l\u00edmite permitido."},"429":{"description":"Demasiadas solicitudes; respeta Retry-After si est\u00e1 presente."},"503":{"description":"Una dependencia temporalmente no est\u00e1 disponible."}},"security":[{"bearerAuth":[]}],"summary":"Consultar la actividad de la integraci\u00f3n"}},"/agents":{"get":{"description":"Listar agentes autorizados Permiso requerido: `agents.read`.","responses":{"200":{"description":"Solicitud procesada correctamente."},"400":{"description":"Solicitud inv\u00e1lida."},"401":{"description":"Token ausente o inv\u00e1lido."},"403":{"description":"Permiso, alcance o pol\u00edtica insuficiente."},"409":{"description":"Conflicto de versi\u00f3n o estado."},"410":{"description":"El borrador o la sesi\u00f3n ya venci\u00f3."},"413":{"description":"El cuerpo o archivo excede el l\u00edmite permitido."},"429":{"description":"Demasiadas solicitudes; respeta Retry-After si est\u00e1 presente."},"503":{"description":"Una dependencia temporalmente no est\u00e1 disponible."}},"security":[{"bearerAuth":[]}],"summary":"Listar agentes autorizados"},"post":{"description":"Crear un agente Permiso requerido: `agents.lifecycle`. Sensibilidad: cambio directo.","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"checkout_mode":{"enum":["automatic","manual"],"type":"string"},"delay":{"maximum":60000,"minimum":0,"type":"integer"},"description":{"maxLength":2000,"type":"string"},"name":{"maxLength":120,"minLength":1,"type":"string"}},"required":["name"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Solicitud procesada correctamente."},"400":{"description":"Solicitud inv\u00e1lida."},"401":{"description":"Token ausente o inv\u00e1lido."},"403":{"description":"Permiso, alcance o pol\u00edtica insuficiente."},"409":{"description":"Conflicto de versi\u00f3n o estado."},"410":{"description":"El borrador o la sesi\u00f3n ya venci\u00f3."},"413":{"description":"El cuerpo o archivo excede el l\u00edmite permitido."},"429":{"description":"Demasiadas solicitudes; respeta Retry-After si est\u00e1 presente."},"503":{"description":"Una dependencia temporalmente no est\u00e1 disponible."}},"security":[{"bearerAuth":[]}],"summary":"Crear un agente"}},"/agents/{agent_id}":{"delete":{"description":"Archivar un agente Permiso requerido: `agents.lifecycle`. Sensibilidad: destructiva; exige confirmaci\u00f3n expl\u00edcita.","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"confirm":{"const":true}},"required":["confirm"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Solicitud procesada correctamente."},"400":{"description":"Solicitud inv\u00e1lida."},"401":{"description":"Token ausente o inv\u00e1lido."},"403":{"description":"Permiso, alcance o pol\u00edtica insuficiente."},"409":{"description":"Conflicto de versi\u00f3n o estado."},"410":{"description":"El borrador o la sesi\u00f3n ya venci\u00f3."},"413":{"description":"El cuerpo o archivo excede el l\u00edmite permitido."},"429":{"description":"Demasiadas solicitudes; respeta Retry-After si est\u00e1 presente."},"503":{"description":"Una dependencia temporalmente no est\u00e1 disponible."}},"security":[{"bearerAuth":[]}],"summary":"Archivar un agente"},"get":{"description":"Consultar un agente Permiso requerido: `agents.read`.","responses":{"200":{"description":"Solicitud procesada correctamente."},"400":{"description":"Solicitud inv\u00e1lida."},"401":{"description":"Token ausente o inv\u00e1lido."},"403":{"description":"Permiso, alcance o pol\u00edtica insuficiente."},"409":{"description":"Conflicto de versi\u00f3n o estado."},"410":{"description":"El borrador o la sesi\u00f3n ya venci\u00f3."},"413":{"description":"El cuerpo o archivo excede el l\u00edmite permitido."},"429":{"description":"Demasiadas solicitudes; respeta Retry-After si est\u00e1 presente."},"503":{"description":"Una dependencia temporalmente no est\u00e1 disponible."}},"security":[{"bearerAuth":[]}],"summary":"Consultar un agente"},"parameters":[{"description":"ID p\u00fablico del agente autorizado.","in":"path","name":"agent_id","required":true,"schema":{"minLength":1,"type":"string"}}]},"/agents/{agent_id}/catalog":{"get":{"description":"Consultar el cat\u00e1logo de la tienda vinculada Permiso requerido: `catalog.read`. Sensibilidad: solo lectura; la tienda se deriva del agente y cada producto incluye una plantilla de fragmento product.","parameters":[{"description":"B\u00fasqueda por t\u00edtulo de producto.","in":"query","name":"q","required":false,"schema":{"maxLength":100,"type":"string"}},{"in":"query","name":"limit","required":false,"schema":{"default":30,"maximum":50,"minimum":1,"type":"integer"}},{"description":"Cursor opaco devuelto en page_info.end_cursor.","in":"query","name":"cursor","required":false,"schema":{"maxLength":1000,"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogResponse"}}},"description":"Cat\u00e1logo visible para el agente."},"400":{"description":"Solicitud inv\u00e1lida."},"401":{"description":"Token ausente o inv\u00e1lido."},"403":{"description":"Permiso, alcance o pol\u00edtica insuficiente."},"409":{"description":"Conflicto de versi\u00f3n o estado."},"410":{"description":"El borrador o la sesi\u00f3n ya venci\u00f3."},"413":{"description":"El cuerpo o archivo excede el l\u00edmite permitido."},"429":{"description":"Demasiadas solicitudes; respeta Retry-After si est\u00e1 presente."},"503":{"description":"Una dependencia temporalmente no est\u00e1 disponible."}},"security":[{"bearerAuth":[]}],"summary":"Consultar el cat\u00e1logo de la tienda vinculada"},"parameters":[{"description":"ID p\u00fablico del agente autorizado.","in":"path","name":"agent_id","required":true,"schema":{"minLength":1,"type":"string"}}]},"/agents/{agent_id}/configuration-context":{"get":{"description":"Diagnosticar las relaciones y dependencias del agente Permiso requerido: `configuration.read`. Sensibilidad: solo lectura; incluye referencias operativas, nunca credenciales, tokens ni tel\u00e9fonos de asesores.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigurationContext"}}},"description":"Contexto de configuraci\u00f3n y diagn\u00f3sticos."},"400":{"description":"Solicitud inv\u00e1lida."},"401":{"description":"Token ausente o inv\u00e1lido."},"403":{"description":"Permiso, alcance o pol\u00edtica insuficiente."},"409":{"description":"Conflicto de versi\u00f3n o estado."},"410":{"description":"El borrador o la sesi\u00f3n ya venci\u00f3."},"413":{"description":"El cuerpo o archivo excede el l\u00edmite permitido."},"429":{"description":"Demasiadas solicitudes; respeta Retry-After si est\u00e1 presente."},"503":{"description":"Una dependencia temporalmente no est\u00e1 disponible."}},"security":[{"bearerAuth":[]}],"summary":"Diagnosticar las relaciones y dependencias del agente"},"parameters":[{"description":"ID p\u00fablico del agente autorizado.","in":"path","name":"agent_id","required":true,"schema":{"minLength":1,"type":"string"}}]},"/agents/{agent_id}/drafts":{"parameters":[{"description":"ID p\u00fablico del agente autorizado.","in":"path","name":"agent_id","required":true,"schema":{"minLength":1,"type":"string"}}],"post":{"description":"Crear un borrador de snapshot completo Permiso requerido: `fragments.draft`. Sensibilidad: borrador reversible.","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"agent":{"additionalProperties":true,"type":"object"},"base_revision":{"description":"Revisi\u00f3n devuelta al leer el recurso; protege de escrituras concurrentes.","minLength":1,"type":"string"},"expires_at":{"format":"date-time","type":"string"},"fragments":{"items":{"additionalProperties":false,"properties":{"active":{"type":"boolean"},"content":{"type":"string"},"id":{"description":"Identificador p\u00fablico hexadecimal de Bulest.","pattern":"^[0-9a-f]{32}$","type":"string"},"meta":{"additionalProperties":true,"properties":{"attachments":{"description":"Lista can\u00f3nica y ordenada de recursos del fragmento. Al editar meta.attachments se reemplaza la lista completa.","items":{"$ref":"#/components/schemas/FragmentAttachment"},"type":"array"}},"type":"object"},"title":{"maxLength":240,"minLength":1,"type":"string"},"type":{"enum":["text","file","product","image","other"],"type":"string"}},"required":["title"],"type":"object"},"type":"array"},"summary":{"maxLength":1000,"type":"string"}},"required":["base_revision"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Solicitud procesada correctamente."},"400":{"description":"Solicitud inv\u00e1lida."},"401":{"description":"Token ausente o inv\u00e1lido."},"403":{"description":"Permiso, alcance o pol\u00edtica insuficiente."},"409":{"description":"Conflicto de versi\u00f3n o estado."},"410":{"description":"El borrador o la sesi\u00f3n ya venci\u00f3."},"413":{"description":"El cuerpo o archivo excede el l\u00edmite permitido."},"429":{"description":"Demasiadas solicitudes; respeta Retry-After si est\u00e1 presente."},"503":{"description":"Una dependencia temporalmente no est\u00e1 disponible."}},"security":[{"bearerAuth":[]}],"summary":"Crear un borrador de snapshot completo"}},"/agents/{agent_id}/fragments":{"get":{"description":"Listar fragmentos y revisi\u00f3n Permiso requerido: `fragments.read`.","responses":{"200":{"description":"Solicitud procesada correctamente."},"400":{"description":"Solicitud inv\u00e1lida."},"401":{"description":"Token ausente o inv\u00e1lido."},"403":{"description":"Permiso, alcance o pol\u00edtica insuficiente."},"409":{"description":"Conflicto de versi\u00f3n o estado."},"410":{"description":"El borrador o la sesi\u00f3n ya venci\u00f3."},"413":{"description":"El cuerpo o archivo excede el l\u00edmite permitido."},"429":{"description":"Demasiadas solicitudes; respeta Retry-After si est\u00e1 presente."},"503":{"description":"Una dependencia temporalmente no est\u00e1 disponible."}},"security":[{"bearerAuth":[]}],"summary":"Listar fragmentos y revisi\u00f3n"},"parameters":[{"description":"ID p\u00fablico del agente autorizado.","in":"path","name":"agent_id","required":true,"schema":{"minLength":1,"type":"string"}}],"post":{"description":"Preparar la creaci\u00f3n de un fragmento Permiso requerido: `fragments.draft`. Sensibilidad: borrador reversible.","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"base_revision":{"description":"Revisi\u00f3n devuelta al leer el recurso; protege de escrituras concurrentes.","minLength":1,"type":"string"},"expires_at":{"format":"date-time","type":"string"},"fragment":{"additionalProperties":false,"properties":{"active":{"type":"boolean"},"content":{"type":"string"},"id":{"description":"Identificador p\u00fablico hexadecimal de Bulest.","pattern":"^[0-9a-f]{32}$","type":"string"},"meta":{"additionalProperties":true,"properties":{"attachments":{"description":"Lista can\u00f3nica y ordenada de recursos del fragmento. Al editar meta.attachments se reemplaza la lista completa.","items":{"$ref":"#/components/schemas/FragmentAttachment"},"type":"array"}},"type":"object"},"title":{"maxLength":240,"minLength":1,"type":"string"},"type":{"enum":["text","file","product","image","other"],"type":"string"}},"required":["title"],"type":"object"},"summary":{"maxLength":1000,"type":"string"}},"required":["base_revision","fragment"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Solicitud procesada correctamente."},"400":{"description":"Solicitud inv\u00e1lida."},"401":{"description":"Token ausente o inv\u00e1lido."},"403":{"description":"Permiso, alcance o pol\u00edtica insuficiente."},"409":{"description":"Conflicto de versi\u00f3n o estado."},"410":{"description":"El borrador o la sesi\u00f3n ya venci\u00f3."},"413":{"description":"El cuerpo o archivo excede el l\u00edmite permitido."},"429":{"description":"Demasiadas solicitudes; respeta Retry-After si est\u00e1 presente."},"503":{"description":"Una dependencia temporalmente no est\u00e1 disponible."}},"security":[{"bearerAuth":[]}],"summary":"Preparar la creaci\u00f3n de un fragmento"}},"/agents/{agent_id}/fragments/{fragment_id}":{"delete":{"description":"Preparar la eliminaci\u00f3n de un fragmento Permiso requerido: `fragments.draft`. Sensibilidad: borrador reversible.","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"base_revision":{"description":"Revisi\u00f3n devuelta al leer el recurso; protege de escrituras concurrentes.","minLength":1,"type":"string"},"summary":{"maxLength":1000,"type":"string"}},"required":["base_revision"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Solicitud procesada correctamente."},"400":{"description":"Solicitud inv\u00e1lida."},"401":{"description":"Token ausente o inv\u00e1lido."},"403":{"description":"Permiso, alcance o pol\u00edtica insuficiente."},"409":{"description":"Conflicto de versi\u00f3n o estado."},"410":{"description":"El borrador o la sesi\u00f3n ya venci\u00f3."},"413":{"description":"El cuerpo o archivo excede el l\u00edmite permitido."},"429":{"description":"Demasiadas solicitudes; respeta Retry-After si est\u00e1 presente."},"503":{"description":"Una dependencia temporalmente no est\u00e1 disponible."}},"security":[{"bearerAuth":[]}],"summary":"Preparar la eliminaci\u00f3n de un fragmento"},"parameters":[{"description":"ID p\u00fablico del agente autorizado.","in":"path","name":"agent_id","required":true,"schema":{"minLength":1,"type":"string"}},{"description":"ID del fragmento dentro del agente.","in":"path","name":"fragment_id","required":true,"schema":{"minLength":1,"type":"string"}}],"patch":{"description":"Preparar la edici\u00f3n de un fragmento Permiso requerido: `fragments.draft`. Sensibilidad: borrador reversible.","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"base_revision":{"description":"Revisi\u00f3n devuelta al leer el recurso; protege de escrituras concurrentes.","minLength":1,"type":"string"},"fragment":{"additionalProperties":false,"properties":{"active":{"type":"boolean"},"content":{"type":"string"},"id":{"description":"Identificador p\u00fablico hexadecimal de Bulest.","pattern":"^[0-9a-f]{32}$","type":"string"},"meta":{"additionalProperties":true,"properties":{"attachments":{"description":"Lista can\u00f3nica y ordenada de recursos del fragmento. Al editar meta.attachments se reemplaza la lista completa.","items":{"$ref":"#/components/schemas/FragmentAttachment"},"type":"array"}},"type":"object"},"title":{"maxLength":240,"minLength":1,"type":"string"},"type":{"enum":["text","file","product","image","other"],"type":"string"}},"required":["title"],"type":"object"},"summary":{"maxLength":1000,"type":"string"}},"required":["base_revision","fragment"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Solicitud procesada correctamente."},"400":{"description":"Solicitud inv\u00e1lida."},"401":{"description":"Token ausente o inv\u00e1lido."},"403":{"description":"Permiso, alcance o pol\u00edtica insuficiente."},"409":{"description":"Conflicto de versi\u00f3n o estado."},"410":{"description":"El borrador o la sesi\u00f3n ya venci\u00f3."},"413":{"description":"El cuerpo o archivo excede el l\u00edmite permitido."},"429":{"description":"Demasiadas solicitudes; respeta Retry-After si est\u00e1 presente."},"503":{"description":"Una dependencia temporalmente no est\u00e1 disponible."}},"security":[{"bearerAuth":[]}],"summary":"Preparar la edici\u00f3n de un fragmento"}},"/capabilities":{"get":{"description":"Consultar capacidades y agentes autorizados","responses":{"200":{"description":"Solicitud procesada correctamente."},"400":{"description":"Solicitud inv\u00e1lida."},"401":{"description":"Token ausente o inv\u00e1lido."},"403":{"description":"Permiso, alcance o pol\u00edtica insuficiente."},"409":{"description":"Conflicto de versi\u00f3n o estado."},"410":{"description":"El borrador o la sesi\u00f3n ya venci\u00f3."},"413":{"description":"El cuerpo o archivo excede el l\u00edmite permitido."},"429":{"description":"Demasiadas solicitudes; respeta Retry-After si est\u00e1 presente."},"503":{"description":"Una dependencia temporalmente no est\u00e1 disponible."}},"security":[{"bearerAuth":[]}],"summary":"Consultar capacidades y agentes autorizados"}},"/drafts":{"get":{"description":"Listar borradores de la integraci\u00f3n Permiso requerido: `fragments.read`.","responses":{"200":{"description":"Solicitud procesada correctamente."},"400":{"description":"Solicitud inv\u00e1lida."},"401":{"description":"Token ausente o inv\u00e1lido."},"403":{"description":"Permiso, alcance o pol\u00edtica insuficiente."},"409":{"description":"Conflicto de versi\u00f3n o estado."},"410":{"description":"El borrador o la sesi\u00f3n ya venci\u00f3."},"413":{"description":"El cuerpo o archivo excede el l\u00edmite permitido."},"429":{"description":"Demasiadas solicitudes; respeta Retry-After si est\u00e1 presente."},"503":{"description":"Una dependencia temporalmente no est\u00e1 disponible."}},"security":[{"bearerAuth":[]}],"summary":"Listar borradores de la integraci\u00f3n"}},"/drafts/{draft_id}":{"delete":{"description":"Eliminar un borrador abierto Permiso requerido: `fragments.draft`. Sensibilidad: destructiva; solo afecta el borrador.","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"confirm":{"const":true}},"type":"object"}}},"required":false},"responses":{"200":{"description":"Solicitud procesada correctamente."},"400":{"description":"Solicitud inv\u00e1lida."},"401":{"description":"Token ausente o inv\u00e1lido."},"403":{"description":"Permiso, alcance o pol\u00edtica insuficiente."},"409":{"description":"Conflicto de versi\u00f3n o estado."},"410":{"description":"El borrador o la sesi\u00f3n ya venci\u00f3."},"413":{"description":"El cuerpo o archivo excede el l\u00edmite permitido."},"429":{"description":"Demasiadas solicitudes; respeta Retry-After si est\u00e1 presente."},"503":{"description":"Una dependencia temporalmente no est\u00e1 disponible."}},"security":[{"bearerAuth":[]}],"summary":"Eliminar un borrador abierto"},"get":{"description":"Consultar un borrador Permiso requerido: `fragments.read`.","responses":{"200":{"description":"Solicitud procesada correctamente."},"400":{"description":"Solicitud inv\u00e1lida."},"401":{"description":"Token ausente o inv\u00e1lido."},"403":{"description":"Permiso, alcance o pol\u00edtica insuficiente."},"409":{"description":"Conflicto de versi\u00f3n o estado."},"410":{"description":"El borrador o la sesi\u00f3n ya venci\u00f3."},"413":{"description":"El cuerpo o archivo excede el l\u00edmite permitido."},"429":{"description":"Demasiadas solicitudes; respeta Retry-After si est\u00e1 presente."},"503":{"description":"Una dependencia temporalmente no est\u00e1 disponible."}},"security":[{"bearerAuth":[]}],"summary":"Consultar un borrador"},"parameters":[{"description":"ID p\u00fablico del borrador.","in":"path","name":"draft_id","required":true,"schema":{"minLength":1,"type":"string"}}],"patch":{"description":"Actualizar un borrador Permiso requerido: `fragments.draft`. Sensibilidad: borrador reversible.","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"agent":{"additionalProperties":true,"type":"object"},"base_revision":{"description":"Revisi\u00f3n devuelta al leer el recurso; protege de escrituras concurrentes.","minLength":1,"type":"string"},"expires_at":{"format":"date-time","type":"string"},"fragments":{"items":{"additionalProperties":false,"properties":{"active":{"type":"boolean"},"content":{"type":"string"},"id":{"description":"Identificador p\u00fablico hexadecimal de Bulest.","pattern":"^[0-9a-f]{32}$","type":"string"},"meta":{"additionalProperties":true,"properties":{"attachments":{"description":"Lista can\u00f3nica y ordenada de recursos del fragmento. Al editar meta.attachments se reemplaza la lista completa.","items":{"$ref":"#/components/schemas/FragmentAttachment"},"type":"array"}},"type":"object"},"title":{"maxLength":240,"minLength":1,"type":"string"},"type":{"enum":["text","file","product","image","other"],"type":"string"}},"required":["title"],"type":"object"},"type":"array"},"summary":{"maxLength":1000,"type":"string"}},"required":["base_revision"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Solicitud procesada correctamente."},"400":{"description":"Solicitud inv\u00e1lida."},"401":{"description":"Token ausente o inv\u00e1lido."},"403":{"description":"Permiso, alcance o pol\u00edtica insuficiente."},"409":{"description":"Conflicto de versi\u00f3n o estado."},"410":{"description":"El borrador o la sesi\u00f3n ya venci\u00f3."},"413":{"description":"El cuerpo o archivo excede el l\u00edmite permitido."},"429":{"description":"Demasiadas solicitudes; respeta Retry-After si est\u00e1 presente."},"503":{"description":"Una dependencia temporalmente no est\u00e1 disponible."}},"security":[{"bearerAuth":[]}],"summary":"Actualizar un borrador"}},"/drafts/{draft_id}/apply":{"parameters":[{"description":"ID p\u00fablico del borrador.","in":"path","name":"draft_id","required":true,"schema":{"minLength":1,"type":"string"}}],"post":{"description":"Solicitar o ejecutar la aplicaci\u00f3n de un borrador Permiso requerido: `fragments.apply`. Sensibilidad: cambio directo posible; depende de la pol\u00edtica de la integraci\u00f3n.","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"confirm":{"type":"boolean"}},"type":"object"}}},"required":false},"responses":{"200":{"description":"Solicitud procesada correctamente."},"400":{"description":"Solicitud inv\u00e1lida."},"401":{"description":"Token ausente o inv\u00e1lido."},"403":{"description":"Permiso, alcance o pol\u00edtica insuficiente."},"409":{"description":"Conflicto de versi\u00f3n o estado."},"410":{"description":"El borrador o la sesi\u00f3n ya venci\u00f3."},"413":{"description":"El cuerpo o archivo excede el l\u00edmite permitido."},"429":{"description":"Demasiadas solicitudes; respeta Retry-After si est\u00e1 presente."},"503":{"description":"Una dependencia temporalmente no est\u00e1 disponible."}},"security":[{"bearerAuth":[]}],"summary":"Solicitar o ejecutar la aplicaci\u00f3n de un borrador"}},"/files":{"post":{"description":"Subir un archivo reutilizable para fragmentos Permiso requerido: `files.upload`. Sensibilidad: crea un recurso de la cuenta; la vinculaci\u00f3n al agente solo ocurre al preparar y aplicar un borrador.","requestBody":{"content":{"multipart/form-data":{"schema":{"additionalProperties":false,"properties":{"description":{"description":"Descripci\u00f3n opcional para el recurso.","maxLength":1000,"type":"string"},"file":{"description":"Archivo que pertenecer\u00e1 a la cuenta del token.","format":"binary","type":"string"}},"required":["file"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalFileResponse"}}},"description":"Archivo guardado y attachment can\u00f3nico listo para insertarse en meta.attachments."},"400":{"description":"Solicitud inv\u00e1lida."},"401":{"description":"Token ausente o inv\u00e1lido."},"403":{"description":"Permiso, alcance o pol\u00edtica insuficiente."},"409":{"description":"Conflicto de versi\u00f3n o estado."},"410":{"description":"El borrador o la sesi\u00f3n ya venci\u00f3."},"413":{"description":"El cuerpo o archivo excede el l\u00edmite permitido."},"429":{"description":"Demasiadas solicitudes; respeta Retry-After si est\u00e1 presente."},"503":{"description":"Una dependencia temporalmente no est\u00e1 disponible."}},"security":[{"bearerAuth":[]}],"summary":"Subir un archivo reutilizable para fragmentos"}},"/guide":{"get":{"description":"Descubrir capacidades y contrato concedido","responses":{"200":{"description":"Solicitud procesada correctamente."},"400":{"description":"Solicitud inv\u00e1lida."},"401":{"description":"Token ausente o inv\u00e1lido."},"403":{"description":"Permiso, alcance o pol\u00edtica insuficiente."},"409":{"description":"Conflicto de versi\u00f3n o estado."},"410":{"description":"El borrador o la sesi\u00f3n ya venci\u00f3."},"413":{"description":"El cuerpo o archivo excede el l\u00edmite permitido."},"429":{"description":"Demasiadas solicitudes; respeta Retry-After si est\u00e1 presente."},"503":{"description":"Una dependencia temporalmente no est\u00e1 disponible."}},"security":[{"bearerAuth":[]}],"summary":"Descubrir capacidades y contrato concedido"}},"/instances":{"get":{"description":"Listar los canales disponibles para asignar un agente Permiso requerido: `instances.assign`. Sensibilidad: solo lectura; no expone n\u00fameros, claves ni datos del proveedor.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalInstancesResponse"}}},"description":"Canales visibles de la cuenta y su agente asignado."},"400":{"description":"Solicitud inv\u00e1lida."},"401":{"description":"Token ausente o inv\u00e1lido."},"403":{"description":"Permiso, alcance o pol\u00edtica insuficiente."},"409":{"description":"Conflicto de versi\u00f3n o estado."},"410":{"description":"El borrador o la sesi\u00f3n ya venci\u00f3."},"413":{"description":"El cuerpo o archivo excede el l\u00edmite permitido."},"429":{"description":"Demasiadas solicitudes; respeta Retry-After si est\u00e1 presente."},"503":{"description":"Una dependencia temporalmente no est\u00e1 disponible."}},"security":[{"bearerAuth":[]}],"summary":"Listar los canales disponibles para asignar un agente"}},"/instances/{instance_db_id}/agent":{"parameters":[{"description":"ID del canal devuelto por GET /instances.","in":"path","name":"instance_db_id","required":true,"schema":{"minLength":1,"type":"string"}}],"put":{"description":"Asignar o retirar el agente de un canal Permiso requerido: `instances.assign`. Sensibilidad: cambio operativo directo; usa agent_id null para retirar la asignaci\u00f3n actual.","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"agent_id":{"description":"ID de un agente autorizado, o null para dejar el canal sin agente asignado.","oneOf":[{"description":"Identificador p\u00fablico hexadecimal de Bulest.","pattern":"^[0-9a-f]{32}$","type":"string"},{"type":"null"}]}},"required":["agent_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalInstanceAssignmentResponse"}}},"description":"Asignaci\u00f3n procesada."},"400":{"description":"Solicitud inv\u00e1lida."},"401":{"description":"Token ausente o inv\u00e1lido."},"403":{"description":"Permiso, alcance o pol\u00edtica insuficiente."},"409":{"description":"Conflicto de versi\u00f3n o estado."},"410":{"description":"El borrador o la sesi\u00f3n ya venci\u00f3."},"413":{"description":"El cuerpo o archivo excede el l\u00edmite permitido."},"429":{"description":"Demasiadas solicitudes; respeta Retry-After si est\u00e1 presente."},"503":{"description":"Una dependencia temporalmente no est\u00e1 disponible."}},"security":[{"bearerAuth":[]}],"summary":"Asignar o retirar el agente de un canal"}},"/test-chat/messages":{"post":{"description":"Enviar un mensaje al Chat de pruebas Permiso requerido: `chat_test.run`. Sensibilidad: prueba reversible; no altera el agente activo.","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"agent_id":{"description":"Identificador p\u00fablico hexadecimal de Bulest.","pattern":"^[0-9a-f]{32}$","type":"string"},"client_message_id":{"description":"Llave de idempotencia \u00fanica dentro de la sesi\u00f3n.","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,99}$","type":"string"},"draft_id":{"description":"Identificador p\u00fablico hexadecimal de Bulest.","pattern":"^[0-9a-f]{32}$","type":"string"},"message":{"oneOf":[{"additionalProperties":false,"properties":{"content":{"minLength":1,"type":"string"},"type":{"const":"text"}},"required":["type","content"],"type":"object"},{"additionalProperties":false,"properties":{"base64":{"description":"Base64 crudo o data URL.","type":"string"},"caption":{"type":"string"},"filename":{"maxLength":160,"type":"string"},"mime_type":{"maxLength":120,"type":"string"},"type":{"enum":["image","audio","video","file"],"type":"string"}},"required":["type","base64","mime_type"],"type":"object"}]},"session_id":{"maxLength":160,"minLength":1,"type":"string"}},"required":["message"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Solicitud procesada correctamente."},"202":{"description":"Mensaje aceptado para procesamiento as\u00edncrono."},"400":{"description":"Solicitud inv\u00e1lida."},"401":{"description":"Token ausente o inv\u00e1lido."},"403":{"description":"Permiso, alcance o pol\u00edtica insuficiente."},"409":{"description":"Conflicto de versi\u00f3n o estado."},"410":{"description":"El borrador o la sesi\u00f3n ya venci\u00f3."},"413":{"description":"El cuerpo o archivo excede el l\u00edmite permitido."},"429":{"description":"Demasiadas solicitudes; respeta Retry-After si est\u00e1 presente."},"503":{"description":"Una dependencia temporalmente no est\u00e1 disponible."}},"security":[{"bearerAuth":[]}],"summary":"Enviar un mensaje al Chat de pruebas"}},"/test-chat/sessions/{session_id}/messages":{"get":{"description":"Consultar respuestas del Chat de pruebas Permiso requerido: `chat_test.run`.","responses":{"200":{"description":"Solicitud procesada correctamente."},"400":{"description":"Solicitud inv\u00e1lida."},"401":{"description":"Token ausente o inv\u00e1lido."},"403":{"description":"Permiso, alcance o pol\u00edtica insuficiente."},"409":{"description":"Conflicto de versi\u00f3n o estado."},"410":{"description":"El borrador o la sesi\u00f3n ya venci\u00f3."},"413":{"description":"El cuerpo o archivo excede el l\u00edmite permitido."},"429":{"description":"Demasiadas solicitudes; respeta Retry-After si est\u00e1 presente."},"503":{"description":"Una dependencia temporalmente no est\u00e1 disponible."}},"security":[{"bearerAuth":[]}],"summary":"Consultar respuestas del Chat de pruebas"},"parameters":[{"description":"ID de la sesi\u00f3n del Chat de pruebas.","in":"path","name":"session_id","required":true,"schema":{"minLength":1,"type":"string"}}]},"/test-chat/sessions/{session_id}/reset":{"parameters":[{"description":"ID de la sesi\u00f3n del Chat de pruebas.","in":"path","name":"session_id","required":true,"schema":{"minLength":1,"type":"string"}}],"post":{"description":"Reiniciar la memoria aislada de la sesi\u00f3n Permiso requerido: `chat_test.run`. Sensibilidad: destructiva para la memoria ef\u00edmera de pruebas.","responses":{"200":{"description":"Solicitud procesada correctamente."},"400":{"description":"Solicitud inv\u00e1lida."},"401":{"description":"Token ausente o inv\u00e1lido."},"403":{"description":"Permiso, alcance o pol\u00edtica insuficiente."},"409":{"description":"Conflicto de versi\u00f3n o estado."},"410":{"description":"El borrador o la sesi\u00f3n ya venci\u00f3."},"413":{"description":"El cuerpo o archivo excede el l\u00edmite permitido."},"429":{"description":"Demasiadas solicitudes; respeta Retry-After si est\u00e1 presente."},"503":{"description":"Una dependencia temporalmente no est\u00e1 disponible."}},"security":[{"bearerAuth":[]}],"summary":"Reiniciar la memoria aislada de la sesi\u00f3n"}}},"security":[{"bearerAuth":[]}],"servers":[{"url":"https://bulest.co/api/v1/external"}]}