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.
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 Artifacts 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.
curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \ -H "Authorization: Bearer {API_TOKEN}" \ -H "x-org: {org_slug}" \ -F 'type=Document' \ -F 'name=Q1 Support Summary' \ -F 'props={ "content_type":"text/plain", "file_name":"q1-support-summary.txt" };type=application/json' \ -F 'fileData=@./q1-support-summary.txt;type=text/plain'
{ "id" : "artifact_doc_q1" , "project_id" : "proj_7a5c3e1b9d2f4a6c" , "name" : "Q1 Support Summary" , "type" : "Document" , "source" : "User" , "state" : "Ready" , "ingest_status" : "Done" , "has_content" : true , "props" : { "file_name" : "q1-support-summary.txt" , "content_type" : "text/plain" , "content_length" : 79 }, "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 "x-org: {org_slug}" \ -H "Content-Type: application/json" \ -d '{ "type": "Folder", "source": "User", "name": "Q1 Support", "description": "Artifacts for Q1 support work.", "props": {} }'
{ "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 "x-org: {org_slug}" \ -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}" } }'
{ "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 "x-org: {org_slug}" \ -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."] } }'
{ "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 "x-org: {org_slug}" \ -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." } }'
{ "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 "x-org: {org_slug}" \ -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?" ] } }'
{ "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 "x-org: {org_slug}" \ -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" } ] } }'
{ "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 "x-org: {org_slug}" \ -H "Content-Type: application/json" \ -d '{ "type": "SmartDoc", "source": "User", "name": "Onboarding SmartDoc", "props": { "artifact_ids": ["{artifactID}"] } }'
{ "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.
curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \ -H "Authorization: Bearer {API_TOKEN}" \ -H "x-org: {org_slug}" \ -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" } }'
{ "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 "x-org: {org_slug}" \ -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": "***" } }'
{ "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}/privateOnly 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}" -H "x-org: {org_slug}"
{ "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}" -H "x-org: {org_slug}"
{ "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 "x-org: {org_slug}" \ -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..." }'
{ "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}" -H "x-org: {org_slug}"
{ "id" : "artifact_doc_q1" , "state" : "Deleted" }
curl "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact/{artifactID}/private" \ -H "Authorization: Bearer {API_TOKEN}" -H "x-org: {org_slug}"
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}" -H "x-org: {org_slug}"
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 valueMeaning InvalidExtensionFile extension is not supported. MismatchedTypeFile type does not match the declared artifact type. MalformedFile is corrupt or unreadable. EncryptedFile is password‑protected. ParsingFailureExtractor failed to parse the file. MaxNodesDocument is too large/complex for parsing. NoValidFileNo valid file was found in the upload. NoValidNodesNo parseable content was extracted. InternalErrorIngest pipeline failed unexpectedly. UnknownUnclassified 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). 
