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, AI Documents, and other artifacts.

Prerequisites

An API token. See Workspace 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.
AI Documents	Summary, composition, extraction flows	Run workflows across artifacts to produce outputs.
Other artifacts	MCP servers, SQL databases	Provide external tools or data sources.

Artifact request fields

Use POST /api/v1/app/project/{projectID}/artifact to create any artifact type. The path provides the project; the body provides shared artifact metadata plus a type-specific props object.

Artifact request fields

Field	Type	Required	Description
`projectID`	path	Yes	Project identifier.
`type`	string	Yes	Artifact type. Client-facing create types include `Document`, `Folder`, `Link`, `Summary`, `Composition`, `BulkQA`, `ReadAndExtract`, `Analysis`, `SmartDoc`, `SqlDatabase`, and `McpServer`.
`name`	string	Yes	Artifact display name.
`props`	object	Yes	Type-specific configuration. The legacy alias `config` is also accepted.
`source`	string	No	Artifact source. Defaults to `User`.
`description`	string	No	Human-readable description.
`parent_id`	string	No	Parent artifact ID for tree artifacts such as documents, folders, and links. Do not use it for MCP or database artifacts.
`integration_id`	string	No	Integration ID for integration-backed artifacts.
`external_url`	string	No	External URL for link-like or connector-backed artifacts.
`raw_content`	string	No	Inline raw content for artifact types that accept text content.
`keep_file_after_ingestion`	boolean	No	Whether uploaded file data should be retained after ingestion. Defaults to `true`.
`interaction_id`	string	No	Interaction that produced this artifact, when applicable.
`private_props`	object	No	Private connector configuration for MCP and SQL database artifacts. The legacy alias `private_config` is also accepted.
`ws_auto_select`	boolean	No	Whether Workspace should auto-select an MCP or SQL database artifact as chat context. Defaults to `false`.
`fileData`	file	No	Multipart-only file binary for upload-backed artifacts such as `Document` and `Skill`.

Document artifacts

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

Document
Folder
Link

props body

Field	Type	Required	Description
`file_name`	string	Yes	Original file name.
`content_type`	string	Yes	MIME type of `fileData`.
`content_length`	integer	Yes	File size in bytes. Must match the uploaded file bytes.
`metadata`	object	No	Provider-specific metadata for integration-backed documents.

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",
    "content_length":79
  };type=application/json' \
  -F 'fileData=@./q1-support-summary.txt;type=text/plain'

Example response

{
  "id": "artifact_doc_q1",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "name": "Q1 Support Summary",
  "type": "Document",
  "source": "User",
  "state": "Published",
  "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"
}

props body

Field	Type	Required	Description
`metadata`	object	No	Provider-specific metadata for integration-backed folders. Use `{}` for user-created folders without metadata.

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.",
    "parent_id": null,
    "props": {}
  }'

Example response

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

props body

Field	Type	Required	Description
`original_artifact_id`	string	Yes	Artifact to link into this project or folder.
`source_artifact_id`	string	Response only	Canonical source artifact ID. The server sets this value.
`original_artifact_type`	string	Response only	Type of the original artifact. The server sets this value.
`original_project_id`	string \| null	Response only	Project that owns the original artifact, when available.

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.",
    "parent_id": "artifact_folder_q1",
    "props": {
      "original_artifact_id": "{artifactID}"
    }
  }'

Example response

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

AI Documents

AI Documents run a Zylon workflow across one or more artifacts to produce a structured output.

props body

Field	Type	Required	Description
`artifact_ids`	string[]	Yes	Input artifacts to summarize.
`style`	string	Yes	`Expert`, `Neutral`, or `Simple`. Deprecated values may still decode but should not be used.
`detail`	string	Yes	`KeyPoints`, `ShortPieces`, or `LongPieces`. Deprecated values may still decode but should not be used.
`instructions`	string[] \| null	No	Extra instructions for the summary generation.

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

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

props body

Field	Type	Required	Description
`artifact_ids`	string[]	Yes	Input artifacts to use for the draft.
`instructions`	string	Yes	Composition prompt or drafting instructions.
`style`	string	Yes	`Expert`, `Neutral`, or `Simple`.
`detail`	string	Yes	`KeyPoints`, `ShortPieces`, or `LongPieces`.

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

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

props body

Field	Type	Required	Description
`questions`	string[]	Yes	Questions to answer.
`artifact_ids`	string[]	Yes	Input artifacts to answer from.
`instructions`	string[]	Yes	Constraints or guidance for the answers.
`detail`	string	Yes	`Concise`, `Moderate`, or `Comprehensive`.
`style`	string	Yes	`Expert`, `Neutral`, or `Simple`.
`results`	object[]	No	Server-populated answer results. Defaults to `[]`.

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

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

props body

Field	Type	Required	Description
`artifact_ids`	string[]	Yes	Input artifacts to read.
`sections`	object[]	Yes	Extraction targets.
`sections[].id`	string	Yes	Stable section ID.
`sections[].title`	string	Yes	Section title.
`sections[].description`	string	Yes	What to extract for that section.
`results`	object[]	Response only	Extracted section results.
`organization_context`	string \| null	Response only	Organization context used by the server.

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

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

props body

Field	Type	Required	Description
`artifact_ids`	string[]	Yes	Input artifacts to analyze.
`instruction`	object \| null	No	Custom analysis instruction. If omitted, the server uses its default analysis prompt.
`instruction.id`	string	Yes when `instruction` is set	Stable instruction ID.
`instruction.prompt`	string	Yes when `instruction` is set	Prompt used for analysis.
`instruction.metadata`	object	No	Extra instruction metadata. Defaults to `{}`.
`result`	object \| null	Response only	Combined analysis output.
`organization_context`	string \| null	Response only	Organization context used by the server.

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": "Analysis",
    "source": "User",
    "name": "Support trend analysis",
    "props": {
      "artifact_ids": ["{artifactID}"],
      "instruction": {
        "id": "support_trends",
        "prompt": "Find the top support trends and risks.",
        "metadata": { "audience": "leadership" }
      }
    }
  }'

Example response

{
  "id": "artifact_analysis_q1",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "type": "Analysis",
  "state": "Processing",
  "ingest_status": "NotApplicable",
  "props": {
    "artifact_ids": ["artifact_doc_q1"],
    "instruction": {
      "id": "support_trends",
      "prompt": "Find the top support trends and risks.",
      "metadata": { "audience": "leadership" }
    },
    "result": null
  },
  "created_at": "2026-02-08T15:16:30Z"
}

props body

SmartDoc creation accepts props, but the server initializes SmartDoc artifacts with an empty object. Send {}.

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

Example response

{
  "id": "artifact_smartdoc_q1",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "type": "SmartDoc",
  "state": "Draft",
  "ingest_status": "NotApplicable",
  "props": {},
  "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

props body

Field	Type	Required	Description
`schemas`	string[] \| null	No	Database schemas to expose.
`tables`	string[] \| null	No	Database tables to expose.
`ssl`	boolean \| null	No	Whether the database connection uses SSL.
`enable_tables`	boolean \| null	No	Enable table discovery/use.
`enable_views`	boolean \| null	No	Enable view discovery/use.
`enable_procedures`	boolean \| null	No	Enable stored procedure discovery/use.
`enable_functions`	boolean \| null	No	Enable function discovery/use.
`private_props.connection_string`	string	Yes	Database connection string. Mask secrets in examples and logs.

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

Example response

{
  "id": "artifact_db_sales",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "type": "SqlDatabase",
  "state": "Published",
  "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"
}

props body

Field	Type	Required	Description
`name`	string	Yes	MCP server name visible to tools.
`tool_configuration`	object \| null	No	Tool allowlist configuration.
`tool_configuration.enabled`	boolean	No	Whether tools are enabled. Defaults to `true`.
`tool_configuration.allowed_tools`	string[] \| null	No	Tool names clients may call through this MCP server.
`private_props.url`	string	Yes	MCP server URL.
`private_props.use_bearer_auth`	boolean	No	Whether to authenticate with bearer auth. Defaults to `false`.
`private_props.authorization_token`	string \| null	No	Authorization token when the server expects a custom authorization token. Mask the value.
`private_props.bearer_token`	string \| null	No	Bearer token when bearer auth is enabled. Mask the value.

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

Example response

{
  "id": "artifact_mcp_internal",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "type": "McpServer",
  "state": "Published",
  "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

Endpoint parameters

Query parameter	Type	Required	Description
`state`	string	No	Comma-separated artifact states. Defaults to `Published,Processing`.
`source`	string	No	Comma-separated sources such as `User`, `SharePoint`, `Confluence`, `Claromentis`, or `FileSystem`.
`ingest_status`	string	No	Comma-separated ingest statuses. Defaults to all statuses.
`type`	string	No	Comma-separated artifact types.
`parent_id`	string	No	Scope results to direct children of a parent artifact.
`include_descendants`	boolean	No	Include the full subtree under `parent_id`; if no parent is set, include all descendants in the project.
`filter_by_text`	string	No	Text search over artifact names and content metadata.
`keep_ancestors`	boolean	No	Include ancestor artifacts for text matches.
`resolve_links`	boolean	No	Include descendants of link artifacts.
`sub_type`	string	No	Comma-separated subtype filter.
`include`	string	No	Use `User` to include creator details.
`page`, `page_size`, `after`, `before`	mixed	No	Pagination controls.

curl "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact?page=1&page_size=20&parent_id={artifactID}&include_descendants=false" \
  -H "Authorization: Bearer {API_TOKEN}"
  -H "x-org: {org_slug}"

Example response

{
  "data": [
    {
      "id": "artifact_doc_q1",
      "project_id": "proj_7a5c3e1b9d2f4a6c",
      "name": "Q1 Support Summary",
      "type": "Document",
      "source": "User",
      "state": "Published",
      "ingest_status": "Done",
      "has_content": true,
      "parent_id": "artifact_folder_q1",
      "child_count": 0,
      "keep_file_after_ingestion": true,
      "ws_auto_select": false,
      "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}"

Example response

{
  "id": "artifact_doc_q1",
  "project_id": "proj_7a5c3e1b9d2f4a6c",
  "name": "Q1 Support Summary",
  "type": "Document",
  "source": "User",
  "state": "Published",
  "ingest_status": "Done",
  "has_content": true,
  "parent_id": "artifact_folder_q1",
  "child_count": 0,
  "keep_file_after_ingestion": true,
  "ws_auto_select": false,
  "created_at": "2026-02-08T14:30:12Z",
  "updated_at": "2026-02-08T14:31:02Z"
}

Response field	Type	Description
`id`	string	Artifact ID.
`parent_id`	string \| null	Parent artifact ID, when the artifact is nested.
`child_count`	integer	Number of direct children.
`project_id`	string	Project ID.
`name`	string	Artifact name.
`description`	string \| null	Artifact description.
`type`	string	Artifact type.
`source`	string	Artifact source.
`state`	string	Current artifact state.
`error`	string \| null	Ingest or processing error code.
`ingest_status`	string	Ingest lifecycle status.
`ingest_warnings`	string[] \| null	Non-fatal ingest warnings.
`ingest_progress`	number \| null	Ingest progress when available.
`has_content`	boolean	Whether content is stored for the artifact.
`raw_content`	string \| null	Raw content when explicitly included.
`integration_id`	string \| null	Integration ID for integration-backed artifacts.
`external_url`	string \| null	External URL when present.
`props`	object	Type-specific public configuration.
`file_uri`	string \| null	Temporary public file URL when available.
`artifact_references`	object[] \| null	References when `include_references=true`.
`artifact_relationships`	object[] \| null	Relationships when `include_relationships=true`.
`keep_file_after_ingestion`	boolean	Whether uploaded file data is retained.
`created_by`	object \| null	Creator details when `include=User`.
`created_at`	timestamp	Creation timestamp.
`updated_at`	timestamp	Last update timestamp.
`ws_auto_select`	boolean	Whether Workspace auto-selects the artifact as context. Only meaningful for MCP and SQL database artifacts.

Update an artifact

Endpoint parameters

Field	Type	Required	Description
`projectID`	path	Yes	Project identifier.
`artifactID`	path	Yes	Artifact identifier.
`name`	string	No	New artifact name.
`parent_id`	string	No	Move a content/tree artifact under this parent artifact. Do not use it for MCP or database artifacts.
`reset_parent_id`	boolean	No	Set to `true` to move a content/tree artifact back to the project root. Defaults to `false`.
`external_url`	string	No	Replace the external URL.
`props`	object	No	Replace or update type-specific public configuration. The legacy alias `config` is also accepted.
`description`	string	No	Replace the description.
`content`	string	No	Base64-encoded binary content.
`plain_text_content`	string	No	Plain text content to store for the artifact.
`private_props`	object	No	Private connector configuration for MCP and SQL database artifacts. The legacy alias `private_config` is also accepted.
`ws_auto_select`	boolean	No	Whether Workspace should auto-select an MCP or SQL database artifact as chat context. Do not use it for document or agent-flow artifacts.

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.",
    "parent_id": "artifact_folder_q1",
    "reset_parent_id": false,
    "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.",
  "parent_id": "artifact_folder_q1",
  "type": "Document",
  "source": "User",
  "ingest_status": "Done",
  "updated_at": "2026-02-08T14:45:21Z"
}

Use parent_id to move an artifact into a folder. Use reset_parent_id: true to remove the current parent and move it back to the project root.

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

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}"
  -H "x-org: {org_slug}"

Example response (private SQL database 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}"

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.

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

Example response

# Q1 Support Summary

Billing issues drove 38% of support cases.

Sync an artifact

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

curl -N -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact/{artifactID}/sync" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Accept: text/event-stream"

The request body is empty. The response is an SSE stream emitted by the integration sync process.

Example stream

event: sync_started
data: {"current_artifact_count":12,"integration_item_count":40}

event: sync_progress
data: {"artifact_id":"artifact_doc_q1","op":"Updated","progress":0.42}

event: sync_completed
data: {}

Bulk update artifacts

Use the bulk update endpoint to apply the same update body shape used by PUT /artifact/{artifactID} to multiple artifacts.

Endpoint parameters

Type	Name	Required	Notes
Path	`projectID`	Yes	Project identifier.
Body	`artifacts`	Yes	Array of artifact updates.
Body	`artifacts[].artifactId`	Yes	Artifact identifier to update.
Body	`artifacts[].update`	Yes	Update body using the same fields as `PUT /artifact/{artifactID}`.

curl -X PUT "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact/bulk" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "artifacts": [
      {
        "artifactId": "artifact_doc_q1",
        "update": {
          "parent_id": "artifact_folder_q1",
          "reset_parent_id": false,
          "description": "Moved into Q1 folder."
        }
      }
    ]
  }'

Example response

[
  {
    "id": "artifact_doc_q1",
    "parent_id": "artifact_folder_q1",
    "description": "Moved into Q1 folder.",
    "type": "Document",
    "state": "Published",
    "ingest_status": "Done",
    "updated_at": "2026-02-08T15:20:00Z"
  }
]

Bulk delete artifacts

Endpoint parameters

Type	Name	Required	Notes
Path	`projectID`	Yes	Project identifier.
Body	`artifact_ids`	Yes	Artifact identifiers to delete.

curl -X DELETE "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact/bulk" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "artifact_ids": ["artifact_doc_q1", "artifact_link_q1"]
  }'

Example response

[
  {
    "id": "artifact_doc_q1",
    "state": "Deleted"
  },
  {
    "id": "artifact_link_q1",
    "state": "Deleted"
  }
]

Check linked artifacts before modifying

Use this endpoint before changing an artifact when you need to check whether linked artifacts depend on it.

Endpoint parameters

Type	Name	Required	Notes
Query	`created_by`	No	User ID that created the artifacts to check.
Query	`project_id`	No	Project ID to check for linked artifacts.
Query	`artifact_id`	No	Artifact ID to check for linked artifacts.

curl "https://{BASE_URL}/api/v1/app/resource/is-safe-to-modify?project_id={projectID}&artifact_id={artifactID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"

Example response

{
  "has_linked_artifacts": false
}

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

​Prerequisites

​Artifacts

​Artifact request fields

​Document artifacts

​AI Documents

​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

​Bulk update artifacts

​Bulk delete artifacts

​Check linked artifacts before modifying

​Errors and edge cases

Prerequisites

Artifacts

Artifact request fields

Document artifacts

AI Documents

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

Bulk update artifacts

Bulk delete artifacts

Check linked artifacts before modifying

Errors and edge cases