FIfiles
remote_servers
Remote Servers

List Remote Servers

Changed on

List Remote Servers

get/remote_servers

Request

  • Base URL
    https://app.files.com/api/rest/v1
  • URL
    https://app.files.com/api/rest/v1/remote_servers
  • Auth
    none declared

Query parameters

user_idinteger

User ID. Provide a value of 0 to operate the current session's user.

cursorstring

Used for pagination. When a list request has more records available, cursors are provided in the response headers X-Files-Cursor-Next and X-Files-Cursor-Prev. Send one of those cursor value here to resume an existing list from the next available record. Note: many of our SDKs have iterator methods that will automatically handle cursor-based pagination.

per_pageinteger

Number of records to show per page. (Max: 10000, 1,000 or less is recommended).

If set, sort records by the specified field in either asc or desc direction. Valid fields are workspace_id, name, server_type, backblaze_b2_bucket, google_cloud_storage_bucket, wasabi_bucket, s3_bucket, azure_blob_storage_container, azure_files_storage_share_name, s3_compatible_bucket, filebase_bucket, cloudflare_bucket or linode_bucket.

If set, return records where the specified field is equal to the supplied value. Valid fields are name, server_type, workspace_id, backblaze_b2_bucket, google_cloud_storage_bucket, wasabi_bucket, s3_bucket, azure_blob_storage_container, azure_files_storage_share_name, s3_compatible_bucket, filebase_bucket, cloudflare_bucket or linode_bucket. Valid field combinations are [ server_type, name ], [ workspace_id, name ], [ backblaze_b2_bucket, name ], [ google_cloud_storage_bucket, name ], [ wasabi_bucket, name ], [ s3_bucket, name ], [ azure_blob_storage_container, name ], [ azure_files_storage_share_name, name ], [ s3_compatible_bucket, name ], [ filebase_bucket, name ], [ cloudflare_bucket, name ], [ linode_bucket, name ], [ workspace_id, server_type ] or [ workspace_id, server_type, name ].

If set, return records where the specified field is prefixed by the supplied value. Valid fields are name, backblaze_b2_bucket, google_cloud_storage_bucket, wasabi_bucket, s3_bucket, azure_blob_storage_container, azure_files_storage_share_name, s3_compatible_bucket, filebase_bucket, cloudflare_bucket or linode_bucket. Valid field combinations are [ backblaze_b2_bucket, name ], [ google_cloud_storage_bucket, name ], [ wasabi_bucket, name ], [ s3_bucket, name ], [ azure_blob_storage_container, name ], [ azure_files_storage_share_name, name ], [ s3_compatible_bucket, name ], [ filebase_bucket, name ], [ cloudflare_bucket, name ] or [ linode_bucket, name ].

Response

A list of RemoteServers objects.

idinteger

Remote Server ID

disabledboolean

If true, this Remote Server is disabled. Updating it clears this flag, except for retired Agent v1 records, which remain disabled.

authentication_methodstring

Type of authentication method to use

hostnamestring

Hostname or IP address. For Agent Remote Servers, the Agent reports the hostname it connects from at each registration, replacing the stored value. This field is not included in the generated Agent configuration file. Setting it on Create or Update does not change the running Agent.

remote_home_pathstring

Initial home folder on remote server

upload_staging_pathstring

Upload staging path. Applies to SFTP only. If a path is provided here, files will first be uploaded to this path on the remote folder and the moved into the final correct path via an SFTP move command. This is required by some remote MFT systems to emulate atomic uploads, which are otherwise not supoprted by SFTP.

allow_relative_pathsboolean

Allow relative paths in SFTP. If true, paths will not be forced to be absolute, allowing operations relative to the user's home directory.

namestring

Internal name for your reference

descriptionstring

Internal description for your reference

portinteger

Port for remote server. For Agent Remote Servers, the Agent reports its downstream proxy port at each registration, replacing the stored value. This field is not included in the generated Agent configuration file. Setting it on Create or Update does not change the running Agent.

buffer_uploads'auto' | 'always' | 'never'

If set to always, uploads to this server will be uploaded first to Files.com before being sent to the remote server. This can improve performance in certain access patterns, such as high-latency connections. It will cause data to be temporarily stored in Files.com. If set to auto, we will perform this optimization if we believe it to be a benefit in a given situation.

max_connectionsinteger

Max number of parallel connections. Ignored for S3 connections (we will parallelize these as much as possible).

pin_to_site_regionboolean

If true, we will ensure that all communications with this remote server are made through the primary region of the site. This setting can also be overridden by a site-wide setting which will force it to true.

pinned_regionstring

If set, all communications with this remote server are made through the provided region.

remote_server_credential_idinteger

ID of Remote Server Credential, if applicable.

s3_bucketstring

S3 bucket name

s3_regionstring

S3 region

s3_kms_key_idstring

ARN of the AWS KMS key that encrypts files written to the bucket (SSE-KMS). Leave blank unless your bucket requires a specific key.

aws_access_keystring

AWS Access Key.

s3_assume_role_arnstring

AWS IAM Role ARN for AssumeRole authentication.

s3_assume_role_duration_secondsinteger

Session duration in seconds for AssumeRole authentication (900-43200).

s3_assume_role_external_idstring

External ID for AssumeRole authentication.

server_certificate'require_match' | 'allow_any'

Remote server certificate

server_host_keystring

Pinned SSH host key or OpenSSH host certificate for SFTP. If omitted, Files.com detects and stores a host key, preferring plain keys over certificates. With server_certificate=require_match (the default), the server must present the exact pinned key or certificate and prove it holds the matching private key. A pinned certificate is compared in full, so renewal can require updating server_host_key even when its underlying key is unchanged. Files.com does not check certificate CA signatures, principals, or validity periods. Certificate expiration alone does not end the pin. Update server_host_key to replace the pin.

server_type'ftp' | 'sftp' | 's3' | 'google_cloud_storage' | 'webdav' | 'wasabi' | 'backblaze_b2' | 'one_drive' | 'box' | 'dropbox' | 'google_drive' | 'azure' | 'sharepoint' | 's3_compatible' | 'azure_files' | 'files_agent' | 'filebase' | 'cloudflare' | 'linode' | 'files_com'

Remote server type.

site_admin_accessboolean

Owner's preference for administrator access to this user-owned Remote Server. Null uses the Site policy's default. Only the owner may change it when the Site policy allows user choice.

effective_site_admin_accessboolean

Whether Site and Workspace Administrators can access this Remote Server under the current Site policy.

user_idinteger

ID of the Integration-Centric user who owns this personal Remote Server, if any. Connections created by Site and Workspace Administrators have no owner.

workspace_idinteger

Workspace ID (0 for default workspace)

ssl'if_available' | 'require' | 'require_implicit' | 'never'

Should we require SSL?

usernamestring

Remote server username.

google_cloud_storage_bucketstring

Google Cloud Storage: Bucket Name

google_cloud_storage_authentication_method'json' | 'hmac' | 'oauth'

Google Cloud Storage: Authentication method. Can be json, hmac, or oauth.

google_cloud_storage_oauth_scopestring

Google Cloud Storage: OAuth scope. Can be https://www.googleapis.com/auth/devstorage.read_only or https://www.googleapis.com/auth/devstorage.read_write.

google_cloud_storage_project_idstring

Google Cloud Storage: Project ID

google_cloud_storage_s3_compatible_access_keystring

Google Cloud Storage: S3-compatible Access Key.

backblaze_b2_s3_endpointstring

Backblaze B2 Cloud Storage: S3 Endpoint

backblaze_b2_bucketstring

Backblaze B2 Cloud Storage: Bucket name

wasabi_bucketstring

Wasabi: Bucket name

wasabi_regionstring

Wasabi: Region

wasabi_access_keystring

Wasabi: Access Key.

auth_status'not_applicable' | 'in_setup' | 'complete' | 'reauthenticate'

Either in_setup or complete

auth_account_namestring

Describes the authorized account

one_drive_account_type'personal' | 'business_other'

OneDrive: Either personal or business_other account types

sharepoint_tenant_idstring

SharePoint: Microsoft Entra tenant ID for app-only authentication.

sharepoint_client_idstring

SharePoint: Microsoft Entra application client ID for app-only authentication.

sharepoint_app_authenticationboolean

SharePoint: If true, this remote server uses Microsoft Entra app-only authentication.

sharepoint_app_credential_typestring

SharePoint: App-only credential type. Either secret or certificate.

sharepoint_site_urlstring

SharePoint: Site URL to scope app-only authentication to a single site. Leave blank to browse all sites.

azure_blob_storage_accountstring

Azure Blob Storage: Account name

azure_blob_storage_containerstring

Azure Blob Storage: Container name

azure_blob_storage_hierarchical_namespaceboolean

Azure Blob Storage: Does the storage account has hierarchical namespace feature enabled?

azure_blob_storage_dns_suffixstring

Azure Blob Storage: Custom DNS suffix

azure_files_storage_accountstring

Azure Files: Storage Account name

azure_files_storage_share_namestring

Azure Files: Storage Share name

azure_files_storage_dns_suffixstring

Azure Files: Custom DNS suffix

s3_compatible_bucketstring

S3-compatible: Bucket name

s3_compatible_endpointstring

S3-compatible: endpoint

s3_compatible_regionstring

S3-compatible: region

s3_compatible_virtual_hosted_styleboolean

S3-compatible: If true, use virtual-hosted-style URLs instead of path-style URLs

s3_compatible_access_keystring

S3-compatible: Access Key

enable_dedicated_ipsboolean

true if remote server only accepts connections from dedicated IPs

custom_domain_idinteger

Custom Domain ID whose dedicated IP addresses are selected when this Remote Server uses dedicated IPs. Must be available to this Remote Server's workspace. Requires enable_dedicated_ips and cannot be combined with an outbound Agent. Set to null to use the site's default dedicated IPs.

outbound_ip_addressesstring[]

Current eligible public IP addresses for the selected Custom Domain. Any address in this list may originate a connection. Empty when no domain is selected or its configuration is unavailable. Only included in responses for a single Remote Server.

files_agent_permission_set'read_write' | 'read_only' | 'write_only'

Agent file permissions: read_only, write_only, or read_write. Files.com writes this value as permission_set in the configuration file generated for this Remote Server. Setting it on Create or Update changes the generated file, not a running Agent. The Agent enforces the permissions in its local configuration file, controlled by the host's system administrator, and reports them at registration, replacing the stored value.

files_agent_rootstring

Agent local root path. Files.com writes this value as root in the configuration file generated for this Remote Server. Setting it on Create or Update changes the generated file, not a running Agent. The Agent enforces the root in its local configuration file, controlled by the host's system administrator, and reports it at registration, replacing the stored value.

files_agent_versionstring

Files.com Agent version reported by the Agent at each registration, replacing the stored value. This field is not included in the generated Agent configuration file. Setting it on Create or Update does not update the running Agent.

files_agent_up_to_dateboolean

If true, the Files Agent is up to date.

files_agent_latest_versionstring

Latest available Files Agent version

files_agent_supports_push_updatesboolean

Files Agent supports receiving push updates

direct_transfer_availableboolean

Whether the Files Agent Proxy recently validated a direct transfer connection. true means a direct connection was recently validated (actual availability can vary by client network), false means direct transfers are enabled but not currently available, and null means direct transfers are disabled or unsupported. Only provided for a connected Files Agent when showing a single Remote Server.

outbound_agent_idinteger

Route traffic to outbound on a files-agent

filebase_bucketstring

Filebase: Bucket name

filebase_access_keystring

Filebase: Access Key.

files_api_key_prefixstring

Files.com direct link: paired API key prefix.

cloudflare_bucketstring

Cloudflare: Bucket name

cloudflare_access_keystring

Cloudflare: Access Key.

cloudflare_endpointstring

Cloudflare: endpoint

dropbox_teamsboolean

Dropbox: If true, list Team folders in root?

linode_bucketstring

Linode: Bucket name

linode_access_keystring

Linode: Access Key

linode_regionstring

Linode: region

supports_versioningboolean

If true, this remote server supports file versioning. This value is determined automatically by Files.com.

Example response

[
  {
    "id": 1,
    "disabled": true,
    "authentication_method": "password",
    "hostname": "remote-server.com",
    "remote_home_path": "/home/user1",
    "upload_staging_path": "/tmp/uploads",
    "allow_relative_paths": true,
    "name": "My Remote server",
    "description": "More information or notes about my server",
    "port": 1,
    "buffer_uploads": "example",
    "max_connections": 1,
    "pin_to_site_region": true,
    "pinned_region": "us-east-1",
    "remote_server_credential_id": 1,
    "s3_bucket": "my-bucket",
    "s3_region": "us-east-1",
    "s3_kms_key_id": "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "aws_access_key": "example",
    "s3_assume_role_arn": "example",
    "s3_assume_role_duration_seconds": 1,
    "s3_assume_role_external_id": "example",
    "server_certificate": "require_match",
    "server_host_key": "[public key]",
    "server_type": "s3",
    "site_admin_access": true,
    "effective_site_admin_access": true,
    "user_id": 1,
    "ssl": "if_available",
    "username": "user",
    "google_cloud_storage_bucket": "my-bucket",
    "google_cloud_storage_authentication_method": "json",
    "google_cloud_storage_oauth_scope": "https://www.googleapis.com/auth/devstorage.read_only",
    "google_cloud_storage_project_id": "my-project",
    "google_cloud_storage_s3_compatible_access_key": "example",
    "backblaze_b2_s3_endpoint": "s3.us-west-001.backblazeb2.com",
    "backblaze_b2_bucket": "my-bucket",
    "wasabi_bucket": "my-bucket",
    "wasabi_region": "us-west-1",
    "wasabi_access_key": "example",
    "auth_status": "in_setup",
    "auth_account_name": "me@example.com",
    "one_drive_account_type": "personal",
    "sharepoint_tenant_id": "00000000-0000-0000-0000-000000000000",
    "sharepoint_client_id": "00000000-0000-0000-0000-000000000000",
    "sharepoint_app_authentication": true,
    "sharepoint_app_credential_type": "secret",
    "sharepoint_site_url": "https://example.sharepoint.com/sites/accounting",
    "azure_blob_storage_account": "storage-account-name",
    "azure_blob_storage_container": "container-name",
    "azure_blob_storage_hierarchical_namespace": true,
    "azure_blob_storage_dns_suffix": "usgovcloudapi.net",
    "azure_files_storage_account": "storage-account-name",
    "azure_files_storage_share_name": "share-name",
    "azure_files_storage_dns_suffix": "file.core.windows.net",
    "s3_compatible_bucket": "my-bucket",
    "s3_compatible_endpoint": "mys3platform.com",
    "s3_compatible_region": "us-east-1",
    "s3_compatible_virtual_hosted_style": true,
    "s3_compatible_access_key": "example",
    "enable_dedicated_ips": true,
    "custom_domain_id": 1,
    "outbound_ip_addresses": [
      "203.0.113.1",
      "203.0.113.2"
    ],
    "files_agent_permission_set": "read_write",
    "files_agent_root": "example",
    "files_agent_version": "example",
    "files_agent_up_to_date": true,
    "files_agent_latest_version": "example",
    "files_agent_supports_push_updates": true,
    "direct_transfer_available": true,
    "outbound_agent_id": 1,
    "filebase_bucket": "my-bucket",
    "filebase_access_key": "example",
    "files_api_key_prefix": "example",
    "cloudflare_bucket": "my-bucket",
    "cloudflare_access_key": "example",
    "cloudflare_endpoint": "https://<ACCOUNT_ID>.r2.cloudflarestorage.com",
    "dropbox_teams": true,
    "linode_bucket": "my-bucket",
    "linode_access_key": "example",
    "linode_region": "us-east-1"
  }
]

Changes

  • 7ba78df2d704Revision changes
    • info

      added the new optional query request parameter user_id

  • 3bb8c8a06041Revision changes
    • info

      api tag Remote Servers added

    • info

      added the new optional query request parameter filter

    • info

      added the new optional query request parameter filter_prefix

    • info

      added the new optional query request parameter sort_by