Documentation Index Fetch the complete documentation index at: https://docs.zylon.ai/llms.txt
Use this file to discover all available pages before exploring further.
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 Artefactos 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ónEjecutar 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.
curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \ -H "Authorization: Bearer {API_TOKEN}" \ -H "x-org: {org_slug}" \ -F 'type=Document' \ -F 'name=Q1 Support Summary' \ -F 'props={ "content_type":"text/plain", "file_name":"q1-support-summary.txt" };type=application/json' \ -F 'fileData=@./q1-support-summary.txt;type=text/plain'
{ "id" : "artifact_doc_q1" , "project_id" : "proj_7a5c3e1b9d2f4a6c" , "name" : "Q1 Support Summary" , "type" : "Document" , "source" : "User" , "state" : "Ready" , "ingest_status" : "Done" , "has_content" : true , "props" : { "file_name" : "q1-support-summary.txt" , "content_type" : "text/plain" , "content_length" : 79 }, "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 "x-org: {org_slug}" \ -H "Content-Type: application/json" \ -d '{ "type": "Folder", "source": "User", "name": "Q1 Support", "description": "Artifacts for Q1 support work.", "props": {} }'
{ "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 "x-org: {org_slug}" \ -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}" } }'
{ "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 "x-org: {org_slug}" \ -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."] } }'
{ "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 "x-org: {org_slug}" \ -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." } }'
{ "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 "x-org: {org_slug}" \ -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?" ] } }'
{ "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 "x-org: {org_slug}" \ -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" } ] } }'
{ "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 "x-org: {org_slug}" \ -H "Content-Type: application/json" \ -d '{ "type": "SmartDoc", "source": "User", "name": "Onboarding SmartDoc", "props": { "artifact_ids": ["{artifactID}"] } }'
{ "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 .
curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \ -H "Authorization: Bearer {API_TOKEN}" \ -H "x-org: {org_slug}" \ -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" } }'
{ "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 "x-org: {org_slug}" \ -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": "***" } }'
{ "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}/privateSolo 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}" -H "x-org: {org_slug}"
{ "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}" -H "x-org: {org_slug}"
{ "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 "x-org: {org_slug}" \ -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..." }'
{ "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}" -H "x-org: {org_slug}"
{ "id" : "artifact_doc_q1" , "state" : "Deleted" }
curl "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact/{artifactID}/private" \ -H "Authorization: Bearer {API_TOKEN}" -H "x-org: {org_slug}"
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}" -H "x-org: {org_slug}"
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 InvalidExtensionExtensión de archivo no admitida. MismatchedTypeEl tipo de archivo no coincide con el tipo declarado. MalformedArchivo corrupto o ilegible. EncryptedArchivo protegido con contraseña. ParsingFailureEl extractor no pudo analizar el archivo. MaxNodesDocumento demasiado grande o complejo para el análisis. NoValidFileNo se encontró un archivo válido. NoValidNodesNo se pudo extraer contenido analizable. InternalErrorFallo inesperado en la ingesta. UnknownFallo 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). 
