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

## Prerequisites

* An API token. See [Workspace Token Management](/en/v1.57/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. |
| **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.

<Accordion title="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`. |
</Accordion>

### Document artifacts

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

<Tabs>
  <Tab title="Document">
    <Accordion title="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. |
    </Accordion>

    ```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",
        "content_length":79
      };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": "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"
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="Folder">
    <Accordion title="props body">
      | Field | Type | Required | Description |
      | - | - | - | - |
      | `metadata` | object | No | Provider-specific metadata for integration-backed folders. Use `{}` for user-created folders without metadata. |
    </Accordion>

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

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

  <Tab title="Link">
    <Accordion title="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. |
    </Accordion>

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

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

### AI Documents

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

<Tabs>
  <Tab title="Summary">
    <Accordion title="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. |
    </Accordion>

    ```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">
    <Accordion title="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`. |
    </Accordion>

    ```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">
    <Accordion title="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 `[]`. |
    </Accordion>

    ```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">
    <Accordion title="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. |
    </Accordion>

    ```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="Analysis">
    <Accordion title="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. |
    </Accordion>

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

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

  <Tab title="SmartDoc">
    <Accordion title="props body">
      SmartDoc creation accepts `props`, but the server initializes SmartDoc artifacts with an empty object. Send `{}`.
    </Accordion>

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

    <Accordion title="Example response">
      ```json theme={null}
      {
        "id": "artifact_smartdoc_q1",
        "project_id": "proj_7a5c3e1b9d2f4a6c",
        "type": "SmartDoc",
        "state": "Draft",
        "ingest_status": "NotApplicable",
        "props": {},
        "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">
    <Accordion title="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. |
    </Accordion>

    ```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": "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"
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="McpServer">
    <Accordion title="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. |
    </Accordion>

    ```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": "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"
      }
      ```
    </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

<Accordion title="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. |
</Accordion>

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

<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": "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
  }
  ```
</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": "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"
  }
  ```
</Accordion>

| 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

<Accordion title="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. |
</Accordion>

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

<Tip>
  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.
</Tip>

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

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

<Accordion title="Example response">
  ```text theme={null}
  # Q1 Support Summary

  Billing issues drove 38% of support cases.
  ```
</Accordion>

### Sync an artifact

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

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

<Accordion title="Example stream">
  ```text theme={null}
  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: {}
  ```
</Accordion>

### Bulk update artifacts

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

<Accordion title="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}`. |
</Accordion>

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

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

### Bulk delete artifacts

<Accordion title="Endpoint parameters">
  | Type | Name | Required | Notes |
  | - | - | - | - |
  | Path | `projectID` | Yes | Project identifier. |
  | Body | `artifact_ids` | Yes | Artifact identifiers to delete. |
</Accordion>

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

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

## Check linked artifacts before modifying

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

<Accordion title="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. |
</Accordion>

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

<Accordion title="Example response">
  ```json theme={null}
  {
    "has_linked_artifacts": false
  }
  ```
</Accordion>

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.