Un artefacto es una pieza de información (o un recurso listo para herramientas) que incorporas a Zylon para poder usarla como contexto en consultas y operaciones. Los artefactos viven dentro de una colección y cada uno tiene un ID artifact estable.
Se pueden crear a partir de:
Tipo Entrada Notas Text Cadena Contenido directo. File Bytes en base64 Para archivos como .txt o .pdf. URI URL Zylon obtiene e ingesta el contenido.
Requisitos previos
Un token de API. Ver Gestión de tokens .
El nombre de host de Zylon (sustituye {BASE_URL} en los ejemplos).
Solicitud y respuesta básica Usa POST /artifacts/ingest cuando quieras que la ingesta termine en la misma petición.
curl -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/ingest" \ -H "Authorization: Bearer {API_TOKEN}" \ -H "Content-Type: application/json" \ -d '{ "collection": "{collectionID}", "artifact": "{artifactID}", "input": { "type": "text", "value": "Release notes: Shipped billing dashboard and fixed three bugs." }, "metadata": { "file_name": "release_notes.txt", "source": "docs" } }'
{ "object" : "list" , "model" : "private-gpt" , "data" : [ { "object" : "ingest.document" , "artifact" : "docs_text_artifact_sync" , "doc_metadata" : { "file_name" : "release_notes.txt" , "source" : "docs" , "headers" : [], "artifact_id" : "docs_text_artifact_sync" , "collection" : "019c7569-f1f3-74da-8017-35d4a11f93ca" , "llm_model" : "default" , "embed_model" : "default" , "hash" : "faf6da679814136cb7cef94532397948cd2cd303b25f91a527af53227e9da99d" } } ] }
Ingesta asíncrona Usa POST /artifacts/ingest/async para cuerpos de petición más grandes o cuando la ingesta pueda tardar. El cuerpo es el mismo que en la ingesta síncrona, envuelto en ingest_body, y la respuesta devuelve un task_id que puedes consultar.
curl -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/ingest/async" \ -H "Authorization: Bearer {API_TOKEN}" \ -H "Content-Type: application/json" \ -d '{ "ingest_body": { "collection": "{collectionID}", "artifact": "{artifactID}", "input": { "type": "text", "value": "Release notes: We shipped a new billing dashboard and fixed three bugs." }, "metadata": { "file_name": "release_notes.txt", "source": "docs" } } }'
curl -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/ingest/async" \ -H "Authorization: Bearer {API_TOKEN}" \ -H "Content-Type: application/json" \ -d '{ "ingest_body": { "collection": "{collectionID}", "artifact": "{artifactID}", "input": { "type": "file", "value": "SGVsbG8gZnJvbSBmaWxlIGFydGlmYWN0Lgo=" }, "metadata": { "file_name": "onboarding_checklist.txt", "source": "docs" } } }'
curl -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/ingest/async" \ -H "Authorization: Bearer {API_TOKEN}" \ -H "Content-Type: application/json" \ -d '{ "ingest_body": { "collection": "{collectionID}", "artifact": "{artifactID}", "input": { "type": "uri", "value": "https://example.com/" }, "metadata": { "file_name": "example.html", "source": "docs" } } }'
{ "task_id" : "f04e0709-131a-4a9d-b884-78872a4e63d7" }
Consultar estado:
curl "https://{BASE_URL}/api/gpt/v1/artifacts/ingest/async/{task_id}" \ -H "Authorization: Bearer {API_TOKEN}"
{ "task_id" : "f04e0709-131a-4a9d-b884-78872a4e63d7" , "task_status" : "PENDING" , "task_result" : null }
Listar artefactos curl "https://{BASE_URL}/api/gpt/v1/artifacts/list?collection={collectionID}" \ -H "Authorization: Bearer {API_TOKEN}"
{ "object" : "list" , "model" : "private-gpt" , "data" : [ { "object" : "ingest.document" , "artifact" : "docs_file_artifact" , "doc_metadata" : { "file_name" : "docs_file_artifact.txt" , "artifact_id" : "docs_file_artifact" , "collection" : "019c7569-f1f3-74da-8017-35d4a11f93ca" } } ] }
Recuperar contenido Contenido completo curl -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/content" \ -H "Authorization: Bearer {API_TOKEN}" \ -H "Content-Type: application/json" \ -d '{ "context_filter": { "collection": "{collectionID}" } }'
{ "data" : [ { "artifact_id" : "docs_file_artifact" , "content" : "Hello from file artifact. \n\n " } ] }
Contenido en fragmentos curl -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/chunked-content" \ -H "Authorization: Bearer {API_TOKEN}" \ -H "Content-Type: application/json" \ -d '{ "context_filter": { "collection": "{collectionID}" }, "max_tokens": 50 }'
{ "data" : [ { "artifact_id" : "docs_file_artifact" , "content" : [ { "type" : "source" , "sources" : [{ "object" : "context.chunk" , "id" : "c5f20f0f-56e6-44e0-99e8-0d4ff4bb87eb" }] }, { "type" : "text" , "text" : "**Context Information**: \n Below is important information..." } ] } ] }
Eliminar artefactos Eliminar (síncrono):
curl -i -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/delete" \ -H "Authorization: Bearer {API_TOKEN}" \ -H "Content-Type: application/json" \ -d '{ "collection": "{collectionID}", "artifact": "{artifactID}" }'
Eliminar (asíncrono):
curl -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/delete/async" \ -H "Authorization: Bearer {API_TOKEN}" \ -H "Content-Type: application/json" \ -d '{ "delete_body": { "collection": "{collectionID}", "artifact": "{artifactID}" } }'
{ "task_id" : "2d48e74f-3eff-474e-b338-a931390ac218" }
Consultar estado:
curl "https://{BASE_URL}/api/gpt/v1/artifacts/delete/async/{task_id}" \ -H "Authorization: Bearer {API_TOKEN}"
{ "task_id" : "2d48e74f-3eff-474e-b338-a931390ac218" , "task_status" : "PENDING" , "task_result" : null }
Sigue consultando hasta que task_status sea "SUCCESS" o "FAILURE".
Si falla mientras el índice se completa, reintenta luego.
Errores y casos límite
401/403 : token ausente o permisos insuficientes.404 : colección o artefacto no encontrado.409 : tarea de ingesta/eliminación ya en progreso.413 : entrada demasiado grande para una ingesta.422 : cuerpo de la petición inválido.Fallos asíncronos : cuando task_status es FAILURE, revisa task_result (por ejemplo routing_key_error: "ingest.failed" o delete.failed) y reintenta tras corregir la entrada. 
