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

# Artifacts

> Workspace artifacts for documents, agent flows, and connectors.

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 [Workspace Token Management](/en/developer-manual/get-started/token-management).
* Your Zylon hostname (replace `{BASE_URL}` in the examples).

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

<Tabs>
  <Tab title="Document">
    ```bash theme={null}
    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'
    ```

    <Accordion title="Example response">
      ```json theme={null}
      {
        "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"
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="Folder">
    ```bash theme={null}
    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": {}
      }'
    ```

    <Accordion title="Example response">
      ```json theme={null}
      {
        "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"
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="Link">
    ```bash theme={null}
    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}"
        }
      }'
    ```

    <Accordion title="Example response">
      ```json theme={null}
      {
        "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"
      }
      ```
    </Accordion>
  </Tab>
</Tabs>

### Agent flows

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

<Tabs>
  <Tab title="Summary">
    ```bash theme={null}
    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."]
        }
      }'
    ```

    <Accordion title="Example response">
      ```json theme={null}
      {
        "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"
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="Composition">
    ```bash theme={null}
    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."
        }
      }'
    ```

    <Accordion title="Example response">
      ```json theme={null}
      {
        "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"
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="BulkQA">
    ```bash theme={null}
    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?"
          ]
        }
      }'
    ```

    <Accordion title="Example response">
      ```json theme={null}
      {
        "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"
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="ReadAndExtract">
    ```bash theme={null}
    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" }
          ]
        }
      }'
    ```

    <Accordion title="Example response">
      ```json theme={null}
      {
        "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"
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="SmartDoc">
    ```bash theme={null}
    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}"]
        }
      }'
    ```

    <Accordion title="Example response">
      ```json theme={null}
      {
        "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"
      }
      ```
    </Accordion>
  </Tab>
</Tabs>

### Other artifacts

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

<Tabs>
  <Tab title="SqlDatabase">
    ```bash theme={null}
    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"
        }
      }'
    ```

    <Accordion title="Example response">
      ```json theme={null}
      {
        "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"
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="McpServer">
    ```bash theme={null}
    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": "***"
        }
      }'
    ```

    <Accordion title="Example response">
      ```json theme={null}
      {
        "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"
      }
      ```
    </Accordion>
  </Tab>
</Tabs>

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

```bash theme={null}
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}"
```

<Accordion title="Example response">
  ```json theme={null}
  {
    "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
  }
  ```
</Accordion>

### Get an artifact

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact/{artifactID}" \
  -H "Authorization: Bearer {API_TOKEN}"
  -H "x-org: {org_slug}"
```

<Accordion title="Example response">
  ```json theme={null}
  {
    "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"
  }
  ```
</Accordion>

### Update an artifact

```bash theme={null}
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..."
  }'
```

<Accordion title="Example response">
  ```json theme={null}
  {
    "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"
  }
  ```
</Accordion>

### Delete an artifact

```bash theme={null}
curl -X DELETE "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact/{artifactID}" \
  -H "Authorization: Bearer {API_TOKEN}"
  -H "x-org: {org_slug}"
```

<Accordion title="Example response">
  ```json theme={null}
  {
    "id": "artifact_doc_q1",
    "state": "Deleted"
  }
  ```
</Accordion>

### Private artifact metadata

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact/{artifactID}/private" \
  -H "Authorization: Bearer {API_TOKEN}"
  -H "x-org: {org_slug}"
```

<Accordion title="Example response (private MCP artifact props)">
  ```json theme={null}
  {
    "connection_string": "postgresql://readonly:***@db.example.com:5432/sales"
  }
  ```
</Accordion>

### Download raw artifact content

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact/{artifactID}/download" \
  -H "Authorization: Bearer {API_TOKEN}"
  -H "x-org: {org_slug}"
```

<Accordion title="Example response">
  ```text theme={null}
  Ticket volume rose 12% week-over-week. Billing issues drove 38% of cases.
  ```
</Accordion>

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