Artefactos

Un artefacto es una pieza de información o herramienta que le entregas a Zylon para usarla como contexto en consultas y operaciones. La Workspace API agrupa los artefactos en documentos, agent flows y otros artefactos.

Requisitos previos

Un token de API. Ver Gestión de tokens.
El nombre de host de Zylon (sustituye {BASE_URL} en los ejemplos).

Categoría	Incluye	Cuándo usar
Artefactos de documento	Documentos, carpetas, enlaces	Guardar u organizar contenido en un proyecto.
Agent flows	`Summary`, composición, extracción	Ejecutar flujos sobre artefactos para producir resultados.
Otros artefactos	Servidores MCP, bases de datos SQL	Conectar herramientas o fuentes externas.

Artefactos de documento

Los documentos contienen contenido, los enlaces referencian artefactos existentes y las carpetas organizan artefactos dentro de un proyecto.

Document
Folder
Link

curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "InlineText",
    "source": "User",
    "name": "Q1 Support Summary",
    "description": "Weekly summary notes.",
    "props": {
      "content": "Ticket volume rose 12% week-over-week. Billing issues drove 38% of cases."
    }
  }'

Ejemplo de respuesta

{
  "id": "artifact_doc_q1",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "name": "Q1 Support Summary",
  "type": "InlineText",
  "source": "User",
  "state": "Published",
  "ingest_status": "NotApplicable",
  "props": {
    "content": "Ticket volume rose 12% week-over-week. Billing issues drove 38% of cases."
  },
  "created_at": "2026-02-08T14:30:12Z",
  "updated_at": "2026-02-08T14:31:02Z"
}

curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Folder",
    "source": "User",
    "name": "Q1 Support",
    "description": "Artifacts for Q1 support work.",
    "props": {}
  }'

Ejemplo de respuesta

{
  "id": "artifact_folder_q1",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "name": "Q1 Support",
  "type": "Folder",
  "source": "User",
  "state": "Ready",
  "child_count": 0,
  "ingest_status": "NotApplicable",
  "props": {},
  "created_at": "2026-02-08T14:32:10Z",
  "updated_at": "2026-02-08T14:32:10Z"
}

curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Link",
    "source": "User",
    "name": "Q1 Support Summary (link)",
    "description": "Reference to the canonical document.",
    "props": {
      "source_artifact_id": "{artifactID}",
      "original_artifact_id": "{artifactID}"
    }
  }'

Ejemplo de respuesta

{
  "id": "artifact_link_q1",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "name": "Q1 Support Summary (link)",
  "type": "Link",
  "source": "User",
  "state": "Ready",
  "ingest_status": "NotApplicable",
  "props": {
    "source_artifact_id": "artifact_doc_q1",
    "original_artifact_id": "artifact_doc_q1"
  },
  "created_at": "2026-02-08T14:33:22Z",
  "updated_at": "2026-02-08T14:33:22Z"
}

Agent flows

Los agent flows ejecutan un flujo de trabajo de Zylon sobre uno o más artefactos para producir un resultado estructurado.

Summary
Composition
BulkQA
ReadAndExtract
SmartDoc

curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Summary",
    "source": "User",
    "name": "Q1 Support Summary (auto)",
    "props": {
      "artifact_ids": ["{artifactID}"],
      "style": "Neutral",
      "detail": "KeyPoints",
      "instructions": ["Focus on billing and onboarding trends."]
    }
  }'

Ejemplo de respuesta

{
  "id": "artifact_summary_q1",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "type": "Summary",
  "state": "Processing",
  "ingest_status": "Processing",
  "props": {
    "artifact_ids": ["artifact_doc_q1"],
    "style": "Neutral",
    "detail": "KeyPoints",
    "instructions": ["Focus on billing and onboarding trends."]
  },
  "created_at": "2026-02-08T15:10:00Z"
}

curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Composition",
    "source": "User",
    "name": "Q1 Support Brief",
    "props": {
      "artifact_ids": ["{artifactID}"],
      "style": "Expert",
      "detail": "LongPieces",
      "instructions": "Draft a one-page summary for leadership."
    }
  }'

Ejemplo de respuesta

{
  "id": "artifact_comp_q1",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "type": "Composition",
  "state": "Processing",
  "ingest_status": "Processing",
  "props": {
    "artifact_ids": ["artifact_doc_q1"],
    "style": "Expert",
    "detail": "LongPieces",
    "instructions": "Draft a one-page summary for leadership."
  },
  "created_at": "2026-02-08T15:12:40Z"
}

curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "BulkQA",
    "source": "User",
    "name": "Billing FAQ",
    "props": {
      "artifact_ids": ["{artifactID}"],
      "style": "Simple",
      "detail": "Concise",
      "instructions": ["Answer using only the artifacts."],
      "questions": [
        "What are the top billing issues?",
        "How quickly were priority bugs resolved?"
      ]
    }
  }'

Ejemplo de respuesta

{
  "id": "artifact_bulkqa_q1",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "type": "BulkQA",
  "state": "Processing",
  "ingest_status": "Processing",
  "props": {
    "artifact_ids": ["artifact_doc_q1"],
    "style": "Simple",
    "detail": "Concise",
    "instructions": ["Answer using only the artifacts."],
    "questions": [
      "What are the top billing issues?",
      "How quickly were priority bugs resolved?"
    ]
  },
  "created_at": "2026-02-08T15:14:10Z"
}

curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ReadAndExtract",
    "source": "User",
    "name": "Contract extraction",
    "props": {
      "artifact_ids": ["{artifactID}"],
      "sections": [
        { "title": "Term", "description": "Contract term in months", "id": "term" },
        { "title": "SLA", "description": "Support response time", "id": "sla" }
      ]
    }
  }'

Ejemplo de respuesta

{
  "id": "artifact_readextract_v3",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "type": "ReadAndExtract",
  "state": "Processing",
  "ingest_status": "Processing",
  "props": {
    "artifact_ids": ["artifact_doc_q1"],
    "sections": [
      { "title": "Term", "description": "Contract term in months", "id": "term" },
      { "title": "SLA", "description": "Support response time", "id": "sla" }
    ]
  },
  "created_at": "2026-02-08T15:15:55Z"
}

curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SmartDoc",
    "source": "User",
    "name": "Onboarding SmartDoc",
    "props": {
      "artifact_ids": ["{artifactID}"]
    }
  }'

Ejemplo de respuesta

{
  "id": "artifact_smartdoc_q1",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "type": "SmartDoc",
  "state": "Processing",
  "ingest_status": "Processing",
  "props": {
    "artifact_ids": ["artifact_doc_q1"]
  },
  "created_at": "2026-02-08T15:17:20Z"
}

Otros artefactos

Los artefactos de conector almacenan integraciones para herramientas. private_props solo se usa en artefactos MCP y SqlDatabase.

SqlDatabase
McpServer

curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SqlDatabase",
    "source": "User",
    "name": "Sales database",
    "description": "Read-only reporting database.",
    "props": {
      "schemas": ["public", "analytics"],
      "tables": ["orders", "customers"],
      "ssl": true,
      "enable_tables": true,
      "enable_views": true,
      "enable_procedures": false,
      "enable_functions": false
    },
    "private_props": {
      "connection_string": "postgresql://readonly:***@db.example.com:5432/sales"
    }
  }'

Ejemplo de respuesta

{
  "id": "artifact_db_sales",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "type": "SqlDatabase",
  "state": "Ready",
  "ingest_status": "NotApplicable",
  "props": {
    "schemas": ["public", "analytics"],
    "tables": ["orders", "customers"],
    "ssl": true,
    "enable_tables": true,
    "enable_views": true,
    "enable_procedures": false,
    "enable_functions": false
  },
  "created_at": "2026-02-08T15:20:05Z"
}

curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "McpServer",
    "source": "User",
    "name": "Internal tools",
    "props": {
      "name": "internal_mcp",
      "tool_configuration": {
        "enabled": true,
        "allowed_tools": ["crm_lookup", "ticket_search"]
      }
    },
    "private_props": {
      "url": "https://mcp.internal.zylon",
      "authorization_token": "***"
    }
  }'

Ejemplo de respuesta

{
  "id": "artifact_mcp_internal",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "type": "McpServer",
  "state": "Ready",
  "ingest_status": "NotApplicable",
  "props": {
    "name": "internal_mcp",
    "tool_configuration": {
      "enabled": true,
      "allowed_tools": ["crm_lookup", "ticket_search"]
    }
  },
  "created_at": "2026-02-08T15:22:30Z"
}

Para recuperar los detalles privados de estos artefactos: GET /api/v1/app/project/{projectId}/artifact/{artifactId}/private Solo el creador del artefacto puede acceder a los detalles privados.

Trabajar con artefactos

Listar artefactos

curl "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact?page=1&page_size=20" \
  -H "Authorization: Bearer {API_TOKEN}"

Ejemplo de respuesta

{
  "data": [
    {
      "id": "artifact_doc_q1",
      "project_id": "proj_7a5c3e1b9d2f4a6c",
      "name": "Q1 Support Summary",
      "type": "Document",
      "source": "User",
      "state": "Ready",
      "ingest_status": "Done",
      "has_content": true,
      "created_at": "2026-02-08T14:30:12Z",
      "updated_at": "2026-02-08T14:31:02Z"
    }
  ],
  "has_next_page": false,
  "has_previous_page": false,
  "total_count": 1
}

Obtener un artefacto

curl "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact/{artifactID}" \
  -H "Authorization: Bearer {API_TOKEN}"

Ejemplo de respuesta

{
  "id": "artifact_doc_q1",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "name": "Q1 Support Summary",
  "type": "Document",
  "source": "User",
  "state": "Ready",
  "ingest_status": "Done",
  "has_content": true,
  "created_at": "2026-02-08T14:30:12Z",
  "updated_at": "2026-02-08T14:31:02Z"
}

Actualizar un artefacto

curl -X PUT "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact/{artifactID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 Support Summary (final)",
    "description": "Finalized weekly summary notes.",
    "plain_text_content": "Ticket volume rose 12% week-over-week..."
  }'

Ejemplo de respuesta

{
  "id": "artifact_doc_q1",
  "name": "Q1 Support Summary (final)",
  "description": "Finalized weekly summary notes.",
  "type": "Document",
  "source": "User",
  "ingest_status": "Done",
  "updated_at": "2026-02-08T14:45:21Z"
}

Eliminar un artefacto

curl -X DELETE "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact/{artifactID}" \
  -H "Authorization: Bearer {API_TOKEN}"

Ejemplo de respuesta

{
  "id": "artifact_doc_q1",
  "state": "Deleted"
}

Metadatos privados del artefacto

curl "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact/{artifactID}/private" \
  -H "Authorization: Bearer {API_TOKEN}"

Ejemplo de respuesta (props privadas MCP)

{
  "connection_string": "postgresql://readonly:***@db.example.com:5432/sales"
}

Descargar contenido sin procesar

curl "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact/{artifactID}/download" \
  -H "Authorization: Bearer {API_TOKEN}"

Ejemplo de respuesta

Ticket volume rose 12% week-over-week. Billing issues drove 38% of cases.

Obtener contenido procesado

Este endpoint solo está disponible cuando el artefacto tiene un índice vectorial inicializado. En la práctica, esto suele implicar documentos de conectores o artefactos con indexación ya completada.

Sincronizar un artefacto

Este endpoint se utiliza principalmente con artefactos de integración (SharePoint, Confluence, Claromentis o FileSystem).

Errores y casos límite

Códigos de error de artefacto: el campo error refleja fallos de ingesta:

valor `error`	Significado
`InvalidExtension`	Extensión de archivo no admitida.
`MismatchedType`	El tipo de archivo no coincide con el tipo declarado.
`Malformed`	Archivo corrupto o ilegible.
`Encrypted`	Archivo protegido con contraseña.
`ParsingFailure`	El extractor no pudo analizar el archivo.
`MaxNodes`	Documento demasiado grande o complejo para el análisis.
`NoValidFile`	No se encontró un archivo válido.
`NoValidNodes`	No se pudo extraer contenido analizable.
`InternalError`	Fallo inesperado en la ingesta.
`Unknown`	Fallo no clasificado.

Si ingest_status es Error, corrige el archivo (o conviértelo) y re‑sincroniza.

Advertencias: ingest_warnings puede incluir valores como BigSize, UnprocessableContent o NoContent para indicar problemas no fatales.
401/403: token ausente o permisos insuficientes.
404: artefacto o proyecto no encontrado.
409: artefacto ya en proceso.
413: el contenido supera el tamaño recomendado (250 MB).

Primeros pasos

Construye con Zylon

Artefactos

Requisitos previos

Artefactos

Artefactos de documento

Agent flows

Otros artefactos

Trabajar con artefactos

Listar artefactos

Obtener un artefacto

Actualizar un artefacto

Eliminar un artefacto

Metadatos privados del artefacto

Descargar contenido sin procesar

Obtener contenido procesado

Sincronizar un artefacto

Errores y casos límite

Primeros pasos

Construye con Zylon

​Requisitos previos

​Artefactos

​Artefactos de documento

​Agent flows

​Otros artefactos

​Trabajar con artefactos

​Listar artefactos

​Obtener un artefacto

​Actualizar un artefacto

​Eliminar un artefacto

​Metadatos privados del artefacto

​Descargar contenido sin procesar

​Obtener contenido procesado

​Sincronizar un artefacto

​Errores y casos límite

Requisitos previos

Artefactos

Artefactos de documento

Agent flows

Otros artefactos

Trabajar con artefactos

Listar artefactos

Obtener un artefacto

Actualizar un artefacto

Eliminar un artefacto

Metadatos privados del artefacto

Descargar contenido sin procesar

Obtener contenido procesado

Sincronizar un artefacto

Errores y casos límite