> ## 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.

# Artefactos

> Crea e ingesta artefactos de ZylonGPT para recuperación y contexto.

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 [Backoffice Developer Console](/es/developer-manual/get-started/developer-console).
* 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.

```bash theme={null}
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"
    }
  }'
```

<Accordion title="Ejemplo de respuesta">
  ```json theme={null}
  {
    "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"
        }
      }
    ]
  }
  ```
</Accordion>

## 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.

<Tabs>
  <Tab title="Text">
    ```bash theme={null}
    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"
          }
        }
      }'
    ```
  </Tab>

  <Tab title="File">
    ```bash theme={null}
    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"
          }
        }
      }'
    ```
  </Tab>

  <Tab title="URI">
    ```bash theme={null}
    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"
          }
        }
      }'
    ```
  </Tab>
</Tabs>

<Accordion title="Ejemplo de respuesta">
  ```json theme={null}
  { "task_id": "f04e0709-131a-4a9d-b884-78872a4e63d7" }
  ```
</Accordion>

Consultar estado:

```bash theme={null}
curl "https://{BASE_URL}/api/gpt/v1/artifacts/ingest/async/{task_id}" \
  -H "Authorization: Bearer {API_TOKEN}"
```

<Accordion title="Ejemplo de respuesta">
  ```json theme={null}
  {
    "task_id": "f04e0709-131a-4a9d-b884-78872a4e63d7",
    "task_status": "PENDING",
    "task_result": null
  }
  ```
</Accordion>

## Listar artefactos

```bash theme={null}
curl "https://{BASE_URL}/api/gpt/v1/artifacts/list?collection={collectionID}" \
  -H "Authorization: Bearer {API_TOKEN}"
```

<Accordion title="Ejemplo de respuesta">
  ```json theme={null}
  {
    "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"
        }
      }
    ]
  }
  ```
</Accordion>

## Recuperar contenido

### Contenido completo

```bash theme={null}
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}"
    }
  }'
```

<Accordion title="Ejemplo de respuesta">
  ```json theme={null}
  {
    "data": [
      {
        "artifact_id": "docs_file_artifact",
        "content": "Hello from file artifact.\n\n"
      }
    ]
  }
  ```
</Accordion>

### Contenido en fragmentos

```bash theme={null}
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
  }'
```

<Accordion title="Ejemplo de respuesta">
  ```json theme={null}
  {
    "data": [
      {
        "artifact_id": "docs_file_artifact",
        "content": [
          { "type": "source", "sources": [{ "object": "context.chunk", "id": "c5f20f0f-56e6-44e0-99e8-0d4ff4bb87eb" }] },
          { "type": "text", "text": "**Context Information**:\nBelow is important information..." }
        ]
      }
    ]
  }
  ```
</Accordion>

## Eliminar artefactos

Eliminar (síncrono):

```bash theme={null}
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}"
  }'
```

<Accordion title="Ejemplo de respuesta">
  ```text theme={null}
  HTTP/2 200

  null
  ```
</Accordion>

Eliminar (asíncrono):

```bash theme={null}
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}"
    }
  }'
```

<Accordion title="Ejemplo de respuesta">
  ```json theme={null}
  { "task_id": "2d48e74f-3eff-474e-b338-a931390ac218" }
  ```
</Accordion>

Consultar estado:

```bash theme={null}
curl "https://{BASE_URL}/api/gpt/v1/artifacts/delete/async/{task_id}" \
  -H "Authorization: Bearer {API_TOKEN}"
```

<Accordion title="Ejemplo de respuesta">
  ```json theme={null}
  {
    "task_id": "2d48e74f-3eff-474e-b338-a931390ac218",
    "task_status": "PENDING",
    "task_result": null
  }
  ```
</Accordion>

<Tip>
  Sigue consultando hasta que `task_status` sea `"SUCCESS"` o `"FAILURE"`.
  Si falla mientras el índice se completa, reintenta luego.
</Tip>

## 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.