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

# Filesystem Integration

> Create, validate, browse, and ingest filesystem integration artifacts.

<Warning>
  **Upcoming release — Zylon 1.58**

  These docs are published ahead of release so you can prepare your API integrations. The release image is not yet available. For installations running 1.57, use the [1.57 documentation](/en/v1.57/overview).
</Warning>

<Warning>
  In 1.58, filesystem validation requires the nested credentials body even on the legacy URL. See [API migration 1.57 → 1.58](/en/v1.58/developer-manual/build-with-zylon/workspace-api/api-migration-1-57-to-1-58#filesystem-requests) before upgrading your integration.
</Warning>

Filesystem integrations are stored as artifacts. The integration identifier used by these endpoints is the integration artifact ID.

## Prerequisites

Enable the filesystem connector first. See [Filesystem integration setup](/en/v1.58/operator-manual/knowledge-base/file-system).

## Create a filesystem integration

Send credentials only in `private_props`; artifact responses do not return them.

<Accordion title="Endpoint parameters">
  | Type | Name | Required | Notes |
  | - | - | - | - |
  | Body | `project_id` | No | Project that owns the integration artifact. Omit it for an organization integration; that requires `AppAdmin` or higher. |
  | Body | `type` | Yes | Must be `Integration`. |
  | Body | `source` | Yes | Must be `FileSystem`. |
  | Body | `name` | Yes | Display name for the integration. |
  | Body | `props` | Yes | Public provider properties; use an empty object. |
  | Body | `props.metadata` | No | Optional provider metadata. |
  | Body | `private_props.username` | Yes | Filesystem username. |
  | Body | `private_props.password` | Yes | Filesystem password. |
</Accordion>

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/artifact" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "{projectID}",
    "type": "Integration",
    "source": "FileSystem",
    "name": "Shared filesystem",
    "props": {},
    "private_props": {
      "username": "{file_system_username}",
      "password": "{file_system_password}"
    }
  }'
```

<Accordion title="Example response">
  ```json theme={null}
  {
    "id": "{integrationArtifactID}",
    "child_count": 0,
    "project_id": "{projectID}",
    "name": "Shared filesystem",
    "type": "Integration",
    "source": "FileSystem",
    "state": "Published",
    "ingest_status": "NotApplicable",
    "props": {},
    "keep_file_after_ingestion": true,
    "created_at": "2026-02-08T14:10:00Z",
    "updated_at": "2026-02-08T14:10:00Z"
  }
  ```
</Accordion>

## Update filesystem credentials

Only the integration creator or an administrator can update private properties.

<Accordion title="Endpoint parameters">
  | Type | Name | Required | Notes |
  | - | - | - | - |
  | Path | `integrationArtifactID` | Yes | Filesystem integration artifact identifier. |
  | Body | `private_props.username` | Yes | Replacement username. |
  | Body | `private_props.password` | Yes | Replacement password. |
</Accordion>

```bash theme={null}
curl -X PUT "https://{BASE_URL}/api/v1/app/artifact/{integrationArtifactID}" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "private_props": {
      "username": "{file_system_username}",
      "password": "{file_system_password}"
    }
  }'
```

The response is the updated public artifact object. It does not contain `private_props`.

## Get the integration artifact

<Accordion title="Endpoint parameters">
  | Type | Name | Required | Notes |
  | - | - | - | - |
  | Path | `integrationArtifactID` | Yes | Filesystem integration artifact identifier. |
</Accordion>

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

The response uses the public artifact shape shown above and includes the persisted default project scope.

<Accordion title="Default scope in the GET response">
  ```json theme={null}
  {
    "scopes": [
      {
        "scope_type": "project",
        "scope_id": "{projectID}",
        "enabled": true,
        "ws_auto_select": false
      }
    ]
  }
  ```
</Accordion>

## Validate credentials

Validation does not create or update an integration artifact. `project_id` may be `null` for an organization-scoped validation; that form requires an organization administrator. Project-scoped validation requires project administrator access.

<Accordion title="Endpoint parameters">
  | Type | Name | Required | Notes |
  | - | - | - | - |
  | Body | `organization_id` | Yes | Organization identifier selected by `x-org`. |
  | Body | `project_id` | No | Project identifier, or `null` for organization scope. |
  | Body | `credentials.username` | Yes | Filesystem username to validate. |
  | Body | `credentials.password` | Yes | Filesystem password to validate. |
</Accordion>

```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/artifact/integration/filesystem/validate" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "{organizationID}",
    "project_id": "{projectID}",
    "credentials": {
      "username": "{file_system_username}",
      "password": "{file_system_password}"
    }
  }'
```

<Accordion title="Example response">
  ```json theme={null}
  true
  ```
</Accordion>

## List root files

<Accordion title="Endpoint parameters">
  | Type | Name | Required | Notes |
  | - | - | - | - |
  | Path | `integrationArtifactID` | Yes | Filesystem integration artifact identifier. |
</Accordion>

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

<Accordion title="Example response">
  ```json theme={null}
  [
    {
      "id": "/shared/support/weekly-brief.pdf",
      "parentId": "/shared/support",
      "name": "weekly-brief.pdf",
      "path": "/shared/support/weekly-brief.pdf",
      "url": "smb://example.com/shared/support/weekly-brief.pdf",
      "parent": "support",
      "isFile": true,
      "isDirectory": false,
      "isHidden": false,
      "lastModified": 1770482530000
    }
  ]
  ```
</Accordion>

## Start an ingest sync

The endpoint returns a server-sent event (SSE) stream.

<Accordion title="Endpoint parameters">
  | Type | Name | Required | Notes |
  | - | - | - | - |
  | Path | `integrationArtifactID` | Yes | Filesystem integration artifact identifier. |
  | Body | `project_id` | Yes | Destination project identifier. |
  | Body | `item_paths` | Yes | File or directory paths to ingest. |
</Accordion>

```bash theme={null}
curl -N -X POST "https://{BASE_URL}/api/v1/app/artifact/{integrationArtifactID}/ingest" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "project_id": "{projectID}",
    "item_paths": ["/shared/support"]
  }'
```

<Accordion title="Example stream">
  ```text theme={null}
  event: SyncEvent
  data: {"type":"sync_started","current_artifact_count":12,"integration_item_count":48}

  event: SyncEvent
  data: {"type":"sync_completed"}
  ```
</Accordion>

## Errors and edge cases

* **400**: invalid credentials or provider fields.
* **403**: connector not enabled or missing project, organization, or private-property permission.
* **404**: integration artifact or project not found, or the artifact is not a filesystem integration.


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