> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/sftp.md).

# SFTP

Exchange files with an SFTP server: read and write a vendor drop folder, and start a workflow when a file lands in it. Plain FTP is not supported, because it sends credentials and file contents unencrypted.

## Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

| Connector       | Authentication                   |
| --------------- | -------------------------------- |
| SFTP (Password) | Username and password            |
| SFTP (Key)      | SSH private key (PEM or OpenSSH) |

### SFTP (Password)

Read and write files on an SFTP server with a username and password. Plain FTP is not supported: it sends credentials and file contents unencrypted. Use SFTP (Key) for key-based authentication.

#### Set up in SFTP

1. Ask the SFTP server administrator for the hostname, port, username, password, and host-key fingerprint.
2. Give the server account permission to the directories and file operations that the workflow needs.

#### Set up in StackAI

1. Open **Settings → Connections**, add a connection, and select **SFTP (Password)**.
2. Enter the credentials and connection details in the fields below.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field        | Required                 | What to enter                                                                                                                                                                                                                |
| -------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Host                 | Yes                      | Hostname or IP address of the SFTP server.                                                                                                                                                                                   |
| Port                 | Optional / as applicable | Port the SFTP server listens on. 22 unless the server's owner says otherwise.                                                                                                                                                |
| Username             | Yes                      | The account the server issued for this drop folder.                                                                                                                                                                          |
| Password             | Yes                      | Password for the SFTP account.                                                                                                                                                                                               |
| Host Key Fingerprint | Optional / as applicable | Optional. Pin the server's host key so a changed key aborts the connection. Leave it empty to accept whatever key the server presents; the fingerprint is then reported by the connection test, ready to paste back in here. |

**Connection notes**

* Use the SFTP (Key) connector if the server requires an SSH private key. This password connector does not accept a private key.

### SFTP (Key)

Read and write files on an SFTP server with an SSH private key. Plain FTP is not supported: it sends credentials and file contents unencrypted. Use SFTP (Password) for password authentication.

#### Set up in SFTP

1. Ask the server administrator for the SFTP hostname, port, username, folder permissions, and host-key fingerprint.
2. Generate an SSH key pair or use a key pair approved by the server administrator. Install the public key for that server account. Keep the private key for StackAI.
3. If the private key is encrypted, obtain its passphrase. The connector accepts OpenSSH and PEM private-key formats.

#### Set up in StackAI

1. Open **Settings → Connections**, add a connection, and select **SFTP (Key)**.
2. Enter the credentials and connection details in the fields below.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field        | Required                 | What to enter                                                                                                                                                                                                                |
| -------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Host                 | Yes                      | Hostname or IP address of the SFTP server.                                                                                                                                                                                   |
| Port                 | Optional / as applicable | Port the SFTP server listens on. 22 unless the server's owner says otherwise.                                                                                                                                                |
| Username             | Yes                      | The account the server issued for this drop folder.                                                                                                                                                                          |
| Private Key          | Yes                      | The private key file for this account, pasted whole, including its BEGIN and END lines. OpenSSH and PEM formats are both accepted.                                                                                           |
| Key Passphrase       | Optional / as applicable | Only needed when the private key itself is encrypted.                                                                                                                                                                        |
| Host Key Fingerprint | Optional / as applicable | Optional. Pin the server's host key so a changed key aborts the connection. Leave it empty to accept whatever key the server presents; the fingerprint is then reported by the connection test, ready to paste back in here. |

**Connection notes**

* Paste the entire private key, including the BEGIN and END lines. Set Key Passphrase only for an encrypted private key.
* Confirm the host-key fingerprint with the server administrator before saving it. An unexpected host-key change can indicate that you reached a different server.
* This connector uses SFTP over SSH. It does not support plain FTP.

### Verify the connection

Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

## Use an action

1. Add the required **SFTP** action to the workflow.
2. Select a connection when the action requests one.
3. Complete the required fields. Use the reference picker when a value comes from another workflow step.
4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

## Actions

### Upload File

Upload a file to a folder on the SFTP server, from text or from a URL.

#### Inputs

| Field          | Type            | Required | Description                                                                                                                            |
| -------------- | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Remote Folder  | file\_picker    | No       | Folder to upload into. Pick one from the browser or type a path such as outgoing. Leave it empty for the folder the account starts in. |
| Content Source | select (string) | Yes      | Where the file's contents come from. Available values: Text, URL. Default: text.                                                       |
| File Content   | textarea        | No       | Text to write. It is written as-is in UTF-8, so give the file an extension that matches what you are writing, such as .csv or .txt.    |
| File URL       | string          | No       | URL to fetch the file from, such as the Download URL of an earlier node.                                                               |
| File Name      | string          | Yes      | Name to save the file under, including its extension.                                                                                  |
| Overwrite      | boolean         | No       | Replace the file if one with this name already exists. Default: false.                                                                 |

#### Outputs

| Field       | Type    | Description                                                  |
| ----------- | ------- | ------------------------------------------------------------ |
| Path        | string  | Path of the uploaded file, usable by the other SFTP actions. |
| File Name   | string  | Name the file was saved under.                               |
| Size        | integer | Size of the uploaded file in bytes.                          |
| Uploaded At | string  | Modification time the server recorded, ISO 8601 UTC.         |

### Download File

Download a file from the SFTP server and return a signed URL for it. To read what is inside, send the URL to Parse Files.

#### Inputs

| Field | Type         | Required | Description                                                                                                                 |
| ----- | ------------ | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| File  | file\_picker | Yes      | File to download. Pick one from the browser, or type a path such as incoming/orders.csv, or feed in a Path from List Files. |

#### Outputs

| Field        | Type    | Description                                                                                                         |
| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------- |
| Download URL | string  | Signed URL for the downloaded file, valid for 24 hours. Feed it to any node that takes a file, such as Parse Files. |
| File Name    | string  | Name of the downloaded file.                                                                                        |
| Size         | integer | Size of the file in bytes.                                                                                          |
| Modified At  | string  | Last modification time on the server, ISO 8601 UTC.                                                                 |

### List Files

List the files and folders directly inside a folder on the SFTP server. Subfolders are listed but not opened.

#### Inputs

| Field       | Type         | Required | Description                                                                                                                          |
| ----------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Folder      | file\_picker | No       | Folder to list. Pick one from the browser or type a path such as incoming/2026. Leave it empty for the folder the account starts in. |
| Name Filter | string       | No       | Only return entries whose name matches this pattern. Supports \* and ?, for example \*.csv. Matching is case-sensitive.              |

#### Outputs

| Field       | Type          | Description                                                                                                                                                    |
| ----------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Files       | object\_array | Entries in the folder. Each Path can be used directly in Download File, Move File or Delete File. At most 1000 are returned.                                   |
| Total Count | integer       | Number of entries returned.                                                                                                                                    |
| Truncated   | boolean       | True when the folder holds more than 1000 matching entries and only the first were returned. Narrow the Name Filter, or point at a subfolder, to see the rest. |

### Move File

Move a file to another folder on the SFTP server, rename it, or both. Moving processed files out of a watched folder is what stops a daily flow from picking up yesterday's file again.

#### Inputs

| Field              | Type         | Required | Description                                                                              |
| ------------------ | ------------ | -------- | ---------------------------------------------------------------------------------------- |
| Source             | file\_picker | Yes      | File to move. Pick one from the browser, type a path, or feed in a Path from List Files. |
| Destination Folder | file\_picker | No       | Folder to move the file into. Leave it empty to rename the file where it is.             |
| New Name           | string       | No       | Name to give the file. Leave it empty to keep the current one.                           |

#### Outputs

| Field     | Type   | Description            |
| --------- | ------ | ---------------------- |
| Path      | string | Path the file now has. |
| File Name | string | Name the file now has. |

### Delete File

Delete a file from the SFTP server. Folders are left alone.

#### Inputs

| Field | Type         | Required | Description                                                                                |
| ----- | ------------ | -------- | ------------------------------------------------------------------------------------------ |
| File  | file\_picker | Yes      | File to delete. Pick one from the browser, type a path, or feed in a Path from List Files. |

#### Outputs

| Field   | Type    | Description                        |
| ------- | ------- | ---------------------------------- |
| Path    | string  | Path of the file that was deleted. |
| Deleted | boolean | Whether the file was deleted.      |

### Create Folder

Create a folder on the SFTP server. Any missing parent folder is created too, and an existing folder is left as it is.

#### Inputs

| Field         | Type         | Required | Description                                                                                  |
| ------------- | ------------ | -------- | -------------------------------------------------------------------------------------------- |
| Parent Folder | file\_picker | No       | Folder to create the new folder inside. Leave it empty for the folder the account starts in. |
| Folder Name   | string       | Yes      | Name for the new folder.                                                                     |

#### Outputs

| Field | Type   | Description                                           |
| ----- | ------ | ----------------------------------------------------- |
| Path  | string | Path of the folder, usable by the other SFTP actions. |

## Triggers

A trigger starts a workflow when its configured event occurs. Configure the event and filters before enabling the trigger.

### On File Received

Run a workflow when a new file arrives in a folder on the SFTP server. SFTP has no events, so the folder is polled every minute; a file is picked up once its upload has finished, not while it is still being written.

#### Configuration

| Field       | Type         | Required | Description                                                                                                                                                                                                                                                    |
| ----------- | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Folder      | file\_picker | No       | Folder to watch. Pick one from the browser or type a path such as incoming. Leave it empty for the folder the account starts in. Subfolders are not watched.                                                                                                   |
| Name Filter | string       | No       | Only fire for files whose name matches this pattern. Supports \* and ?, for example \*.csv. Matching is case-sensitive. A drop folder usually holds more than the file you want: logs, control files, and the partial names other tools write while uploading. |

#### Event inputs

| Field       | Type    | Required | Description                                           |
| ----------- | ------- | -------- | ----------------------------------------------------- |
| Path        | string  | Yes      | Path of the new file, ready for a Download File node. |
| File Name   | string  | Yes      | Name of the new file.                                 |
| Size        | integer | Yes      | Size of the file in bytes.                            |
| Modified At | string  | No       | Last modification time on the server, ISO 8601 UTC.   |

#### Outputs

| Field       | Type    | Description                                                            |
| ----------- | ------- | ---------------------------------------------------------------------- |
| Path        | string  | Path of the new file. Put a Download File node behind this to read it. |
| File Name   | string  | Name of the new file.                                                  |
| Size        | integer | Size of the file in bytes.                                             |
| Modified At | string  | Last modification time on the server, ISO 8601 UTC.                    |

## Important behavior

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/sftp.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
