Artifacts

Upcoming release — Zylon 1.58These 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.

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 or Token Management.
Your Zylon hostname (replace {BASE_URL} in the examples).

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.

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

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.

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.

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.

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"
      }
    },
    "callback": {}
  }'

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

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

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