Artifacts

An artifact is a piece of information or tool you provide to Zylon so it can be used as context for queries and operations. The Workspace API groups artifacts into document artifacts, agent flows, and other artifacts.

Prerequisites

An API token. See Token Management.
Your Zylon hostname (replace {BASE_URL} in the examples).

Category	Includes	When to use
Document artifacts	Documents, folders, links	Store or organize content inside a project.
Agent flows	Summary, composition, extraction flows	Run workflows across artifacts to produce outputs.
Other artifacts	MCP servers, SQL databases	Provide external tools or data sources.

Document artifacts

Document artifacts hold content, links reference existing artifacts, and folders organize artifacts inside a project.

Document
Folder
Link

curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "InlineText",
    "source": "User",
    "name": "Q1 Support Summary",
    "description": "Weekly summary notes.",
    "props": {
      "content": "Ticket volume rose 12% week-over-week. Billing issues drove 38% of cases."
    }
  }'

Example response

{
  "id": "artifact_doc_q1",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "name": "Q1 Support Summary",
  "type": "InlineText",
  "source": "User",
  "state": "Published",
  "ingest_status": "NotApplicable",
  "props": {
    "content": "Ticket volume rose 12% week-over-week. Billing issues drove 38% of cases."
  },
  "created_at": "2026-02-08T14:30:12Z",
  "updated_at": "2026-02-08T14:31:02Z"
}

curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Folder",
    "source": "User",
    "name": "Q1 Support",
    "description": "Artifacts for Q1 support work.",
    "props": {}
  }'

Example response

{
  "id": "artifact_folder_q1",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "name": "Q1 Support",
  "type": "Folder",
  "source": "User",
  "state": "Ready",
  "child_count": 0,
  "ingest_status": "NotApplicable",
  "props": {},
  "created_at": "2026-02-08T14:32:10Z",
  "updated_at": "2026-02-08T14:32:10Z"
}

curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Link",
    "source": "User",
    "name": "Q1 Support Summary (link)",
    "description": "Reference to the canonical document.",
    "props": {
      "source_artifact_id": "{artifactID}",
      "original_artifact_id": "{artifactID}"
    }
  }'

Example response

{
  "id": "artifact_link_q1",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "name": "Q1 Support Summary (link)",
  "type": "Link",
  "source": "User",
  "state": "Ready",
  "ingest_status": "NotApplicable",
  "props": {
    "source_artifact_id": "artifact_doc_q1",
    "original_artifact_id": "artifact_doc_q1"
  },
  "created_at": "2026-02-08T14:33:22Z",
  "updated_at": "2026-02-08T14:33:22Z"
}

Agent flows

Agent flows run a Zylon workflow across one or more artifacts to produce a structured output.

Summary
Composition
BulkQA
ReadAndExtract
SmartDoc

curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Summary",
    "source": "User",
    "name": "Q1 Support Summary (auto)",
    "props": {
      "artifact_ids": ["{artifactID}"],
      "style": "Neutral",
      "detail": "KeyPoints",
      "instructions": ["Focus on billing and onboarding trends."]
    }
  }'

Example response

{
  "id": "artifact_summary_q1",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "type": "Summary",
  "state": "Processing",
  "ingest_status": "Processing",
  "props": {
    "artifact_ids": ["artifact_doc_q1"],
    "style": "Neutral",
    "detail": "KeyPoints",
    "instructions": ["Focus on billing and onboarding trends."]
  },
  "created_at": "2026-02-08T15:10:00Z"
}

curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Composition",
    "source": "User",
    "name": "Q1 Support Brief",
    "props": {
      "artifact_ids": ["{artifactID}"],
      "style": "Expert",
      "detail": "LongPieces",
      "instructions": "Draft a one-page summary for leadership."
    }
  }'

Example response

{
  "id": "artifact_comp_q1",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "type": "Composition",
  "state": "Processing",
  "ingest_status": "Processing",
  "props": {
    "artifact_ids": ["artifact_doc_q1"],
    "style": "Expert",
    "detail": "LongPieces",
    "instructions": "Draft a one-page summary for leadership."
  },
  "created_at": "2026-02-08T15:12:40Z"
}

curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "BulkQA",
    "source": "User",
    "name": "Billing FAQ",
    "props": {
      "artifact_ids": ["{artifactID}"],
      "style": "Simple",
      "detail": "Concise",
      "instructions": ["Answer using only the artifacts."],
      "questions": [
        "What are the top billing issues?",
        "How quickly were priority bugs resolved?"
      ]
    }
  }'

Example response

{
  "id": "artifact_bulkqa_q1",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "type": "BulkQA",
  "state": "Processing",
  "ingest_status": "Processing",
  "props": {
    "artifact_ids": ["artifact_doc_q1"],
    "style": "Simple",
    "detail": "Concise",
    "instructions": ["Answer using only the artifacts."],
    "questions": [
      "What are the top billing issues?",
      "How quickly were priority bugs resolved?"
    ]
  },
  "created_at": "2026-02-08T15:14:10Z"
}

curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ReadAndExtract",
    "source": "User",
    "name": "Contract extraction",
    "props": {
      "artifact_ids": ["{artifactID}"],
      "sections": [
        { "title": "Term", "description": "Contract term in months", "id": "term" },
        { "title": "SLA", "description": "Support response time", "id": "sla" }
      ]
    }
  }'

Example response

{
  "id": "artifact_readextract_v3",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "type": "ReadAndExtract",
  "state": "Processing",
  "ingest_status": "Processing",
  "props": {
    "artifact_ids": ["artifact_doc_q1"],
    "sections": [
      { "title": "Term", "description": "Contract term in months", "id": "term" },
      { "title": "SLA", "description": "Support response time", "id": "sla" }
    ]
  },
  "created_at": "2026-02-08T15:15:55Z"
}

curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SmartDoc",
    "source": "User",
    "name": "Onboarding SmartDoc",
    "props": {
      "artifact_ids": ["{artifactID}"]
    }
  }'

Example response

{
  "id": "artifact_smartdoc_q1",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "type": "SmartDoc",
  "state": "Processing",
  "ingest_status": "Processing",
  "props": {
    "artifact_ids": ["artifact_doc_q1"]
  },
  "created_at": "2026-02-08T15:17:20Z"
}

Other artifacts

Connector artifacts store tool integrations. private_props is only used for MCP and SQL database artifacts.

SqlDatabase
McpServer

curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SqlDatabase",
    "source": "User",
    "name": "Sales database",
    "description": "Read-only reporting database.",
    "props": {
      "schemas": ["public", "analytics"],
      "tables": ["orders", "customers"],
      "ssl": true,
      "enable_tables": true,
      "enable_views": true,
      "enable_procedures": false,
      "enable_functions": false
    },
    "private_props": {
      "connection_string": "postgresql://readonly:***@db.example.com:5432/sales"
    }
  }'

Example response

{
  "id": "artifact_db_sales",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "type": "SqlDatabase",
  "state": "Ready",
  "ingest_status": "NotApplicable",
  "props": {
    "schemas": ["public", "analytics"],
    "tables": ["orders", "customers"],
    "ssl": true,
    "enable_tables": true,
    "enable_views": true,
    "enable_procedures": false,
    "enable_functions": false
  },
  "created_at": "2026-02-08T15:20:05Z"
}

curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "McpServer",
    "source": "User",
    "name": "Internal tools",
    "props": {
      "name": "internal_mcp",
      "tool_configuration": {
        "enabled": true,
        "allowed_tools": ["crm_lookup", "ticket_search"]
      }
    },
    "private_props": {
      "url": "https://mcp.internal.zylon",
      "authorization_token": "***"
    }
  }'

Example response

{
  "id": "artifact_mcp_internal",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "type": "McpServer",
  "state": "Ready",
  "ingest_status": "NotApplicable",
  "props": {
    "name": "internal_mcp",
    "tool_configuration": {
      "enabled": true,
      "allowed_tools": ["crm_lookup", "ticket_search"]
    }
  },
  "created_at": "2026-02-08T15:22:30Z"
}

To retrieve private details for these artifacts, call: GET /api/v1/app/project/{projectId}/artifact/{artifactId}/private Only the creator of the artifact can access the private details.

Working with artifacts

List artifacts

curl "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact?page=1&page_size=20" \
  -H "Authorization: Bearer {API_TOKEN}"

Example response

{
  "data": [
    {
      "id": "artifact_doc_q1",
      "project_id": "proj_7a5c3e1b9d2f4a6c",
      "name": "Q1 Support Summary",
      "type": "Document",
      "source": "User",
      "state": "Ready",
      "ingest_status": "Done",
      "has_content": true,
      "created_at": "2026-02-08T14:30:12Z",
      "updated_at": "2026-02-08T14:31:02Z"
    }
  ],
  "has_next_page": false,
  "has_previous_page": false,
  "total_count": 1
}

Get an artifact

curl "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact/{artifactID}" \
  -H "Authorization: Bearer {API_TOKEN}"

Example response

{
  "id": "artifact_doc_q1",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "name": "Q1 Support Summary",
  "type": "Document",
  "source": "User",
  "state": "Ready",
  "ingest_status": "Done",
  "has_content": true,
  "created_at": "2026-02-08T14:30:12Z",
  "updated_at": "2026-02-08T14:31:02Z"
}

Update an artifact

curl -X PUT "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact/{artifactID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 Support Summary (final)",
    "description": "Finalized weekly summary notes.",
    "plain_text_content": "Ticket volume rose 12% week-over-week..."
  }'

Example response

{
  "id": "artifact_doc_q1",
  "name": "Q1 Support Summary (final)",
  "description": "Finalized weekly summary notes.",
  "type": "Document",
  "source": "User",
  "ingest_status": "Done",
  "updated_at": "2026-02-08T14:45:21Z"
}

Delete an artifact

curl -X DELETE "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact/{artifactID}" \
  -H "Authorization: Bearer {API_TOKEN}"

Example response

{
  "id": "artifact_doc_q1",
  "state": "Deleted"
}

Private artifact metadata

curl "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact/{artifactID}/private" \
  -H "Authorization: Bearer {API_TOKEN}"

Example response (private MCP artifact props)

{
  "connection_string": "postgresql://readonly:***@db.example.com:5432/sales"
}

Download raw artifact content

curl "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact/{artifactID}/download" \
  -H "Authorization: Bearer {API_TOKEN}"

Example response

Ticket volume rose 12% week-over-week. Billing issues drove 38% of cases.

Get parsed content

This endpoint is only available when the artifact has an initialized vector index. In practice, this usually means connector-backed documents or artifacts that have completed indexing.

Sync an artifact

This endpoint is primarily used for integration artifacts (SharePoint, Confluence, Claromentis, or FileSystem).

Errors and edge cases

Artifact error codes: the error field maps to ingest failures:

`error` value	Meaning
`InvalidExtension`	File extension is not supported.
`MismatchedType`	File type does not match the declared artifact type.
`Malformed`	File is corrupt or unreadable.
`Encrypted`	File is password‑protected.
`ParsingFailure`	Extractor failed to parse the file.
`MaxNodes`	Document is too large/complex for parsing.
`NoValidFile`	No valid file was found in the upload.
`NoValidNodes`	No parseable content was extracted.
`InternalError`	Ingest pipeline failed unexpectedly.
`Unknown`	Unclassified ingest failure.

If ingest_status is Error, fix the source file (or convert it) and re‑sync.

Warnings: ingest_warnings can include values like BigSize, UnprocessableContent, or NoContent to indicate non‑fatal issues.
401/403: token missing or insufficient permissions.
404: artifact or project not found.
409: artifact already processing.
413: content exceeds the recommended upload size (250 MB).

First Steps

Build with Zylon

Artifacts

Prerequisites

Artifacts

Document artifacts

Agent flows

Other artifacts

Working with artifacts

List artifacts

Get an artifact

Update an artifact

Delete an artifact

Private artifact metadata

Download raw artifact content

Get parsed content

Sync an artifact

Errors and edge cases

First Steps

Build with Zylon

​Prerequisites

​Artifacts

​Document artifacts

​Agent flows

​Other artifacts

​Working with artifacts

​List artifacts

​Get an artifact

​Update an artifact

​Delete an artifact

​Private artifact metadata

​Download raw artifact content

​Get parsed content

​Sync an artifact

​Errors and edge cases

Prerequisites

Artifacts

Document artifacts

Agent flows

Other artifacts

Working with artifacts

List artifacts

Get an artifact

Update an artifact

Delete an artifact

Private artifact metadata

Download raw artifact content

Get parsed content

Sync an artifact

Errors and edge cases