Filesystem Integration

Upcoming release — Zylon 1.58These 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.

In 1.58, filesystem validation requires the nested credentials body even on the legacy URL. See API migration 1.57 → 1.58 before upgrading your integration.

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.

Create a filesystem integration

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

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.

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

Example response

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

Update filesystem credentials

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

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.

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

Endpoint parameters

Type	Name	Required	Notes
Path	`integrationArtifactID`	Yes	Filesystem integration artifact identifier.

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.

Default scope in the GET response

{
  "scopes": [
    {
      "scope_type": "project",
      "scope_id": "{projectID}",
      "enabled": true,
      "ws_auto_select": false
    }
  ]
}

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.

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.

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

Example response

true

List root files

Endpoint parameters

Type	Name	Required	Notes
Path	`integrationArtifactID`	Yes	Filesystem integration artifact identifier.

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

Example response

[
  {
    "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
  }
]

Start an ingest sync

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

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.

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

Example stream

event: SyncEvent
data: {"type":"sync_started","current_artifact_count":12,"integration_item_count":48}

event: SyncEvent
data: {"type":"sync_completed"}

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.

First Steps

Build with Zylon

Coding Agents

Filesystem Integration

Prerequisites

Create a filesystem integration

Update filesystem credentials

Get the integration artifact

Validate credentials

List root files

Start an ingest sync

Errors and edge cases

​Prerequisites

​Create a filesystem integration

​Update filesystem credentials

​Get the integration artifact

​Validate credentials

​List root files

​Start an ingest sync

​Errors and edge cases

Prerequisites

Create a filesystem integration

Update filesystem credentials

Get the integration artifact

Validate credentials

List root files

Start an ingest sync

Errors and edge cases