Artifacts

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. See Backoffice Developer Console.
Your Zylon hostname (replace {BASE_URL} in the examples).

Basic request and response

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

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"
    }
  }'

Example response

{
  "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"
      }
    }
  ]
}

Async ingest

Use POST /artifacts/ingest/async for larger payloads or when ingest may take longer. The payload is the same as sync ingest, wrapped in ingest_body, and the response returns a task_id you can poll.

Text
File
URI

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"
      }
    }
  }'

Example response

{ "task_id": "f04e0709-131a-4a9d-b884-78872a4e63d7" }

Check task status:

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

Example response

{
  "task_id": "f04e0709-131a-4a9d-b884-78872a4e63d7",
  "task_status": "PENDING",
  "task_result": null
}

Listing ingested artifacts

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

Example response

{
  "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"
      }
    }
  ]
}

Retrieving content

Full content

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

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}"
    }
  }'

Example response

{
  "data": [
    {
      "artifact_id": "docs_file_artifact",
      "content": "Hello from file artifact.\n\n"
    }
  ]
}

Chunked content (chat-optimized)

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

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
  }'

Example response

{
  "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..." }
      ]
    }
  ]
}

Deleting artifacts

Delete (sync):

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}"
  }'

Example response

HTTP/2 200

null

Delete (async):

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}"
    }
  }'

Example response

{ "task_id": "2d48e74f-3eff-474e-b338-a931390ac218" }

Check task status:

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

Example response

{
  "task_id": "2d48e74f-3eff-474e-b338-a931390ac218",
  "task_status": "PENDING",
  "task_result": null
}

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

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.

First Steps

Build with Zylon

Coding Agents

Prerequisites

Basic request and response

Async ingest

Listing ingested artifacts

Retrieving content

Full content

Chunked content (chat-optimized)

Deleting artifacts

Errors and edge cases

​Prerequisites

​Basic request and response

​Async ingest

​Listing ingested artifacts

​Retrieving content

​Full content

​Chunked content (chat-optimized)

​Deleting artifacts

​Errors and edge cases

Prerequisites

Basic request and response

Async ingest

Listing ingested artifacts

Retrieving content

Full content

Chunked content (chat-optimized)

Deleting artifacts

Errors and edge cases