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

# Artifacts

> Create and ingest ZylonGPT artifacts for retrieval and context.

<Warning>
  **Upcoming release — Zylon 1.58**

  These docs are published ahead of release so you can prepare your API integrations. The release image is not yet available. For installations running 1.57, use the [1.57 documentation](/en/v1.57/overview).
</Warning>

An **artifact** is a piece of information (or tool-ready resource) you ingest into Zylon so it can be used as context for queries and operations. Artifacts live inside a **collection**, and each artifact has a stable `artifact` ID.

Artifacts can be created from:

| Type | Input | Notes |
| - | - | - |
| **Text** | Raw string | Provide content directly. |
| **File** | Base64 bytes | For files like `.txt` or `.pdf`. |
| **URI** | URL | Zylon fetches and ingests the content. |

## Prerequisites

* An API token with the required write scope. See [Backoffice Developer Console](/en/v1.58/developer-manual/get-started/developer-console) or [Token Management](/en/v1.58/developer-manual/get-started/token-management).
* Your Zylon hostname (replace `{BASE_URL}` in the examples).

<Warning>
  Every ZylonGPT artifact operation—including ingest, list, content retrieval, task status, and delete—requires a read-write scope. `PrivateGPT.Read.All` and `Read.All` with `gateway_id` return `403` for all artifact routes. A `Read.All` token without gateway context cannot call ZylonGPT at all.
</Warning>

## Basic request and response

Use `POST /artifacts/ingest` when you want the ingest to complete in the same request.

```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="Example response">
  ```json theme={null}
  {
    "object": "list",
    "model": "private-gpt",
    "data": [
      {
        "object": "ingest.document",
        "artifact": "docs_text_artifact_sync",
        "doc_metadata": {
          "file_name": "release_notes.txt"
        }
      }
    ]
  }
  ```
</Accordion>

<Accordion title="Sync ingest response fields">
  | Field | Type | Meaning |
  | - | - | - |
  | `object`, `model` | string | Response kind and model. |
  | `data` | object\[] | Ingested document references. |
  | `data[].object`, `data[].artifact` | string | Document kind and artifact ID. |
  | `data[].doc_metadata` | object | Optional nullable string fields: `window`, `original_text`, `page_label`, `file_name`, `doc_id`. |
  | `callback.properties` | JSON or null | Optional returned metadata; this is a literal top-level key, not a nested object. |

  Nullable fields may be omitted. Arbitrary upstream document metadata is not included in the synchronous ingest response.
</Accordion>

## Async ingest

Use `POST /artifacts/ingest/async` for larger payloads or when ingest may take longer. Wrap the sync ingest payload in `ingest_body` and include the required `callback` object. Use `callback: {}` when polling without callback configuration. The response returns a `task_id` you can poll.

<Accordion title="Endpoint parameters">
  | Type | Name | Required | Notes |
  | - | - | - | - |
  | Body | `ingest_body` | Yes | Sync ingest body with required `collection`, `artifact`, and `input`; optional `metadata`. |
  | Body | `callback` | Yes | Callback object; `{}` is accepted. Optional `properties` carries correlation data. |
</Accordion>

<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"
          }
        },
        "callback": {}
      }'
    ```
  </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"
          }
        },
        "callback": {}
      }'
    ```
  </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"
          }
        },
        "callback": {}
      }'
    ```
  </Tab>
</Tabs>

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

Check task status:

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

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

## Listing ingested artifacts

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

<Accordion title="Example response">
  ```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>

## Retrieving content

### Full content

Use `POST /artifacts/content` to fetch complete document text:

```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="Example response">
  ```json theme={null}
  {
    "data": [
      {
        "artifact_id": "docs_file_artifact",
        "content": "Hello from file artifact.\n\n"
      }
    ]
  }
  ```
</Accordion>

### Chunked content (chat-optimized)

Use `POST /artifacts/chunked-content` to retrieve content split into chat-friendly blocks:

```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="Example response">
  ```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>

## Deleting artifacts

Delete (sync):

```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="Example response">
  ```text theme={null}
  HTTP/2 200

  null
  ```
</Accordion>

Delete (async):

```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="Example response">
  ```json theme={null}
  { "task_id": "2d48e74f-3eff-474e-b338-a931390ac218" }
  ```
</Accordion>

Check task status:

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

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

<Tip>
  Keep polling until `task_status` becomes `"SUCCESS"` or `"FAILURE"`.
  If deletion fails while an index is still being populated, retry after a short delay.
</Tip>

## Errors and edge cases

* **401/403**: missing token or insufficient permissions.
* **404**: collection or artifact not found.
* **409**: ingest/delete task already in progress.
* **413**: input too large for a single ingest.
* **422**: invalid payload shape.
* **Async failures**: when `task_status` becomes `FAILURE`, check `task_result` (for example `routing_key_error: "ingest.failed"` or `delete.failed`) and retry after fixing the input.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.